All Zoho Connect API's need to be authenticated using an OAuth token.
You can obtain an OAuth token by registering your extension with Zoho's Developer Console.
Register as a new client by accessing this website:
https://accounts.zoho.com/developerconsole
- Click on Add Client ID and give the following :
Client Name
Client Domain
Authorized redirect URLs
- Click Create.
Upon providing the necessary details for registering, you are given a set of OAuth credentials known as client id and client secret exclusive for your extension. These credentials will be known to both Zoho and your extension.
Authorization by generating grant token
Redirect the user to the authorization URL, and the authorization will be done when the user grants access in the "user consent" page.
Mandatory case sensitive fields to be passed in the authorization URL are as below:
| Parameter | Description |
| scope | The scope required for your extension. feedList, blogs, events, tasks, wikis, chatrooms, attachments, customapps, connectNotifications, userDetail and pagelist. |
| client_id | Client id obtained during client registration. |
| state | A generated value that correlates the callback with its associated authorization reques |
| response_type | "code" |
| redirect_uri | The redirect URL mentioned during client registration. |
| access_type | Access type will be either online or offline. |
Sample request to generate grant token
GET oauth/v2/auth
Host: https://accounts.zoho.com
Query String: https://accounts.zoho.com/oauth/v2/auth?scope=zohopulse.feedList.CREATE, zohopulse.feedList.READ, zohopulse.feedList.UPDATE,zohopulse.feedList.DELETE&client_id=xxxx.yyy &state=zzz &response_type=code &redirect_uri=http://application_name.com/&access_type=offline
Sample response on generating grant token
http://accounts.zoho.com/oauth2callback?state=zzz&code=xxx
Getting the access token
Once your extension receives the Auth code, a new request can be made to receive an access token using which your app will receive the user credentials.
The code parameter can be obtained from the response of the initial request sent.
Below are parameters to be passed in the URL.
| Parameters | Description |
| code | Authorization code obtained during grant token generation. |
| client_id | Client id obtained during client registration. |
| client_secret | Client secret obtained during client registration. |
| redirect_uri | Redirect url mentioned during client registration. |
| grant_type | authorization_code |
| scope | Specify the scope allowed for your extension. |
| state | A generated value that correlates the callback with its associated authorization request.Has to be maintained the same during the entire process for authenticity. |
Once the request along with the authorization code is sent, Zoho will issue a response to your app which will give you the following information.
- expires_in - Time in milliseconds that the token remains valid.
- token_type - Type of token. It is bearer in this case.
- access_token - Access token for the user. This token can be used for the final API calls and will be valid only for an hour.
- refresh_token - Refresh token to use when the token has timed out. This token is permanent and can be used multiple times (limit - 20) to refresh the app and get a new access token.
All REST APIs should be accessed with an OAuth token. Send the access token as a header when you call a Zoho Connect REST API.
All headers should have the following:
Header name: Authorization
Header value: Zoho-oauthtoken<space>access token
contentType:"application/json"
Sample request to generate access token
POST oauth/v2/token
Host: https://accounts.zoho.com
Query String: https://accounts.zoho.com/oauth/v2/token?code=xxx&grant_type=authorization_code&scope=zohopulse.feedList.CREATE, zohopulse.feedList.READ, zohopulse.feedList.UPDATE,zohopulse.feedList.DELETE&client_id=xxx.yyy&client_secret=xxx&redirect_uri=http://application_name.com/
Sample response on generating the access token
{ "access_token": "f2*********************4f", "refresh_token": "12*********************0c", "token_type":"Bearer", "expires_in": 3600000 }
Example of using the access token
Request URL: GET https://connect.zoho.com/nativeapi/v2/tasks
Request Header: Authorization: Zoho-oauthtoken<space>xxx
Generating the access token from refresh token
You can request for a refresh token to be generated along with the access token. To request for a refresh token, add access_type=offline in the authentication request.
The refresh token will always be generated by prompt=consent
In most cases, the access tokens expire in one hour. Until then, the access token has unlimited usage. Once the access token expires the refresh token can be used to generate a new access token.
Example for generating the access token using refresh token
Request URL: POST https://accounts.zoho.com/oauth/v2/token
Host: https://accounts.zoho.com
Query String : https://accounts.zoho.com/oauth/v2/token?refresh_token=xxx.yyy.zzz&grant_type=refresh_token&scope=zohopulse.feedList.CREATE, zohopulse.feedList.READ, zohopulse.feedList.UPDATE,zohopulse.feedList.DELETE&client_id=xxx.yyy&client_secret=xxx&redirect_uri=http://application_name.com/