OAuth 2.0 User Guide

If you are building a custom application with Zoho account or if you want to make certain modifications to the already existing calendar features depending on your needs, it is mandatory to obtain permission to access the Calendar API. For this reason, OAuth 2.0 authentication is required.

The following steps will help you understand on how to proceed with the OAuth 2.0 authentication process.

1. Register your application : Generate Client ID and Client Secret using Client Name and Client Domain

The primary step towards receiving your OAuth 2.0 authentication is registering your application with Zoho Developer's Console. Once you register yourself, your Client ID and Client secret will be generated.

Steps to generate your client ID and client secret:

1. To register your application, navigate to https://accounts.zoho.com/developerconsole.

2. You will be prompted with a screen that says "You don't have credentials to access the API". Click on the Add Client ID button to proceed further.

3. The Create Zoho Client ID window is opened. Fill in the details shown to you which consists of Client name, Client Domain and Authorized redirect URIs.

4. After filling the required fields, click on Create.

​

You will be provided with the Client ID and the Client secret which will be known to both Zoho and your application. Using these credentials, you can go ahead with the OAuth 2.0 authentication.

2. Get Authorization: Generate code (expires in 3 to 8 minutes) using client ID

In the next level of authentication, the user needs to call an "Authorization URL". This authorization URL should be defined using certain parameters as mentioned below:

Example:

After the authorization URL is called by the user, a new page called as the "User Consent Page" is loaded. The user has to either Accept or Decline the authorization process at this stage. 

If the user proceeds with Accept, then Zoho redirects the user back to your site with an Authorization code. After receiving the auth_code, the access token can be generated by the application by sending a request to Zoho. In case, the user clicks on Deny, then the server returns an error. 

Prompting re-consent:

You can prompt the user to reauthorize your app every time the user logins in by adding the prompt=consent parameter to the authentication request. 

When prompt=consent is included, the consent screen is displayed every time the user logs into your app. For this reason, include prompt=consent only when necessary.

3. Get the Access Token : Generate Access Token and Refresh Token using Client ID, Client Secret, Code and Scope

The crucial step towards authentication lies in the generation of access token and refresh token. Once the auth_code is received by the application, the auth_code can be used to request Zoho for generating the required access token. When the user sends a request for the access token, your app will receive the user details. Since this is an important step in the entire process, be careful while setting the parameters for the same.

Example:

After the user has made a request using the authorization code, Zoho will issue a response to your app which contains the following information:

expires_in - Time in milliseconds for which the token remains valid.

token_type - Type of token. (”bearer”) access_token

access_token - Access token for this user.This token can be used for the final API calls and will be valid only for one hour.

refresh_token - Refresh token to be used when the access 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. You can store this data so that there is no need for authorization each time the user accesses your app.

4. Use the Access Token: Access API with the Access Token (Access Token expires in 3600 seconds)

Once you have received the access token, you can use it to obtain access to the calendar API. Send the access token as a header when you call a Zoho service REST API.

Example:

When the access token with the available scope invokes the URL, the information as permitted in the scope is granted to the application. The user credentials are thus obtained and the regular sign-in flow can be implemented.

5. Use the Refresh Token : Regenerate the Access Token (Generate Access Token using Refresh Token)

Access tokens have limited validity. In most 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. 

In your request for access you can request a Refresh Token to be returned along with the access token. The refresh token provides your app access to Zoho APIs even when the user is not logged in. To request a Refresh Token, add access_type=offline to the authentication request.

For sending this request, you need to include the following parameters:

Example:

You will now receive an access token using which you can continue to get user credentials. This access token will also have a validity of one hour.