Authentication

1. Register your application

The first step in using OAuth is to register your client application with the Zoho API console. After registration, you will receive a Client ID and Client Secret. These are used to authorize the application's OAuth requests.

To register,

• Go to the Zoho Developer Console.
• In the Zoho API Console page, click on GET STARTED.
• Choose the type of third-party client application that is being registered:
• Client-based applications: Applications that run exclusively on a browser and are independent of a web server.
• Server-Based applications: Applications that are clients running on a dedicated HTTP server.
• Mobile-based applications: Applications that are installed on smartphones and tablets.
• Non-browser mobile applications: Applications for devices without browser provisioning such as smart TVs and printers.
• Self Client: These are stand-alone applications that perform back-end tasks, like data synchronization, without any manual intervention.

For more details, refer here.

Steps to register a server-based application:

Enter the following details:

• Client Name: The name of the client application you want to register with Zoho.
• Homepage URL: The URL of the client application's webpage.
• Authorized redirect URIs: A valid URL of the client application where Zoho Accounts sends you an authorization code after successful authentication.

• Click CREATE.

You will be provided with the Client ID and the Client secret. Using these credentials, you can go ahead with the OAuth 2.0 authentication.

2. Generating authorization code

The next step is to get an authorization code. For this, you will have to call the following Authorization URL with the mentioned query parameters

https://accounts.zoho.com/oauth/v2/auth?scope={scope}&client_id={client_id}&response_type=code&access_type={offline or online}&redirect_uri={redirect_uri}

Parameter	Description
scope	SCOPE for which the token is to be generated. Multiple scopes can be given, which have to be separated by commas. Ex : logs360cloud.logs.READ
client_id	Client ID obtained during client registration
response_type	code
redirect_uri	One of the redirect URLs given in the above step. This parameter should be the same redirect URL mentioned while registering the Client.
access_type	The allowed values are offline and online. By default, it is set to online. Online Gives your application an access token that is valid for one hour.Offline Gives your application both an access token and a refresh token.

When you make this request, you'll see a "user consent page". Once you click "Accept", Zoho will redirect you to the specified redirect_uri with the code and state parameters.

https://{your_domain}.com/{your_redirect_page}?code={authorization_code}&location={domain}&accounts-server={accounts_url}

This code value is required for obtaining the access token in the next step, and it remains valid for 60 seconds. If you click "Deny", the server will return an error.

3. Generate access and refresh token

Zoho's OAuth implementation uses the Bearer authentication scheme. This means that when making API calls, the access token has to be passed in the Authorization header with the prefix "Zoho-oauthtoken".

To generate an access and refresh token, make a POST request with the following URI.

After getting code by following the above step, make a POST request for the following

https://accounts.zoho.com/oauth/v2/token?code={authorization_code}&grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}

Parameter	Description
code	code code obtained from the above step
client_id	Client ID obtained during Client Registration
client_secret	Client secret obtained during Client Registration
redirect_uri	This parameter should be the same redirect URL mentioned while adding a client.
grant_type	authorization_code

In the response, you will get both access_token and refresh_token.

1. The access_token will expire after a particular period (as mentioned in expires_in parameter in the response).

2. The refresh_token is permanent and will be used to regenerate new access_token, if the current access token is expired.

Note: Each time a re-consent page is accepted, a new refresh token is generated. The maximum limit is 20 refresh tokens per user. If this limit is crossed, the first refresh token is automatically deleted to accommodate the latest one. This is done irrespective of whether the first refresh token is in use or not.

4. Generate Access Token From Refresh Token

Access Tokens have limited validity. In most general cases, the access tokens expire in one hour. Until then, the access token has unlimited usage. Once it expires, your app will have to use the refresh token to request a new access token. Redirect to the following POST URL with the given parameters to get a new access token

https://accounts.zoho.com/oauth/v2/token?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token

Parameter	Description
refresh_token	REFRESH TOKEN, obtained from the above step
client_id	Client ID obtained during Client registration
client_secret	Client secret obtained during Client registration
grant_type	refresh_token

5. Revoking a Refresh Token

To revoke a refresh token, call the following POST URL with the given parameters

https://accounts.zoho.com/oauth/v2/token/revoke?token={refresh_token}

Parameter	Description
token	REFRESH TOKEN which is to be revoked