Step 3: Get access tokens using authorization code

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

You can refer to the user's domain location from the redirect URI response.

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 your web application. 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 your web application. This parameter helps to authenticate your application 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 given as code in the redirect URI.

For example,

code=1000.aa75abd2cd57603af9cd152be0a4a724.681a79ac0ad10a7c66713be8dbbe8541

redirect_uri stringrequired

An Authorized Redirect URI is specified during the registration of your application with the authorization server.

For example,

redirect_uri=https://www.yourdomain.com/callback

grant_type stringrequired

The grant_type lets the authorization server know about the type of authorization grant. As your application 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&redirect_uri=https://www.yourdomain.com/callback&grant_type=authorization_code"

Copiedpayload = Map();
payload = put.("client_id","1000.682FCGL9IO0XAAQY7904YOBT4IHGYL");
payload = put.("client_secret","bb4169344ea3ef804d96531f8de0ca7a8b6fb7d8dd");
payload = put.("code","1000.7fc735ed53b27aa3f31ab0da694cb844.0dbcf8f045ef51578be78b136e974e66");
payload = put.("redirect_uri","https://www.yourdomain.com/callback");
payload = put.("grant_type","authorization_code");

response = invokeurl
[
	url : "https://accounts.zoho.com/oauth/v2/token"
	type : POST
	parameters : payload.toStrings()
	connection : "connection_link_name"
];
info response;

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 without user consent.

Notes:
The refresh token only generates when you set the access-type parameter to offline in the authorization code request.
There is no expiry time limit for refresh tokens. You can generate up to five access tokens in a minute.

scope string

A space-delimited list of scopes that are associated with the access token.

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 the authorization code and access/refresh token pair from the same domain using the same domain URL. Alternatively, enable multi-dc for your application to generate tokens from any domain.

Reason 3: An invalid client secret is passed when multi-dc is enabled for your application

Resolution: When multi-dc is enabled, each data center has a separate client secret. Make sure to pass the valid client secret to the correct data center.

invalid_code 200 OK

Reason 1: The Authorization code is expired

Resolution: The authorization code is valid only for one minute in the redirection-based flow. Generate the access and refresh tokens before the grant token 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.

Reason 4: Redirect URI mismatch

The redirect URI in the request mismatches the one registered in the developer console.

Resolution: Provide the same redirect URI you've specified while registering your application in the API console.

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",
    "scope": "ZohoBigin.modules.READ ZohoBigin.modules.CREATE ZohoBigin.modules.UPDATE ZohoBigin.modules.DELETE",
    "api_domain": "https://www.zohoapis.com",
    "token_type": "Bearer",
    "expires_in": 3600
    }