Introduction to OAuth 2.0

What is OAuth 2.0?

OAuth 2.0 is an industry standard protocol which allows you to grant a third-party website or an application (i.e., a client) delegated access to the protected resources of Zoho via Zoho APIs. It is a way to authenticate and authorize API requests made to Zoho.

Advantages of OAuth 2.0

• Clients are not required to support password authentication or store user credentials, because the authentication and authorization is done by exchanging OAuth tokens.
• Clients gain delegated access, i.e., access only to resources authorized by the user.
• Users can revoke third-party application's delegated access anytime.
• OAuth access tokens expire after a set time. If the client faces a security breach, user data will be compromised only until the access token is valid.

OAuth 2.0 workflow

Refer to the OAuth 2.0 glossary section to understand more about the terms used here.

Step 1: Register your app and get OAuth credentials

The first step in using OAuth authentication is registering your app with the Zoho API console. Once you register your client, you will get a Client ID and Client secret for your application. This Client ID and Client secret are used to authorize your app's OAuth requests.

Step 2: Obtain an access token

Access token is an OAuth token used to access Zoho's protected resources. The way in which the access token can be generated depends on the type of app. For example, server-based apps can use the authorization code flow to generate an access token, while client-based apps can use the implicit flow to generate an access token. 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.

To learn about the workflows for different types of clients, refer to the below pages:

• Server-based apps
• Client-based apps
• Mobile & desktop apps
• Non-browser apps (i.e., apps for limited input devices)
• Self client

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, hence while making API calls, the access token has to be passed in the Authorization header with the prefix Zoho-oauthtoken or Bearer.

Supported formats: 

Authorization: Zoho-oauthtoken <space> {access-token-value}

Authorization: Bearer <space> {access-token-value}

Example: Authorization: Zoho-oauthtoken 1000.2deaf8d0c2...

Step 4: Refresh the access token when it expires

Access tokens have limited validity, i.e., their lifetime is only 1 hour, post which they expire and cannot be used to access the resources any longer. However, if the app wants to access the resource for more than 1 hour, then a refresh token can be retrieved and stored. This refresh token allows the app to generate a new access token whenever required.

Step 5: Revoke unwanted tokens

If a refresh token is no longer required or appears to be compromised, it can be revoked and made invalid. It can be revoked by making an API request and after successful revocation, it can no longer be used to generate access tokens, and the existing access tokens generated using this refresh token will also become invalid.  

OAuth 2.0 glossary

Protected resource

It is the data present in a Zoho service that the client wants to access. For example, if the client wants to access the records module in Zoho CRM using an API, then the records module is called the protected resource. This data (i.e., module) can be accessed by the client only after proper authorization using OAuth, hence then name protected resource.

Resource owner

Resource owner is the user who can grant permission to the client and in turn access to the protected resource of their Zoho account.

Resource sever

The server where the protected resources are stored, and to where the client must make API calls is called the resource server. In our case, the Zoho app which has the resource the client wants to access represents the resource server.

Authorization server

The server which grants access tokens and refresh tokens on behalf of the resource owner (i.e., the user), for the client to access protected resources is called the authorization server. In our case, Zoho Accounts is the authorization server.

Client

The application which needs access to the protected resource is called the client. The client can be a server-based application, single page JavaScript application, mobile/desktop application, or a non-browser limited input application. The client can make API requests to the resource server after successful authorization by the authorization server on behalf of the user.

Client type

Indicates the type of application you develop. The four types of clients are:

• Server-based application
  Web applications that are built to run with a dedicated HTTP server. Follows authorization code flow of OAuth.
• Client-based application
  Single page JavaScript applications that are built to run exclusively on browsers independent of web servers. Follows implicit flow of OAuth.
• Mobile/desktop application
  Applications that are built to run on smartphones and tablets. Follows the authorization code flow.
• Non-browser application
  Applications that run on devices without browsers such as TVs and printers.
• Self-client
  Applications which doesn't have a redirect URI and is used only to fetch information automatically from your own account.

Client ID

A unique identifier for your application which you can receive when registering your application in the Zoho API console.

Client secret

A unique secret key for your application which you can receive when registering your application in the Zoho API console. Client secret is know only between your application and Zoho, therefore, must be kept confidential. (Client secret is not needed for client-based applications and will not be provided). 

Access token

Access tokens are granted by the authorization server (Zoho Accounts) and are used by the client to access the protected resources. It contains information about the user and the scopes. It essentially tells the resource owner that the bearer of this token has been authorized by the user to access the protected resource as per the scope defined. The validity of an access token is 1 hour.

Refresh token

Refresh tokens are used to generate a new access token after the old one expires. Refresh tokens are granted by the authorization server (Zoho Accounts) and can be stored by the client to generate access tokens whenever required.

Authorization code

For server-based applications and mobile-based applications, access tokens cannot be generated directly. Instead, the client must first get an authorization code from the authorization server (Zoho Accounts), and then exchange it for an access token. The lifetime of authorization code is only two minutes and can be used only once.

Client registration

To access the resources of Zoho using the various Zoho APIs, you will need to register your application with Zoho first. You can register your application as one of the following client types:

• Server-based application
• Client-based application
• Mobile-based application
• Non-browser based application
• Self client

On successful registration of your application, you will get a Client ID and Client secret. You can use them to get the access token which is needed to make API calls to Zoho.
 

To register your application

1. Go to Zoho API console, then click GET STARTED. 
   
2. 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.
   
3. Enter the required details, then click CREATE. The required details for each client are as follows:

You can find the Client ID and Client secret in the Client Secret tab of your application in the console.

To learn more about self client, refer to this article.

Server-based apps - Overview

What are server-based apps

Server-based apps typically involve a separation between the front-end (client-side) and back-end (server-side) components. The application logic is performed on the server, and the rendered content is sent to the browser for display.

These apps can securely store credentials on the server-side, such as client secrets, and are referred to as " confidential clients " in OAuth terminology.

For such apps, the Authorization Code Flow is used to obtain access tokens. It involves exchanging an authorization code (received from the authorization server) for access tokens. Refresh tokens can also be obtained in this flow, allowing the server-based app to obtain new access tokens without requiring user intervention.

Authorization code flow

To begin with, you need to register your app in the API console as a "server-based app". You will get a client ID and client secret. You will need them to make the API calls to receive OAuth tokens. Once you receive an access token, you can use it to access the protected resources of Zoho.

For server-based apps, you can optionally use the authorization code flow with the Proof Key for Code Exchange (PKCE) extension for added security. It is required for mobile-based apps, but recommended for server-based apps as well. Learn more about PKCE

The authorization code flow to obtain access token is as follows:

• Step 1:

  Make a GET request to the endpoint oauth/v2/auth mentioning the required scopes. The end user will be displayed the permissions you're requesting. If the user grants access, an authorization code will be returned to the redirection URL. This code will be valid for 2 minutes.

  Refer API reference

• Step 2:

  Using the received authorization code, make a POST request to the endpoint oauth/v2/token . The authorization server will return an access token and an optional refresh token. This access token will be valid for 1 hour.

  Refer API reference

• Step 3:

  Using the received access token, you can call the Zoho APIs to access protected resources. If you need to access the resources again after the access token expires, you can use the refresh token to obtain access tokens whenever required. Send a POST request to the endpoint oauth/v2/token with the refresh token to obtain another access token.

  Refer API reference

Multi DC support

In Zoho, we use different data centers (DC) to store users' information. This information is not shared between data centers. Learn more about data centers

If your app is registered in the a certain DC, to access the data of the users in other DCs, then you need to enable multi DC support for your app. After you enable this support, when you make API calls, you will have to change your endpoint URL depending on the user's DC.

• Enable multi DC support
• Workflow for server-based apps

Incremental authorization

Incremental authorization allows your app to request for a permission from the user only when it is needed and not upfront. Let's say your app needs to obtain profile information of the user to provide basic functionality; and for certain features, need additional permission. Normally, your app will have to request profile info permission and additional permissions upfront when user grants access. But this would provide a bad experience for the user because they would have to give permission for features which they aren't even using yet. Incremental authorization helps avoid this and provides a better user experience.

• Implement incremental authorization

Revoking refresh tokens

Refresh tokens can be revoked programmatically or by the user themselves.

Refresh tokens can be revoked by users in two ways:

• Users can go to the Connected Apps section in accounts.zoho.com and revoke the access they've granted for an app.
• Users can choose to revoke access for connected apps when they change their password, or enable multi-factor authentication (MFA).

Programmatically, refresh tokens can be revoked by making a POST request to the endpoint oauth/v2/token/revoke . Refer API reference

Note : Access tokens can also be revoked programmatically. When an access token is revoked, if it is granted via a refresh token, it will also get revoked.

Client-based apps - Overview

What are client-based apps

Client-based apps, such as single-page JavaScript apps, perform the application logic directly in the browser using JavaScript.

These apps typically cannot securely store credentials, including client secrets, on the client-side due to the potential for exposure or compromise. Client-based apps are often referred to as " public clients " in OAuth, indicating their inability to keep credentials confidential.

For such apps, the Implicit Flow is used for obtaining access tokens. It returns the access token directly to the client-side environment as part of the redirection process. Refresh tokens are not provided in the Implicit Flow, but the app may be able to obtain new access tokens without user intervention if the user has granted permission for the session.

Implicit flow

To begin with, you need to register your app in the API console as a "client-based app". You will get a client ID. You will need it to make the API calls to receive access token. Once you receive an access token, you can use it to access the protected resources of Zoho.

The implicit flow to obtain access token is as follows:

• Step 1:

  Make a GET request to the endpoint oauth/v2/auth mentioning the required scopes. The end user will be displayed the permissions you're requesting. If the user grants access, an access token will be returned to the redirection URL. This access token will be valid for 1 hour.

  Refer API reference

• Step 2:

  Using the received access token, you can call the Zoho APIs to access protected resources. If you need to access the resources again after the access token expires, you can obtain another access token if the user has granted access for the entire session in step 1. Send a GET request to the endpoint oauth/v2/auth/refresh to obtain another access token.

  Refer API reference

Multi DC support

In Zoho, we use different data centers (DC) to store users' information. This information is not shared between data centers. Learn more about data centers

If your app is registered in the a certain DC, to access the data of the users in other DCs, then you need to enable multi DC support for your app. After you enable this support, when you make API calls, you will have to change your endpoint URL depending on the user's DC.

• Enable multi DC support
• Workflow for client-based apps

Revoking access tokens

Access tokens can be revoked programmatically or by the user themselves. Users can go to the Connected Apps section in accounts.zoho.com and revoke the access they've granted for an app, which will revoke the access tokens.

Programmatically, access tokens can be revoked by making a POST request to the endpoint oauth/v2/token/revoke . Refer API reference

Mobile-based Applications

Native mobile applications on different mobile operating systems can gain authorized access to Zoho's APIs via OAuth. The authorization flow is similar to the server-based application flow . The mobile device must additionally provide an app schema, so the redirection can be caught by the mobile application.

Authorization code flow with PKCE

Mobile and desktop-based apps can communicate with Zoho and obtain the access token using the authorization code flow. Since, mobile and desktop apps are public clients , the Proof Key for Code Exchange (PKCE) extension must also be used to obtain the access token.

Note: Previously, PKCE was not mandated for mobile and desktop apps. Apps previously registered with Zoho that haven't supported PKCE can still obtain access tokens. However, it is strongly advised to support the PKCE extension from now on to improve the security of your app.

Why is PKCE needed

When public clients use the authorization code flow, there is a risk of an "authorization code inception attack" due to the following reasons:

1. Multiple apps can register themselves as a handler for a redirect URL . Hence, a malicious app (by using the same redirect URL as the original app) can intercept the authorization code when the browser returns it from the Zoho server.
2. A public client cannot store the client credentials securely . Hence, a malicious app will be able to steal the client secret, pose itself as the original app, then exchange the intercepted authorization code for an access token.

PKCE mitigates this attack, and ensures the access token is provided only to the correct app and not to any malicious app.

How PKCE works

Prerequisite: Refer to the authorization code flow to understand the the fundamental workflow of getting access tokens.

In regular authorization code flow, the app will open the browser and initiate the OAuth flow. However, with the PKCE extension, before opening the browser, the app will generate a code_verifier and code_challenge , then proceeds with the OAuth flow.

The PKCE flow will be as follows:

1. When the app wants to access a Zoho resource, it generates a code_verifier and code_challenge . The code_verifier is a random cryptographically-generated code, and code_challenge is a transformed version of code_verifier .
2. The app opens the browser and sends a request to Zoho to obtain an authorization code (oauth/v2/auth). The code_challenge and the code_challenge_method (i.e., the method used for the transformation) are included as parameters in this request.
3. After authenticating the user, Zoho provides an authorization code, and stores the code_challenge and the code_challenge_method .
4. The browser returns the authorization code to the app via the redirect URL.
5. The app sends the authorization code to Zoho in exchange for an access token (oauth/v2/token). The code_verifier is included as a parameter in this request.
6. Zoho will transform the code_verifier using the code_challenge_method , then compares the transformed version with the stored code_challenge .
7. If both the transformed code_verifier and the stored code_challenge matches, Zoho returns an access token to the app. If not, an error response will be returned.

How to implement authorization code flow with PKCE

Step 1: Generate code_verifier

The code_verifier is a cryptographically-generated random string. The code_verifier must:

• Be created using the unreserved characters: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~".
• Have a minimum length of 43 characters and maximum length of 128 characters.
• Have a high entropy value and must be impossible to guess.

Step 2: Transform code_verifier into code_challenge

The code_verifier can be transformed into code_challenge using the following methods:

• SHA256 (recommended)
  code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
• Plain
  code_challenge = code_verifier

If the client can support the SHA256 method, it is mandatory to use this method. The plain method should be used only if the client is unable to support SHA256.

The issue with the plain method is that it can mitigate the attack if the malicious app can only observe the responses. If a malicious app is able to observe the requests, then the plain method will be ineffective as the app will be able to steal the code_verifier and use it to obtain the access token, since the code_verifier is the same as the code_challenge .

Step 3: Send an authorization request with code_challenge included

Follow this API reference doc to send an authorization request and obtain the authorization code.

Step 4: Send an access token request with code_verifier included

Follow this API reference doc to send an access token request and obtain the access token.

Non-browser applications

What are non-browser apps

Some apps run on devices that don't have a browser and only have limited input capabilities, such as TVs and printers. Hence, users won't be able to grant permission to the app directly, the regular OAuth flow can't be used. These apps are called Non-browser apps.

For such apps, the "Device Authorization Grant" flow has to be used. To request for permission, the app will need to display a URL and verification code to the user. The user will have to go to the verification URL (in a browser of their mobile device or computer) and enter the code to grant permission. After the permission is granted, an access token and refresh token will be provided to the app.

Device authorization grant flow

Step 1: Client registration

Register your client with the Zoho API console and generate client ID and client secret.

Step 2: Initiation request

The device won't be able to get permission from the user directly, due to the lack of a browser. The device needs to make an initiation request to Zoho Accounts server to get the following:

• user_code - this will be used to get permission from the user
• verification_url - this is the URL that the user should access from a browser, and enter the user code in.
• device_code - this will be used to get the access token (during polling request).

See API reference for initiation request

Step 3: Display the user code and verification URL to user

After the initiation request, the device must display the verification_URL and user_code to the user. The user can grant permission to the device by navigating to the verification_URL from their mobile phone or laptop and entering the user_code . Simultaneously, the device will have to send polling requests to the Zoho server.

When the user navigates to the verification_URL in a browser, the following screen will be shown, where the user needs to enter the user_code and click Verify . After clicking Verify , the required permissions will be shown. The user needs to grant permission by clicking Accept .

Step 4: Polling request

If the user has granted permission, the device can make requests to the Zoho server to get an access token. But the device won't know whether the user has granted permission or not. Hence, the device will have to keep polling requests to the server at a rate of 1 request per 5 seconds. The server will respond with a feedback response depending on the user's action. If the user has granted permission, the server will provide the access token to the device.

See API reference

Step 5: Access resources

Using the access token, the device can access the resources specified in the scope.

Multi DC support

In Zoho, we use different data centers (DC) to store users' information. This information is not shared between data centers. Learn more about data centers

If your app is registered in the a certain DC, to access the data of the users in other DCs, then you need to enable multi DC support for your app. After you enable this support, when you make API calls, you will have to change your endpoint URL depending on the user's DC.

• Enable multi DC support
• Workflow for non-browser apps
  

Revoking refresh tokens

Refresh tokens can be revoked programmatically or by the user themselves.

Refresh tokens can be revoked by users in two ways:

• Users can go to the Connected Apps section in accounts.zoho.com and revoke the access they've granted for an app.
• Users can choose to revoke access for connected apps when they change their password, or enable multi-factor authentication (MFA).

Programmatically, refresh tokens can be revoked by making a POST request to the endpoint oauth/v2/token/revoke . Refer API reference

Note : Access tokens can also be revoked programmatically. When an access token is revoked, if it is granted via a refresh token, it will also get revoked.

Self client

If you want your app to fetch data from your own Zoho account, or set up app-to-app communication in the backend without any user interaction, you can use the Self Client option. In this situation, you will be the resource owner and there will be no end-user authorization required. The client will request access permission on behalf of itself and not any end-user.

Follow the steps to set up Self Client:

Create a self client in API console

1. Go to the Zoho API console. 
2. Click GET STARTED. 
3. Hover over the Self Client option and click CREATE NOW. 
4. Click CREATE, then click OK. A Client ID and Client Secret will be created and shown under the Client Secret tab. You can copy these.

Get access token

There are two ways in which you can get an access token for your self client:

• Authorization code grant flow
• Client credentials grant flow

In the authorization code grant flow, you will need to generate an authorization code from the API console, then exchange it for an access token and refresh token. When the access token expires, you can use the refresh token to get a new access token. See API reference

In the client credentials grant flow, you will need to provide your client credentials to get an access token. A refresh token won't be provided. So, you will need to send the same request again to get a new access token whenever required. See API reference 

Instance-level OAuth with administrator consent

What is an app instance?

An app instance refers to a specific environment or container within a Zoho app. Some Zoho apps support having only one instance (for example, Zoho Mail or Zoho Vault), while others allow multiple instances (for example, Zoho CRM or Zoho Books). The instances may be referred to differently across apps, such as “Organizations” in Zoho CRM and Zoho Books, and “Portals" in Zoho Desk and Zoho Projects.

App instance-level OAuth

When you want to set up an integration that needs access to data across an entire app instance, using the regular user-based OAuth flow can be limiting. Each user must give consent individually, and also their tokens stop working if they revoke access or if a user is removed from the app instance.

With the instance-level OAuth flow, an administrator grants consent once on behalf of the entire instance. The integration can then access the required data from the instance as a whole. And the tokens remain valid even if the administrator who authorized it is later removed from the instance.

An example use case: Your app wants to generate an analytical report using the tickets and agents data pulled from Zoho Desk, specifically from a particular instance (that is, a Portal). With user-based OAuth, each user would have to grant access individually, and the access will be limited to only the tickets associated with them. With instance-level OAuth, the department administrator can grant access once at the Portal level, allowing your app to retrieve the required data.

Implementing instance-level OAuth

Create a client for the integration

You need to first create an "ORG" type client for each integration. These clients can be created at the API console. Follow the steps below to create an "ORG" client:

1. Go to https://api-console.zoho.com/add?client_type=ORG

2. Sign in with your Zoho account if prompted.

3. Enter a name for the client.

4. Enter the Homepage URL and Authorized Redirect URIs of your app.

   INFO:

   • Homepage URL :
     The full URL to your application's home page.

   • Authorized Redirect URI :
     It is the URI of the application to which the authorization server (Zoho Accounts) sends the response back to, with the authorization code after the admin grants permission through consent. The URI should begin with https:// or http://. You can add multiple redirect URIs by clicking [plus]. Example: https://www.zylker.com/oauthredirect

5. Click CREATE . Client ID and Client Secret will be displayed. You can also view them anytime at the API console.

Get consent from admin and generate tokens

Points to note before

• Scopes are limited to one Zoho app per refresh token

  The client must request for scopes of only one Zoho app per refresh token. This is because in the integration context, a refresh token defines authorization between your client and a single Zoho app, not multiple apps. The exception to this requirement is the scopes of certain common Zoho services listed below:

  • ZohoContacts
  • ZohoProfile
  • ZohoFiles
  • AaaServer

• User must be an administrator in at least one instance

  The user granting permission must be an administrator in at least one instance of the Zoho app mentioned in the scope.

Step 1: Get an authorization code after consent

Request for an authorization code. We will display the requested permissions to the administrator. If they are the administrator of multiple instances, they will have to select which instance to grant permission for. If they grant it, an authorization code will be sent to your redirect URL, which is valid for 2 minutes.

See API reference

Step 2: Get access token and a refresh token

Exchange the authorization code to receive an access token and a refresh token. Store this refresh token so you can use it to generate new access tokens whenever your apps wants to access the data.

See API reference

Step 3: Refresh access tokens when needed

Generate new access tokens using your stored refresh token whenever needed. Each access token will be valid for 1 hour.

See API reference

Revoking tokens
If you want to revoke a refresh token created for an integration, you can make a POST request to oauth/v2/token/revoke . For more details, refer to Revoke OAuth tokens .