DOCUMENTS

Documents of the BORA project.

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

ParameterRequiredValuesDescriptionParameter TypeData Type
Authorization*Client Basic authorization informationheaderstring
grant_type*client_credentialsResponse type (must be "client_credentials")formDatastring

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

ParameterRequiredValuesDescriptionParameter TypeData Type
response_type*codeResponse type (must be "code")querystring
client_id*Client Idquerystring
stateCSRF protection tokenquerystring
client_id*Redirect URIquerystring

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

ParameterRequiredValuesDescriptionParameter TypeData Type
Authorization*Client Basic authorization informationheaderstring
grant_type*authorization_codeAuthorization type (must be "authorization_code")formDatastring
code*The access token request code (Authorization Code) formDataformDatastring
redirect_uri*Redirect URIformDatastring

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

ParameterRequiredValuesDescriptionParameter TypeData Type
Authorization*Client Basic authorization informationheaderstring
token*Access Tokenquerystring

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

ParameterRequiredValuesDescriptionParameter TypeData Type
Authorization*Client Basic authorization informationheaderstring
grant_type*refresh_tokenAuthorization type (must be "refresh_token")formDatastring
refresh_token*Refresh TokenformDatastring

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.

에러 코드

ValuesDescription
invalid_requestThe request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
invalid_tokenThe access token provided is expired, revoked, malformed, or invalid for other reasons.
invalid_grantThe 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_clientThe client is not authorized to request an authorization code or access token using this method.
unsupported_response_typeThe authorization server does not support obtaining an authorization code or access token using this method.
redirect_uri_mismatchThe 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 CodeDescription
401Unauthorized: The request requires user authentication.
403Fobbiden: The URI is not allowed access.
404Not Found: No URLs or the result does not exist.
500Internal Server Error: This is an error on the authentication server. Please contact the BORA team.