Step 3: Generate Access and Refresh Tokens

OAuth2.0 requests are usually authenticated with an access token, which is passed as bearer token. To use this access token, you need to construct a normal HTTP request and include it in an Authorization header along with the value of Bearer.

You must use your domain-specific Zoho Accounts URL to generate access and refresh tokens. The following are the various domains and their corresponding accounts URLs.

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

To generate access and refresh tokens:

Make a POST request with the following URL. Replace {Accounts_URL} with your domain-specific Zoho accounts URL when you make the request.

{Accounts_URL}/oauth/v2/token

Note: For security reasons, pass the below parameters in the body of your request.

To invoke OAuth generation via Postman, you need to download and import the JSON files as listed below.

Request Parameters

Parameter	Data Type	Description
Mandatory Parameters
grant_type	String	Enter grant_type = authorization_code.
client_id	String	Your client_id that is found in Zoho Developer console.
client_secret	String	Your client_secret that is found in Zoho Developer console.
redirect_uri	String	The Callback URL that was provided during the App registration.
code	String	Specify the grant token generated in Step 2.

If the request is successful, you would receive the following:

{

"access_token": "{access_token}",

"refresh_token": "{refresh_token}",

"api_domain": "https://www.zohoapis.com",

"token_type": "Bearer",

"expires_in": 3600

}

Response Parameters

Parameter	Description
access_token	Access token to access ZohoWriter APIs
refresh_token	Used to obtain a new access token after the old one expires. A refresh token does not expire. The maximum number of allowed refresh tokens per account is 20. The 21st refresh token will replace the first created refresh token.
expires_in	Time in seconds after which the access token expires
api_domain	Domain name of the API. Use this domain in your requests to make API calls to Zoho Writer.
token_type	Type of token obtained. "Bearer" indicates this is an access token.

This completes the authentication. Once your app receives the access token, send the token in your HTTP authorization header to Zoho Writer API with the value "Zoho-oauthtoken {access_token}" for each endpoint (for each request).

Note

Each access token is valid for only an hour and used only for the operations defined in the scope.
Refresh token does not expire. Use it to refresh access tokens when they expire.
You can only generate a maximum of five refresh tokens in a minute.
Here is avideo explaining how to generate access and refresh tokens.
Using a refresh token a client can create up to ten access tokens in a span of ten minutes. If the limit is reached, the access token creation will be blocked for the rest of the ten minutes.
You can save the refresh and access tokens and reuse them.

Possible Errors

Error	Reason	Resolution
invalid_client	You have passed an invalid Client ID or secret. Domain mismatch. You have registered the client and generated the grant token in a certain domain (US), but generating the tokens from a different domain (EU). You have passed the wrong client secret when multi-DC is enabled. .	Specify the correct client ID and secret. Ensure that you generate the grant, access, and refresh tokens from the same domain using the same domain URL (or) Enable Multi-DC for your client to generate tokens from any domain. Each DC holds a unique client secret. Ensure to pass the right client secret for that DC.
invalid_code	The grant token has expired. You have already used the grant token. The refresh token to generate a new access token is wrong or revoked. .	The grant token is valid only for one minute in the redirection-based flow. Generate the access and refresh tokens before the grant token expires. You can use the grant token only once. Specify the correct refresh token value while refreshing an access token.
invalid_redirect_uri	The redirect URI in the request mismatches the one registered in the developer console.	Specify the correct redirect URI in the request.