Step 2: Get access tokens using authorization code

The self client must obtain an access token to authenticate API requests that are sent to the Bigin server. The Bigin authorization server approves the client's request to exchange the authorization code with an access token or access and refresh token pair that appears as a string and consists of specific scope, lifetime and other access properties. While making requests to access protected resources in Bigin, you must pass the access token as a bearer token.

Request URL

{accounts-server}/oauth/v2/token

You must use domain-specific accounts URL to generate access and refresh tokens. Based on the domain location of the user, you should replace {accounts-server} with any of the following domain-specific accounts URL:

For US, https://accounts.zoho.com
For AU, https://accounts.zoho.com.au
For EU, https://accounts.zoho.eu
For IN, https://accounts.zoho.in
For CN, https://accounts.zoho.com.cn
For JP, https://accounts.zoho.jp

For example, if the user's domain location is US, you should make an access token request using https://accounts.zoho.com.

Endpoint

POST /token

Request parameters

In the sample request, we used request parameters as query parameters so that you can try our API. In the real time scenario, we recommend you to pass the request parameters in the request body as form-data.

The request parameters are given below:

client_id stringrequired

Indicates the client identifier of the registered self client. This parameter helps the Bigin authorization server to identify a client who is requesting a new access token.

For example,

client_id=1000.682FCGL9IO0XAAQY7904YOBT4IHGYL

client_secret stringrequired

Indicates the client secret of the registered self client. This parameter helps to authenticate your registered self client with the Bigin authorization server.

For example,

client_secret=bb4169344ea3ef804d96531f8de0ca7a8b6fb7d8dd

code stringrequired

This code exchanges with the Bigin authorization server for key access tokens. Copy and paste the authorization code that is generated in Step 1: Generate authorization code.

For example,

code=1000.aa75abd2cd57603af9cd152be0a4a724.681a79ac0ad10a7c66713be8dbbe8541

grant_type stringrequired

The grant_type lets the authorization server know about the type of authorization grant. As your registered self client is using the authorization code grant type, always specify the value as authorization_code for this parameter.

For example,

grant_type=authorization_code

Sample request

Copiedcurl -X POST "https://accounts.zoho.com/oauth/v2/token?client_id=1000.682FCGL9IO0XAAQY7904YOBT4IHGYL&client_secret=bb4169344ea3ef804d96531f8de0ca7a8b6fb7d8dd&code=1000.7fc735ed53b27aa3f31ab0da694cb844.0dbcf8f045ef51578be78b136e974e66&grant_type=authorization_code"

Response object

The response object contains the following details:

access_token string

A temporary key token that is used to access Bigin resources. You can add the access token value to the authorization header of all Bigin APIs.

Note: This value is valid up to 1 hour and must be used only for the operations defined in the scope.

refresh_token string

A key token that is used to generate new access tokens.

Note:
There is no expiry time limit for refresh tokens. You can generate up to five refresh tokens in a minute.

api_domain string

The Domain name of Bigin APIs. You can use this domain name to access Bigin resources.

token_type string

The type of token obtained. It'll be Bearer for access tokens.

expires_in number

The number of seconds after which the access token expires.

Possible errors

The response of this resource includes HTTP status and error codes.

The most common errors that occur when you request access to this endpoint are given in the following:

invalid_client 200 OK

Reason 1: Invalid Client ID or Client secret is passed

Resolution: Provide a valid Client ID and Client secret.

Reason 2: Domain mismatch

Resolution: Generate access/refresh token pair from the same domain using the same domain URL.

invalid_code 200 OK

Reason 1: The Authorization code is expired

Resolution: The authorization code is valid only for the specified time duration. Generate the access and refresh tokens before the authorization code expires.

Reason 2: The Authorization code is reused

Resolution: Use the authorization code only once. If you have already used the authorization code once, generate the new code and then request for access tokens.

Reason 3: Invalid or revoked refresh token is passed

Resolution: Provide the valid refresh token while refreshing an access token.

What's next

Step 4: Use access tokens in API requests ➔

Sample JSON response

Copied{
    "access_token": "1000.c9a82de89509322214a396bc666388a8.95d91b2e5b1cd1570346adf30c8a8ea7",
    "refresh_token": "1000.1c22b605bebf0c0ce535590352110f2a.276ce629b4789681eabe632ca0d572fe",
    "api_domain": "https://www.zohoapis.com",
    "token_type": "Bearer",
    "expires_in": 3600
}