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. If you have already added an application, click ADD CLIENT in the top-right corner.
3. Choose your client type and click CREATE NOW.
   

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.

Client type and authorization flow

The table below summarizes the authorization flow for each client type. Select the link for your client type above for the complete setup steps.

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:

Field descriptions

Credentials issued

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

• Client ID: A public identifier for your application.

• Client Secret: A private key used to authenticate your app’s token requests. Keep this confidential and never expose it in client-side code.

Step 2 : Requesting 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.

Step 4 : Granting 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: Exchanging 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 : Accessing 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.

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 

Access tokens are revoked on logout, expiration, security updates, suspicious activity, or account changes to maintain security.

The client application requests that the Zoho authentication server revoke the refresh token by sending a POST request to the API platform, embedding the refresh token received in step 6 in the URL, along with other necessary details.