Using OAuth for authorizing Server-based application
To use the APIs you can create an access token by following the steps mentioned below. Once you've created an access token, you can read, write or insert sheets/cells using Zoho Sheet's Data APIs.
Table of Contents
How to register your application with Zoho's API Console?
You will have to first register your application with Zoho's API console in order to get "Client ID" and "Client Secret". To register your application, Go to Zoho API Console and click "Get Started".
Note : If you are directly shown your API credentials page, click "Add Client ID".
Choose "Server based Applications" and add your Client Name, Homepage URL and the Authorized Redirect URI in the form and click "Create".
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.
How to get Authorization?
Next, the user should be directed to the authorization URL. The authorization URL should contain the following parameters.
URI Endpoint : https://accounts.zoho.com/oauth/v2/auth
HTTP Request type : GET
PARAMS :
Parameter | Parameter type | Description |
client_id | Mandatory | Obtained from registering your application at the Zoho Accounts API console. |
response_type | Mandatory | Value must be 'code'. |
redirect_uri | Mandatory | The URI endpoint that Zoho Accounts will redirect the web browser to with the authorization code after authorizing the client. Make sure the redirect URI is the same as the one provided while registering your client. |
scope | Mandatory | Specifies the scope allowed for your application. Has to be separated by commas. Syntax: Servicename.Scopename.OPERATION Example: ZohoSheet.dataAPI.UPDATE, ZohoSheet.dataAPI.READ |
access_type | Optional | offline/online (By default it is taken as online). The "online" access_type gives your application only the access_token which has limited validity. Whereas the "offline" access_type will give your application an access_token as well as a refresh_token. Once the access token expires you can use the refresh token to regenerate them. |
prompt | Optional | Value must be 'consent'. If this parameter is included in the query, every time you generate an OAuth token, the user's consent will be mandatory. |
state | Optional | A generated value that correlates the callback with its associated authorization request. |
To receive a refresh token, include access_type=offline and prompt=consent in this request.
https://accounts.zoho.com/oauth/v2/auth
?response_type=code
&client_id=1000.P4Z0WWOLFDGRT23126TYD3B4JWQ5TE
&scope=ZohoSheet.dataAPI.UPDATE,ZohoSheet.dataAPI.READ
&redirect_uri=https://www.zylker.com/oauthredirect
&state=123
&access_type=offline
&prompt=consent
Once the user is directed to the authorization URL, the user is now shown a "user consent page".
If the user clicks "Accept" then Zoho redirects the user back to your site with an Authorization code appended in the URL. Your application can now request Zoho for an access token using that authorization code. The code generated will be of one time use. Once a request is made with the code, it will be deleted.
https://www.zylker.com/oauthredirect/?state=123&code=1000.6d7b960a6bcbb74a383ea9b3ef8081be.525f737f496b0eb62f7ff2fbd7690770&location=us&accounts-server=https%3A%2F%2Faccounts.example.com
- state - Which is provided during request.
- code - Authorization code used to request access.
- location - User's domain location.
- accounts-server - Zoho Accounts server.
Prompting re-consent
You can prompt the user to re-authorize your application every time the user logs in by adding the "prompt=consent" parameter to the authentication request. When "prompt=consent" is included, the user consent page is displayed every time the user logs into your application. For this reason, include "prompt=consent" only when necessary.
How to get the Access Token?
Once your application receives the Authorization code, a new request should be made to receive an access token. This request should be made from server along with client secret. The client secret should be completely hidden from the end user due to security reasons. This is an important step in the entire process and so be careful while setting the parameters for the same.
URI Endpoint : https://accounts.zoho.com/oauth/v2/token
HTTP Request type : POST
PARAMS :
Parameter | Parameter type | Description |
code | Mandatory | The authorization code you received as a response for the authentication request. |
client_id | Mandatory | Obtained from registering your application at the Zoho Accounts API console. |
client_secret | Mandatory | Obtained from registering your application at the Zoho Accounts API console. The client secret must be kept confidential and should only be known to you and Zoho. |
redirect_uri | Mandatory | The URI endpoint that Zoho Accounts will redirect the web browser to. Make sure the redirect URI is the same as the one provided while registering your client. |
grant_type | Mandatory | Value must be 'authorization_code'. |
https://accounts.zoho.com/oauth/v2/token
?code=1000.adfcca4c2be2f08b0ce82a54f6343356.ba532585103af6f12a0f243
&grant_type=authorization_code
&client_id=1000.P4Z0WWOLFDGRT23126TYD3B4JWQ5TE
&client_secret=83r359de68c312ta5f1f06c3b1319ab98f59fa246d
&redirect_uri=https://www.zylker.com/oauthredirect
Once the request along with the authorization code is sent, Zoho will issue a response to your application which gives you the following information.
Note : Only if "access_type=offline" and "prompt=consent" is included in the authentication request, your response here will have the "refresh_token".
{
"access_token":"12d865836f0df5ef81a...",
"refresh_token":"f246d233c04a4ccae5f...",
"api_domain":"https://api.example.com",
"token_type":"Bearer",
"expires_in":1000
}
- access_token - A client-authorized key that lets the client access protected resources from Zoho Sheet. The client can make API requests using this access token for up to an hour after the creation of the token.
- refresh_token - Refresh token to use when the access token has timed out. This token is permanent and can be used multiple times to refresh the application and get a new access token.
- api_domain - The API domain URI which the client must use to make all API requests.
- token_type - Type of token. ("Bearer")
- expires_in - Time in seconds that the access token remains valid.
You can store this data so that there is no need for authorization each time this user accesses your app.
Note : Using a refresh token a client can create up to ten access tokens in a span of ten minutes. If the limit is reached, the access token creation will be blocked for the rest of the ten minutes.
How to use the Access Token?
Send the access token as a header when you call a Zoho Sheet Data API.
URI Endpoint : https://sheet.zoho.com/api/v2/<resource_id>
HTTP Request type : POST
Query String :
https://sheet.zoho.com/api/v2/<resource_id>?<parameters>
Header :
Authorization:Zoho-oauthtoken<space><access token>
How to get and use the Refresh Token?
In your request for access you can request a refresh token to be returned along with the access token. A refresh token provides your app access to Data APIs even when the user is not logged in. To request a refresh token, you must add "access_type=offline" and "prompt=consent" in the authorization request.
The maximum number of refresh token is 20. Once the limit is reached the first refresh token in terms of time will be deleted.
The Access Tokens have limited validity. 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.
For this new request, the parameters to be included are,
URI Endpoint : https://accounts.zoho.com/oauth/v2/token
HTTP Request type : POST
PARAMS :
Parameter | Type | Description |
client_id | Mandatory | Obtained from registering your application at the Zoho Accounts API console. |
client_secret | Mandatory | Obtained from registering your application at the Zoho Accounts API console. The client secret must be kept confidential and should only be known to you and Zoho. |
grant_type | Mandatory | Value must be 'refresh_token'. |
refresh_token | Mandatory | The refresh token provided along with the access token in this request. |
https://accounts.zoho.com/oauth/v2/token
?refresh_token=1000.4acb52df20e889f.f170bcf62367
&grant_type=refresh_token
&client_id=1000.P4Z0WWOLFDGRT23126TYD3B4JWQ5TE
&client_secret=83r359de68c312ta5f1f06c3b1319ab98f59fa246d
You will now receive a new access token using which you can continue with Zoho Sheet's Data APIs. This access token will also have limited validity.