BORA Lagoon

Authorization APIs

This document provides examples and APIs for how to apply OAuth 2.0 authentication and authorization to access the BORA API. To learn more about OAuth2.0, please see https://oauth.net/2/.

OAuth2.0 for BORA Platform Client

In order for content providers to pay users BORA Shell, they need to know the content provider's address and the user's address. To do this, you need to be able to get the address, or control the part that pays the BORA Shell through the appropriate authorization method. The BORA Platform has proved to be reliable in solving this problem and has adopted the widely used OAuth2.0 authorization method.To use the BORA API, Authorization code and Client Credential method of OAuth2.0 grant type are used. The Access Token obtained by Authorization Code method (hereinafter referred to as "User Access Token") is used for transactions originating from users who use content, and the Access Token obtained by Client Credential method (hereinafter referred to as "Client Access Token") is used for transactions originating from the content provider's address.For example, if a content provider and a user play a game, and the user wins and points flow from the content provider's address to the user's address, the Client Access Token is used. On the other hand, if the content provider wins and needs to get points from the user's address, the User Access Token is used. On the same principle, when a transaction occurs between users who use the content, the User Access Token of the user who has to pay is used.All authentication requests require client Basic authentication information. The authentication information includes client_id and client_secret, which is the same as the ID and password for login. Therefore, it should never be exposed to the outside. It is recommended to call from server side as much as possible to prevent exposure. In addition, the BORA platform does not support CORS for authentication request URIs, so you can not request authentication in your browser environment.

Client Credentials Grant Flow

To understand Client Credentials Grant Flow, please see the diagram.

1Access the Request Authentication Code page

POST /member/oauth/token
Authorization: Basic {client_basic_auth}
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
HOST: accounts.boraecosystem.com

// Note: {client_basic_auth} means Base64-encoded value of "client_id:client_secret".
// Example:
curl -d "grant_type=client_credentials" -H "Authorization: Basic dGVzdDp0ZXN0MTIzNA" -X POST https://accounts.boraecosystem.com/member/oauth/token

Parameters

Parameter	Required	Values	Description	Parameter Type	Data Type
Authorization	*		Client Basic authorization information	header	string
grant_type	*	client_credentials	Response type (must be "client_credentials")	formData	string

Response

{
 "access_token": "d4c0eecb-4c01-4ef1-94fd-669d227aa625", 
 "token_type": "bearer", 
 "expires_in": 79684, 
 "scope": "user email gauction", 
 "app_no": 100004 
 }

Authorization Code Grant Flow

To help you understand the Authorization Code Grant flow and how to use the API, please see the diagram below.

1Access authorization code request page

GET /member/oauth/authorize?response_type=code&client_id={client_id}&state={state}
&redirect_uri={redirect_uri}
HOST: accounts.boraecosystem.com

// Example:
Move to: https://accounts.boraecosystem.com/member/oauth/authorize?response_type=code&client_id=X0yT6nI69Q&state=hLiDdL2uhPtsftcU&redirect_uri=https://localhost/code

In the case of requiring authentication of the user, the content provider will have the user to follow the link to the web page of authentication that is provided by BORA (Above example URL) and then the user will enter the ID and Password of BORA and proceed for authentication. Upon completion of the authentication, corresponding code and value of state will be transfer via designated redirect_uri. Redirect-URI is the server URI of the content provider which will process both corresponding code and state. In this process of issuing client-id, only the permitted URL is allowed. It is recommended to utilize the value of state to prevent CSRF attack.

Parameters

Parameter	Required	Values	Description	Parameter Type	Data Type
response_type	*	code	Response type (must be "code")	query	string
client_id	*		Client Id	query	string
state			CSRF protection token	query	string
client_id	*		Redirect URI	query	string

Response

Send Authorization code in "GET /{redirect_uri}?code=xxxx" format

// Example:
If redirect_uri is "http://localhost/code", code and state values are sent to the content provider's page in the form of "http://localhost/code?code=HBua25&state=hLiDdL2uhPtsftcU"

2Request Access Token

POST /member/oauth/token
 Authorization: Basic {client_basic_auth}
 Content-Type: application/x-www-form-urlencoded
 grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}
 HOST: accounts.boraecosystem.com

// Example:
// Call the API that issues the access token using the code received above. At this time, redirect_uri is transmitted to process the issued Access Token.curl -d "grant_type=authorization_code&code=HBua25&redirect_uri=http://localhost/token" -H "Authorization: Basic dGVzdDp0ZXN0MTIzNA" -X POST https://accounts.boraecosystem.com/member/oauth/token

Parameters

Parameter	Required	Values	Description	Parameter Type	Data Type
Authorization	*		Client Basic authorization information	header	string
grant_type	*	authorization_code	Authorization type (must be "authorization_code")	formData	string
code	*		The access token request code (Authorization Code) formData	formData	string
redirect_uri	*		Redirect URI	formData	string

Response

{
 "access_token": "b409ebbf-6077-4f60-b961-3d5962ff1e26",
 "token_type": "bearer",
 "refresh_token": "275c574b-4e41-4053-9e83-fca53dccaxxx",
 "expires_in": 86399,
 "scope": "user email gauction",
 "app_no": 100004,
 "member_no": 1
 "username": "test@boraecosystem.com"
 }

Access token validation

Access Token expires 24 hours after issue. You can use this API if the Access Token is expired or if it is valid.

Request validation

 GET /member/oauth/check_token?token={access_token}
 Authorization: Basic {client_basic_auth}
 HOST: accounts.boraecosystem.com

 // Example:
 curl -H "Authorization: Basic dGVzdDp0ZXN0MTIzNA" -X POST https://accounts.boraecosystem.com/member/oauth/check_token?token=b409ebbf-6077-4f60-b961-3d5962ff1e26

Parameters

Parameter	Required	Values	Description	Parameter Type	Data Type
Authorization	*		Client Basic authorization information	header	string
token	*		Access Token	query	string

Response

 {
 "member_no": 1,
 "scope": "user email gauction",
 "active": true,
 "app_no": 100004,
 "exp": 1539665602,
 "client_id": "X0yT6nI69Q",
 "username": "test@boraecosystem.com"
 }

Refresh Access Token

You can use a Refresh Token to obtain a new Access Token even after the old one expires.

Request refreshment

POST /member/oauth/token
Authorization: Basic {client_basic_auth}
grant_type=refresh_token&refresh_token={refresh_token}
HOST: accounts.boraecosystem.com

// Example:
// Use refresh token to obtain a new one.
curl -d "grant_type=refresh_token&refresh_token=275c574b-4e41-4053-9e83-fca53dccaxxx" -H "Authorization: Basic dGVzdDp0ZXN0MTIzNA" -X POST https://accounts.boraecosystem.com/member/oauth/token

Parameters

Parameter	Required	Values	Description	Parameter Type	Data Type
Authorization	*		Client Basic authorization information	header	string
grant_type	*	refresh_token	Authorization type (must be "refresh_token")	formData	string
refresh_token	*		Refresh Token	formData	string

Response

{
"access_token": "37f07130-19ce-47db-a7a5-d635476958a6",
"token_type": "bearer",
"refresh_token": "275c574b-4e41-4053-9e83-fca53dccaxxx",
"expires_in": 86399,
"scope": "user email gauction",
"app_no": 100004,
"member_no": 1,
"username": "test@boraecosystem.com"
}

Error Response

If HTTP Status 400 error (bad request) occurs, the API responds in the following format.

Response

// If 400 Error
{
 "error": "invalid_token",
 "error_description": "Token was not recognised"
}

Other errors such as the following may occur.

에러 코드

Values	Description
invalid_request	The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
invalid_token	The access token provided is expired, revoked, malformed, or invalid for other reasons.
invalid_grant	The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
unauthorized_client	The client is not authorized to request an authorization code or access token using this method.
unsupported_response_type	The authorization server does not support obtaining an authorization code or access token using this method.
redirect_uri_mismatch	The redirect URI in the request does not match the URIs authorized for the client.

Other errors such as the following may occur.

Error Code

HTTP Code	Description
401	Unauthorized: The request requires user authentication.
403	Fobbiden: The URI is not allowed access.
404	Not Found: No URLs or the result does not exist.
500	Internal Server Error: This is an error on the authentication server. Please contact the BORA team.

Inquiries, bug reports and feedback
about BORA Lagoon are very helpful to us.
Please communicate actively through
our community channel.

Send Email