OAuth 2.0 User Guide
Table of Contents
OAuth 2.0 overview
Zoho Calendar REST API uses OAuth 2.0 for secure authentication and authorization. OAuth 2.0 enables third-party applications to access resources without requiring the end user to repeatedly authenticate. By obtaining user consent, OAuth 2.0 allows applications to perform predefined API calls securely, ensuring data protection while enhancing user convenience.
If you are developing a custom application or customizing Zoho Calendar features for specific business needs, OAuth 2.0 ensures secure access to Zoho Calendar data through API integration.
Glossary
The following terms are used throughout this guide:
| Parameter | Description |
|---|---|
| Client application | Third-party application that users access through their Zoho account |
| End user | Person who uses the client application |
| Zoho Authorization Server | Zoho Accounts server that authenticates users and issues authorization codes and tokens |
| Access token | Short-lived OAuth token used to access protected Zoho resources; valid for one hour |
| Refresh token | Long-lived token used to obtain new access tokens without requiring the user to authenticate again |
| Scopes | Permissions that define the data and actions an access token can access |
Refer to the OAuth 2.0 glossary section to understand more about the terms used here.
How OAuth 2.0 works?
The following steps describe the OAuth 2.0 authentication process between the end user, client application, and Zoho Authorization Server.
- The end user accesses the client application.
- The client application initiates authorization by sending a request for an authorization code, specifying the required scopes.
- The Zoho server prompts the end user to authorize the client application to access their data within the specified scopes.
- The end user grants authorization to the client application.
- The Zoho server sends the authorization code to the client application.
- The client application requests an access token from the Zoho server in exchange for the authorization code.
- The Zoho server sends an access token and, if requested, a refresh token.
- The client application uses the access token to access Zoho Calendar resources on behalf of the end user. When the access token expires, the refresh token is used to obtain a new one. This cycle continues until access is explicitly revoked.
Implementation Steps
Follow the steps below to integrate your application with Zoho Calendar using OAuth 2.0.
Step 1: Register your app and get OAuth credentials
Before making any API calls, register your application in the Zoho API Console. This is a one-time setup that provides the credentials your app uses to identify itself to the Zoho Authorization Server.
How to register
- Go to Zoho API Console at accounts.zoho.com/developerconsole
- Hover over your application's client type and click CREATE NOW. If you've previously added an application, click ADD CLIENT in the top-right corner.
- To learn about the workflows for different types of clients, refer to the below table below:
Client type | Authorization flow | Description |
Authorization Code | For web applications with a backend server. The authorization code is exchanged for tokens server-side, keeping the client secret secure. | |
Implicit / Authorization Code with PKCE | For browser-based JavaScript applications with no backend server. Tokens are handled entirely in the browser. | |
Authorization Code with PKCE | For native iOS and Android applications. PKCE replaces the client secret for environments where secrets cannot be stored safely. | |
Device Authorization | For limited-input devices such as CLIs or smart TVs. The user authenticates on a separate browser-enabled device while the application polls for the token. | |
Pre-generated Authorization Code | For personal scripts and automation tools accessing your own Zoho Calendar account. No user-facing consent screen is involved. |
- Enter the required details, then click CREATE. The required details for each client type are as follows:
| Client Type | Required Details |
| Client-based | Client Name, Homepage URL, Authorized Redirect URIs, JavaScript Domain |
| Server-based | Client Name, Homepage URL, Authorized Redirect URIs |
| Mobile-based | Client Name, Homepage URL, Authorized Redirect URIs |
| Non-browser-based | Client Name, Homepage URL |
| Self Client | _ |
Application registration parameters:
Parameter | Description |
| Homepage URL | Full URL of your application's home page |
| Authorized Redirect URI | URI to which Zoho Accounts sends the authorization response after the user grants consent. The response contains the authorization code or, for client-based applications, the access token. The URI must begin with https:// or http://. Multiple redirect URIs can be added using the + icon. Example: https://www.zylker.com/oauthredirect |
| JavaScript Domain | Domain of your client-based JavaScript application. The domain must begin with https:// or http://. Multiple domains can be added using the + icon |
Credentials issued
- Client ID - Unique identifier assigned to your application.
- Client Secret - Confidential key used alongside the Client ID to authenticate your application's token requests. Store it securely and do not expose it in client-side applications or public repositories.
After registration, select the Client Secret tab in your application's page in the console to find your Client ID and Client Secret. Use these credentials to obtain access tokens when making API calls.
Note
Your Client ID and Client Secret are permanent for the registered application. Store them securely and rotate the Client Secret immediately if it is ever compromised.
Step 2: Obtain an access token
The method for obtaining an access token depends on your application type. However, in any method, access token will be provided only after the user grants permission through consent. Also, access tokens are always granted for the specific scopes which are mentioned in the request, and the scopes will be displayed to the user while asking for permission.
Scopes
Scopes define exactly what your application is permitted to access. Specify only the scopes your application requires. The requested scopes are displayed to the user during the consent prompt.
Syntax:
service_name.scope_name.OPERATION_TYPE
Example
ZohoCalendar.event.READ
Step 3: Access the resource using the access token
After your app has the access token, it can access Zoho's protected resources. On giving the access token to the resource server, your app will be granted access as per the scopes defined in the request. Zoho's OAuth implementation uses Bearer authentication scheme as defined in RFC 6750, hence while making API calls, the access token has to be passed in the Authorization header with the prefix Bearer.
Note
The OAuth token response includes token_type as Bearer, in compliance with the OAuth 2.0 specification. However, Zoho Mail APIs require Zoho-oauthtoken as the authorization header prefix, not Bearer. Use the following format when making API requests.
Syntax:
Authorization: Zoho-oauthtoken {access_token}
Example
Authorization: Zoho-oauthtoken 1000.2deaf8d0c2ab34f891e...
The Zoho resource server validates the token and grants access to resources within the approved scopes. Requests with an invalid, expired, or out-of-scope token will receive a 401 Unauthorized response.
Step 4: Refresh the access token when it expires
Access tokens have a fixed lifetime of 1 hour. After expiry, the token can no longer be used to access resources. If your application requires access for longer than 1 hour (3600 seconds), request a refresh token during the initial authorization and store it securely. This refresh token allows the app to generate a new access token whenever required.
Refresh token flow
- Detect a 401 Unauthorized response (or proactively track token expiry time)
- Send a token refresh request to the Zoho Authorization Server using the stored refresh token
- The server issues a new access token
- Resume API calls with the new token
Note
Refresh tokens do not expire automatically. They remain valid until the user revokes access or you explicitly revoke the token. Store refresh tokens with the same care as passwords.
Step 5: Revoke unwanted tokens
If a refresh token is no longer required, or if you suspect it has been compromised, revoke it immediately using the Zoho OAuth revoke endpoint. Revoking a refresh token also invalidates all access tokens that were generated from it.
When to revoke
- User logs out of your application
- User revokes consent in their Zoho account settings
- A refresh token is suspected to be leaked or compromised.
- Your application is decommissioned or the integration is removed
After a successful revocation, the refresh token becomes immediately invalid and cannot be used to generate further access tokens.