OAuth 2.0 User Guide

Step 1: Register your app and get OAuth credentials

Before making any API calls, register your application in the Zoho API Console. This one-time setup provides the credentials your app uses to identify itself to the Zoho Authorization Server.

How to register?

1. Go to the Zoho API Console.
2. Click GET STARTED.
3. Hover over and select your client type, then click CREATE NOW. If you have already added an application, click ADD CLIENT in the top-right corner.
   

Choosing a client type

The client type determines the authorization flow your application uses to obtain tokens. Choose based on where your application runs and whether it can securely store a client secret.

4. Enter the below mentioned details based on the choice of client type, then click CREATE. The details required during registration depend on your client type. Use the table below to confirm which fields apply to your application:

After registration, Zoho issues the following credentials for your application:

• Client ID - Unique identifier assigned to your application.
• Client Secret - Confidential key used alongside the Client ID to authenticate your application's token requests. Store it securely and do not expose it in client-side applications or public repositories.

Step 2 : Request authorization code

You (the end-user) or your client application should initiate the authorization process by requesting an authorization code through a GET request to the Zoho authentication server via a web browser. The request must include the required scopes, client_id, response_type, and redirect_uri.

Query Parameters Details :

 * denotes mandatory parameter.

Step 3 : User authorization prompt

In response, the Zoho authentication server will prompt you (the end-user) to authorize the client application to access their data based on the specified scopes.

The screen displays the application name, the requested scopes, and the option to Accept or Deny access.

Step 4 : Grant authorization

• If you (the end-user) click "Accept" in the prompt window,  you authorize the client application to access your Zoho account's resources within the specified scope. Upon acceptance, the Zoho authentication server redirects you to the specified redirect_uri, including the requested authorization code "code" embedded in the URL.

  Sample response format of the URL in which authorization code is received:

  https://{redirect_uri}?code={authorization_code}&location={domain}&accounts-server={accounts_url}

  Example response URL in which authorization code is received:

  https://zylker.com/redirect?code=1000.*******77&location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com

  The client application retrieves the authorization code from the above URL. The authorization code  is valid for 2 minutes.

• If the end user clicks Deny, the server will return an error.

Step 5: Exchange authorization code for access token

The client application should request an access token from the Zoho authentication server by sending a POST request in any API platform like Postman, embedding the authorization code received in the previous step in the URL, along with other necessary details.

Query Parameter Details :

• denotes mandatory parameter.

Step 6 : Zoho server response

The Zoho server responds with an access token (and a refresh token if requested).

You can store this data so that there is no need for authorization each time the end user accesses the registered client application. This completes the authentication.

Step 7 : Access Zoho Mail resources

Once your client application obtains the access token, it can access Zoho's protected resources through Zoho Mail's APIs. When the access token is provided to the Zoho's resource server, your client application will be granted access based on the scopes specified in the request. Zoho's OAuth implementation uses the Bearer authentication scheme. Therefore, the access token must be included in the Authorization header, prefixed with Zoho-oauthtoken, in every API request.

Manage OAuth tokens 

After obtaining and using the access token, your application must manage the token lifecycle to maintain uninterrupted and secure access to Zoho Mail resources. Access tokens have a limited validity period and must be renewed using the refresh token when they expire. When access is no longer required, you can revoke the refresh token to prevent further access.

Renew access token

Access tokens have a limited validity period and, in most cases, expire after one hour (3,600 seconds). Once an access token expires, the client application must use the refresh token to request a new access token for continued access. This process repeats each time the access token expires, ensuring that the refresh token is consistently used to obtain new access tokens. The cycle continues until access is explicitly revoked. Refresh tokens typically have a longer lifespan—ranging from days to months or even years—depending on the authorization server’s policy.

The client application requests a new access token from the Zoho authentication server by sending a POST request, embedding the refresh token from step 6 in the URL, along with other required details.

Query Parameter Details:

• denotes mandatory parameter.

If the request is successful, you will receive the following response:

In response, you have received a new Access Token. This new Access Token will also have an hour(3600 seconds) of time validity. 

Revoke refresh token 

When the client application no longer requires access to Zoho Mail resources, revoke the refresh token to prevent the application from obtaining new access tokens. Access tokens may also be revoked due to logout, expiration, security updates, suspicious activity, or account changes to maintain security.

The client application can request the Zoho authentication server to revoke the refresh token by sending a POST request with the refresh token.