Step 5: Get new access token using refresh token

The authorization server issues the refresh tokens along with the access tokens. These tokens are issued to generate new access tokens when the current access token becomes invalid or expires. Unlike the access tokens, the refresh tokens are optional and only obtained when you when you set the access-type parameter to offline in the authorization code request. However, refresh tokens aren't passed to resource servers along with API requests, they are permitted to be used only with authorization server.

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 a request to generate a new access token from the refresh token using https://accounts.zoho.com.

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

Endpoints

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,

1000.682FCGL9IO0XAAQY7904YOBT4IHGYL

client_secret stringrequired

Indicates the client secret of your web application. This parameter helps to authentication your application with the Bigin authorization server.

For example,

bb4169344ea3ef804d96531f8de0ca7a8b6fb7d8dd

refresh_token stringrequired

A key token that is used to generate new access token without user consent.

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

grant_type stringrequired

The grant_type lets the authorization server know about the type of authorization request. As your application is requesting for a new access token from a refresh token, always specify the value as refresh_token for this parameter.

Sample request

Copiedcurl -X POST "https://accounts.zoho.com/oauth/v2/token?refresh_token=1000.921fa5d2ba9dd1ffd8a9cfd9f043e6e8.28460fe08194a390ac11fb8865ad1572&client_id=1000.682FCGL9IO0XAAQY7904YOBT4IHGYL&client_secret=bb4169344ea3ef804d96531f8de0ca7a8b6fb7d8dd&grant_type=refresh_token"

Copiedpayload = Map();
payload = put.("client_id","1000.682FCGL9IO0XAAQY7904YOBT4IHGYL");
payload = put.("client_secret","bb4169344ea3ef804d96531f8de0ca7a8b6fb7d8dd");
payload = put.("grant_type","refresh_token");
payload = put.("refresh_token","1000.921fa5d2ba9dd1ffd8a9cfd9f043e6e8.28460fe08194a390ac11fb8865ad1572");

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.

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

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.

What's next!

Step 6: Revoke refresh tokens ➔

Sample JSON response

Copied{
    "access_token": "1000.6dcd0011b81811a1ceb7ae3e456caecd.621bfaf140bf73d91180ac4fa6af1e67",
    "scope": "ZohoBigin.settings.modules.READ",
    "api_domain": "https://www.zohoapis.com",
    "token_type": "Bearer",
    "expires_in": 3600
}