Skip to main content

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, Binance Login(Oauth2.0), is only provided to close ecosystem partners now. Please reach to our business team for more details.

Based on your application type, you can choose different authorization flow:

  1. A web application please refer to Authorization Code Flow
  2. 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.#

GET https://accounts.binance.com/en/oauth/authorize?    response_type=code&    client_id=YOUR_CLIENT_ID&    redirect_uri=YOUR_REDIRECT_URI&    state=CSRF_TOKEN&    scope=SCOPES

⚠️ 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.

ParametersDescription
response_typeRequired Value code
client_idRequired The client ID of your application.
redirect_urirequired The URL in your web application where users will be redirected after authorization. This value needs to be URL encoded.
stateOptional The CSRF token to protect against CSRF (cross-site request forgery) attacks.
scoperequired List of scopes enum your application requests access to, with comma (,) seperated.

Here is an Example of an authorization URL:

GET https://accounts.binance.com/en/oauth/authorize?    response_type=code&    client_id=a28f296f2cbe6c64b4d5dec24735d39b1b6fffcf&    redirect_uri=https%3A%2F%2Fdomain.com%2Foauth%2Fcallback&    state=377f36a4557ab5935b36&    scope=user:email,user:address

Step 2. Binance prompts user for consent#

In 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 application#

If 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:

GET https://domain.com/oauth/callback?    code=cf6941ae8918b6a008f1377f36a4557ab5935b36&    state=377f36a4557ab5935b36

state is the same as the one in step 1

Step 4. Exchange authorization code for refresh and access tokens#

After 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:

POST https://accounts.binance.com/oauth/token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&code=STEP3_CODE&redirect_uri=YOUR_REDIRECT_URI
ParameterDescription
grant_typerequired Value authorization_code
coderequired Step3 return code
client_idrequired The client ID of your application.
client_secretrequired The client secret of your application.
redirect_urirequired The URL in your web application where users will be redirected after authorization. This value needs to be URL encoded.

Example POST call:

curl https://accounts.binance.com/oauth/token \  -X POST  -d 'client_id=je-client&client_secret=je-client-secret&grant_type=authorization_code&code=95OfIm&redirect_uri=https%3A%2F%2Fdomain.com%2Foauth%2Fcallback'

After a successful request, a valid access_token will be returned in the response.

Here is an example response:

{  "access_token": "83f2bf51-a2c4-4c2e-b7c4-46cef6a8dba5",  "refresh_token": "fb5587ee-d9cf-4cb5-a586-4aed72cc9bea",  "scope": "read",  "token_type": "bearer",  "expires_in": 30714}

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.#

GET https://accounts.binance.com/en/oauth/authorize?    response_type=code&    client_id=YOUR_CLIENT_ID&    redirect_uri=YOUR_REDIRECT_URI&    state=CSRF_TOKEN&    scope=SCOPES&    code_challenge=CODE_CHALLENGE&    code_challenge_method=S256

⚠️ 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

// Generate a secure random string using the browser crypto functionsfunction generateRandomString() {  var array = new Uint32Array(28);  window.crypto.getRandomValues(array);  return Array.from(array, (dec) => ("0" + dec.toString(16)).substr(-2)).join(    ""  );}
ParametersDescription
response_typeRequired Value code
client_idRequired The client ID of your application.
redirect_urirequired The URL in your web application where users will be redirected after authorization. This value needs to be URL encoded.
stateOptional The CSRF token to protect against CSRF (cross-site request forgery) attacks.
scoperequired List of scopes enum your application requests access to, with comma (,) seperated.
code_challengerequired Hash and base64-urlencode of code_verifier

Here is an Example of javascript generate code_challenge

// Calculate the SHA256 hash of the input text.function sha256(code_verifier) {  const encoder = new TextEncoder();  const data = encoder.encode(code_verifier);  return window.crypto.subtle.digest("SHA-256", data);}
// Base64-urlencodes the input stringfunction base64urlencode(hashed) {  return btoa(String.fromCharCode.apply(null, new Uint8Array(hashed)))    .replace(/\+/g, "-")    .replace(/\//g, "_")    .replace(/=+$/, "");}
// Return the base64-urlencoded sha256 hash for the PKCE challengeasync function generateCodeChallenge(code_verifier) {  hashed = await sha256(code_verifier);  return base64urlencode(hashed);}

Here is an Example of an authorization URL:

GET https://accounts.binance.com/en/oauth/authorize?    response_type=code&    client_id=a28f296f2cbe6c64b4d5dec24735d39b1b6fffcf&    redirect_uri=https%3A%2F%2Fdomain.com%2Foauth%2Fcallback&    state=377f36a4557ab5935b36&    scope=user:email,user:address&    code_challenge=ARU184muFVaDi3LObH5YTZSxqA5ZdYPLspCl7wFwV0U    code_challenge_method=S256

Step 2. Binance prompts user for consent#

In 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 application#

If 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:

GET https://domain.com/oauth/callback?    code=cf6941ae8918b6a008f1377f36a4557ab5935b36&    state=377f36a4557ab5935b36

state is the same as the one in step 1

Step 4. Exchange authorization code for refresh and access tokens#

After 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:

POST https://accounts.binance.com/oauth/token?client_id=YOUR_CLIENT_ID&code_verifier=STEP1_CODE_VERIFIER&grant_type=authorization_code&code=STEP3_CODE&redirect_uri=YOUR_REDIRECT_URI
ParameterDescription
grant_typerequired Value authorization_code
coderequired Step3 return code
client_idrequired The client ID of your application.
code_verifierrequired The random secret code created and stored in STEP1
redirect_urirequired The URL in your web application where users will be redirected after authorization. This value needs to be URL encoded.

Example POST call:

curl https://accounts.binance.com/oauth/token \  -X POST  -d 'client_id=je-client&code_verifier=65a4ecce1fe857067bec7a6887529531831ebe38e32da95fe0f322a2&grant_type=authorization_code&code=95OfIm&redirect_uri=https%3A%2F%2Fdomain.com%2Foauth%2Fcallback'

After a successful request, a valid access_token will be returned in the response.

Here is an example response:

{  "access_token": "83f2bf51-a2c4-4c2e-b7c4-46cef6a8dba5",  "refresh_token": "fb5587ee-d9cf-4cb5-a586-4aed72cc9bea",  "scope": "read",  "token_type": "bearer",  "expires_in": 30714}

Step 5. Calling Binance APIs#

After you have a valid access_token, you can make your first API call:

curl https://accounts.binance.com/oauth-api/user-info?access_token=xxx

Response:

{  "code": "000000",  "message": null,  "data": {    "userId": "e10e20b7f20947e7bd206b15ce3dae90",    "email": "xx@xx.com"  },  "success": true}