OAuth

Zoho REST APIs uses the OAuth 2.0 protocol to authorize and authenticate calls. It provides secure access to protect resources thereby reducing the hassle of asking for a username and password everytime a user logs in. Follow the steps listed here, to access Zoho’s APIs using OAuth 2.0

Step 1: Registering New Client

You will have to first register your application with Zoho's Developer console in order get your Client ID and Client Secret.

To register your application, go to https://accounts.zoho.com/developerconsole and click on Add Client ID. Provide the required details to register your application.

On successful registration, you will be provided with a set of OAuth 2.0 credentials such as a Client ID and Client Secret that are known to both Zoho and your application. Do not share this credentials anywhere.

Step 2: Generating Grant Token

Redirect to the following authorization URL with the given params

https://accounts.zoho.com/oauth/v2/auth?

Parameter	Description
scope ^*	Scope for which the token has to be generated, e.g.`ZohoDirectory.groups.READ,ZohoDirectory.groups.CREATE`. Multiple scopes can be given which have to be separated by comma.
client_id ^*	Client ID obtained while registering the client.
state	An opaque string that is round-tripped in the protocol, i.e., whatever value given to this will be passed back to you.
response_type ^*	`code`
redirect_uri ^*	One of the redirect URL 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`. The `online` access_type gives your application only the access_token which is valid for one hour. The `offline` access_type will give the application an access_token as well as a refresh_token. By default it is taken as `online.`
prompt	Prompts for user consent each time your app tries to access user credentials. e.g. `Consent.`

Note: Fields with * are mandatory

On this request, you will be shown with a "user consent page".

Upon clicking “Accept”, Zoho will redirect to the given redirect_uri with code and state param. This code value is mandatory to get the access token in the next step and this code is valid for 60 seconds.

On clicking “Deny”, the server returns an error

 
https://accounts.zoho.com/oauth/v2/auth?
scope=ZohoDirectory.groups.CREATE,ZohoDirectory.groups.READ,ZohoDirectory.groups.UPDATE,ZohoDirectory.groups.DELETE&
client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&
state=testing&
response_type=code&
redirect_uri=http://www.zoho.com/directory&
access_type=offline

Step 3: Generate Access and Refresh Token

After getting code from the above step, make a POST request for the following URL with given params, to generate the access_token.

https://accounts.zoho.com/oauth/v2/token?

Parameter	Description
code^*	`code` which is obtained in the previous step.
client_id^*	Client ID obtained while registering the client.
client_secret^*	Client secret obtained while registering the client.
redirect_uri^*	This parameter should be the same redirect URL mentioned while registering the client.
grant_type^*	`authorization_code`
scope	Scope for which token has to be generated,e.g. : `ZohoDirectory.groups.READ,ZohoDirectory.users.CREATE`. Multiple scopes have to be separated by commas.
state	An opaque string that is round-tripped in the protocol, i.e., the value will be passed back to you.

Note: Fields with * are mandatory

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

1. The access_token will expire after a particular period (as given in expires_in param 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.

 
$ curl https://accounts.zoho.com/oauth/v2/token \
-X POST \
-d 'code=1000.dd7exxxxxxxxxxxxxxxxxxxxxxxx9bb8.b6c0xxxxxxxxxxxxxxxxxxxxxxxxdca4' \
-d 'client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V' \
-d 'client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf' \
-d 'redirect_uri=http://www.zoho.com/directory' \
-d 'grant_type=authorization_code' \

Step 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 for a new access token. Redirect to the following POST URL with the given params to get a new access token

https://accounts.zoho.com/oauth/v2/token?

Parameter	Description
refresh_token	Refresh Token that is obtained in the previous step.
client_id	Client ID obtained while registering the client.
client_secret	Client secret obtained while registering the client.
redirect_uri	This parameter should be the same redirect URL mentioned while registering the client.
grant_type	`refresh_token`

 
$ curl https://accounts.zoho.com/oauth/v2/token \
-X POST \
-d 'refresh_token=1000.8ecdxxxxxxxxxxxxxxxxxxxxxxxx5cb7.463xxxxxxxxxxxxxxxxxxxxxxxxebdc' \
-d 'client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V' \
-d 'client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf' \
-d 'redirect_uri=http://www.zoho.com/directory' \
-d 'grant_type=refresh_token' \

Step 5: Revoking a Refresh Token

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

https://accounts.zoho.com/oauth/v2/token/revoke?

Parameter	Description
token	Refresh Token which is to be revoked.

 
$ curl https://accounts.zoho.com/oauth/v2/token/revoke \
-X POST \
-d 'token=1000.8ecdxxxxxxxxxxxxxxxxxxxxxxxx5cb7.4638xxxxxxxxxxxxxxxxxxxxxxxxebdc' \

Step 6: Calling An API

Access Token can be passed only in header and cannot be passed in the request param.

Header name should be Authorization
Header value should be Zoho-oauthtoken {access_token}

Sample List of scopes available in Zoho Directory :

Scope	Description
Users	To access users related APIs. Available types: `ZohoDirectory.users.CREATE, ZohoDirectory.users.READ, ZohoDirectory.users.UPDATE, ZohoDirectory.users.DELETE`
Groups	To access groups related APIs. Available types: `ZohoDirectory.groups.CREATE, ZohoDirectory.groups.READ, ZohoDirectory.groups.UPDATE, ZohoDirectory.groups.DELETE`

Token Validity

Grant Token (Authorization code)

For Self Client: - The grant token is a one-time use token and it is valid for three minutes, by default. If you want to extend its expiration time, choose the required time from the drop-down while generating the token from the API console.

For Other Clients: - The grant token is a one-time use token and it is valid for two minutes.

You can generate a maximum of 10 grant tokens in a span of 10 minutes per client ID. If the limit is reached, "access_denied" exception will be thrown for the remaining duration.

Access Token

Each access token is valid for one hour.

A maximum of 15 active access tokens can be stored per refresh token. When the 16th token is requested, the oldest token is invalidated. When an invalid access token is used, "INVALID_OAUTHTOKEN" exception will be thrown.

You can generate a maximum of 10 access tokens from a refresh token in a span of 10 minutes.

If the 10-minute throttle limit is reached, "Access Denied" error will be thrown. Re-use valid tokens to avoid this exception.

Refresh Token

Refresh tokens do not expire until a user revokes them.

A maximum of 20 refresh tokens can be stored per user.

When you generate the 21st refresh token, the oldest refresh token will become invalid.