Using OAuth to Access Binance API
Binance APIs use the OAuth 2.0 protocol for authentication and authorization. Binance supports common OAuth 2.0 scenarios such as those for web server, single page (browser based) , and mobile and native applications. In this doc, it will show how your application interacts with Binance's OAuth 2.0 server to obtain user's consensus to perform an API request on the user's behalf.
To begin, your application should identify the needed permissions (scope) firstly. Setup and register your application with Binance Accounts, and get your client_id . For now, please contact us.
Based on your application type, you can choose different authorization flow:
- A web application please refer to Authorization Code Flow
- Browser based Applications, and mobile and native applications, please refer to PCKE Flow.
1. Authorization Code Flow
#
Step 1. Redirect users to request Binance access and set authorization parameters.⚠️ The carriage returns of the above example are only for readability and should be removed in real world, as well as the following examples
When redirecting a user to Binance to authorize access to your application, your first step is to create the authorization request.
Parameters | Description |
---|---|
response_type | Required Value code |
client_id | Required The client ID of your application. |
redirect_uri | required The URL in your web application where users will be redirected after authorization. This value needs to be URL encoded. |
state | Optional The CSRF token to protect against CSRF (cross-site request forgery) attacks. |
scope | required List of scopes enum your application requests access to, with comma (, ) seperated. |
Here is an Example of an authorization URL:
#
Step 2. Binance prompts user for consentIn this step, the user decides whether to grant your application the requested access. At this stage, Binance displays a consent window that shows the name of your application and the Binance API services that it is requesting permission to access with the user's authorization credentials. The user can then consent or refuse to grant access to your application.
Your application doesn't need to do anything at this stage as it waits for Binance's OAuth 2.0 server to redirect back.
#
Step 3. Binance redirects back to your applicationIf the user approves your application, Binance's OAuth server will redirect back to your redirect_uri
with a temporary authorization code
parameter.
If you specified a state
parameter in step 1, the parameter will be included as well. If you generate a random string or encode the hash of a cookie or another value that captures the client's state
, you can validate the response to additionally ensure that the request and response originated in the same browser, providing protection against attacks such as cross-site request forgery.
Example of the redirection:
state
is the same as the one in step 1
#
Step 4. Exchange authorization code for refresh and access tokensAfter your application receives the authorization code
, it can exchange the authorization code
for an access token, which can be done by make a POST call:
Parameter | Description |
---|---|
grant_type | required Value authorization_code |
code | required Step3 return code |
client_id | required The client ID of your application. |
client_secret | required The client secret of your application. |
redirect_uri | required The URL in your web application where users will be redirected after authorization. This value needs to be URL encoded. |
Example POST call:
After a successful request, a valid access_token
will be returned in the response.
Here is an example response:
2. PKCE Flow
The PKCE extension prevents an attack where the authorization code is intercepted and exchanged for an access token by a malicious client, by providing the authorization server with a way to verify the same client instance that exchanges the authorization code is the same one that initiated the flow. For more details, refer to https://tools.ietf.org/html/rfc7636
#
Step 1. Redirect users to request Binance access and set authorization parameters.⚠️ The carriage returns of the above example are only for readability and should be removed in real world, as well as the following examples
When redirecting a user to Binance to authorize access to your application, your first step is to create the authorization request. You need create and store a new PKCE code_verifier, also will be used in STEP4 Here is an Example of javascript generate code_verifier
Parameters | Description |
---|---|
response_type | Required Value code |
client_id | Required The client ID of your application. |
redirect_uri | required The URL in your web application where users will be redirected after authorization. This value needs to be URL encoded. |
state | Optional The CSRF token to protect against CSRF (cross-site request forgery) attacks. |
scope | required List of scopes enum your application requests access to, with comma (, ) seperated. |
code_challenge | required Hash and base64-urlencode of code_verifier |
Here is an Example of javascript generate code_challenge
Here is an Example of an authorization URL:
#
Step 2. Binance prompts user for consentIn this step, the user decides whether to grant your application the requested access. At this stage, Binance displays a consent window that shows the name of your application and the Binance API services that it is requesting permission to access with the user's authorization credentials. The user can then consent or refuse to grant access to your application.
Your application doesn't need to do anything at this stage as it waits for Binance's OAuth 2.0 server to redirect back.
#
Step 3. Binance redirects back to your applicationIf the user approves your application, Binance's OAuth server will redirect back to your redirect_uri
with a temporary authorization code
parameter.
If you specified a state
parameter in step 1, the parameter will be included as well. If you generate a random string or encode the hash of a cookie or another value that captures the client's state
, you can validate the response to additionally ensure that the request and response originated in the same browser, providing protection against attacks such as cross-site request forgery.
Example of the redirection:
state
is the same as the one in step 1
#
Step 4. Exchange authorization code for refresh and access tokensAfter your application receives the authorization code
, it can exchange the authorization code
for an access token, which can be done by make a POST call:
Parameter | Description |
---|---|
grant_type | required Value authorization_code |
code | required Step3 return code |
client_id | required The client ID of your application. |
code_verifier | required The random secret code created and stored in STEP1 |
redirect_uri | required The URL in your web application where users will be redirected after authorization. This value needs to be URL encoded. |
Example POST call:
After a successful request, a valid access_token
will be returned in the response.
Here is an example response:
#
Step 5. Calling Binance APIsAfter you have a valid access_token
, you can make your first API call:
Response: