OAuth 2.0 for APIs - An Overview

The Zoho Product's API uses the OAuth 2.0 protocol for authentication. OAuth 2.0 is an industry-standard protocol specification that enables third-party applications (clients) to gain delegated access to protected resources in Zoho via an API.

• Why should we use OAuth 2.0?

• How OAuth 2.0 works?

• Key Terminologies in OAuth 2.0

• Tokens

Why should we use OAuth 2.0?

• Clients are not required to support password authentication or store user credentials.

• Clients gain delegated access, i.e., access only to resources authenticated by the user.

• Users can revoke the client's delegated access anytime.

• OAuth 2.0 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.

How OAuth 2.0 works?

Key Terminologies in OAuth 2.0

The following are some terms you need to know before you start using the Zoho Product's APIs.

Resource owner

Any end-user of your account, who can grant access to the protected resources.

Client

An application that sends requests to the resource server to access the protected resources on behalf of the end-user.

Client ID

The consumer key generated from the connected application.

Client Secret

The consumer secret generated from the connected application.

Authentication server

Authorization server provides the necessary credentials (such as Access and Refresh tokens) to the client.

Authentication code

The authorization server creates a temporary token and sends it to the client via the browser. The client will send this code to the authorization server to obtain access and refresh tokens.

Tokens

Access Token

A token that is sent to the resource server to access the protected resources of the user. The Access token provides secure and temporary access to the protected resources and is used by the applications to make requests to the connected app. Each access token will be valid only for an hour and can be used only for the set of operations that are described in the scope.

Refresh Token

A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.

Important

User Access Token must be kept confidential since it provides access to protected resources. Do NOT expose your Access Token anywhere in public forums, public repositories or on your website's client-side code like HTML or JavaScript. Exposing it to the public may lead to data theft, loss or corruption.

Scopes

Scopes limit the level of access given to a client for protected resources. It enables a user to provide delegated access to a client. Zoho Service APIs use selected scopes, which control the type of resource that the client application can access. Tokens are usually created with various scopes to ensure improved security. For example, you can generate a scope to create or view a lead, or to view metadata and so on.
Scopes contain three parameters — service name, scope name, and operation type. The format to define a scope is scope=service_name.scope_name.operation_type

For example, ZService.modules.ALL

Here, ZService is the service API name, modules is the scope name, and ALL is the operation type.

• Service API name is the name of the service the client is making API calls to.

• Scope name is the name of the module in the service the client needs access to.

• Operation type is the type of operation that is permissible for the client. It can be ALL, CREATE, READ, UPDATE, DELETE. (ALL gives access to perform all operations).

Group Scopes

Group scope provide complete access to all functions the user can perform on the record. For instance, a group scope can allow a user to read, create, update, and delete records in all modules.

Example:

https://accounts.zoho.com/oauth/v2/auth?scope=ZService.modules.ALL,ZService.settings.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

In the above example, the user has access to all modules in the client ZService account.

Other examples are

• scope=ZService.modules.READ(Read-only permission)

• scope=ZService.modules.CREATE

• scope=ZService.modules.UPDATE

• scope=ZService.modules.DELETE

Separate Scopes

Separate scopes are used to provide access to data in a particular module without access to other modules.

https://accounts.zoho.com/oauth/v2/auth?scope=ZService.modules.leads.ALL,ZService.modules.deals.ALL,ZService.settings.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

The above scope gives the user access to only the leads and deals modules from the client Zoho Service account.

Additionally, you can set specific permissions, like read, create, update or delete, for each module. For examples:

• scope=ZService.modules.leads.READ(Read-only permission)

• scope=ZService.modules.leads.CREATE

• scope=ZService.modules.leads.UPDATE

• scope=ZService.modules.leads.DELETE

Multiple Scopes

Access tokens can also be generated with multiple scopes. In such cases, the scopes should be separated by commas. The format to provide multiple scope is service_name.scope_name.OPERATION_TYPE,service_name.scope_name.OPERATION_TYPE. For example, ZService.modules.READ,ZService.settings.READ.

Register your Application

Before you get started with authorization and make any calls using the Zoho Service APIs, you need to register your application with Zoho Service.

To register,

1. Go to Zoho Developer Console and click on GET STARTED.

   

2. Choose a client type and click CREATE NOW:

   

   Types of Clients

   • Client-based Applications

     Applications that run exclusively in a browser and are independent of web servers.

   • Serve-based Applications

     Applications intended for use by multiple Zoho accounts, with a dedicated backend server and web UI to handle authorization and business logic. Users are redirected to Zoho for authorization and, once consent is granted, the app accesses their data on their behalf.

   • Mobile-based Applications

     Applications built to run on smartphones and tablets.

   • Non-browser Device Applications

     Applications that run on devices without a traditional browser, such as smart TVs or printers.

   • Self Client

     Applications without a redirect URL or web UI, operating solely in the backend without user interaction. Common when both the application and Zoho services are managed by the same owner to enable secure server-to-server communication.

   For more details, refer to OAuth Overview.

   Note

   If you don't have a domain name and a redirect URL, you can use dummy values in their place and register your client.

3. Enter mandatory entries for corresponding client type and click on CREATE.

   Mandatory Entries for Different Client Types

   The following are the mandatory entries for different client types.

   Client Type	Client Name	Homepage URL	Redirect URIs	JS Domains
   Java Script	Y	Y	Y	Y
   Web-based	Y	Y	Y	NA
   Mobile	Y	Y	Y	NA
   Self Client	N	N	N	NA
   Device	Y	Y	N	NA

• Server-based applications

  

• Client-based applications

  

• Self client

  

1. You will receive the client credentials such as Client ID and Client Secret in the Client Secret tab.

Possible Errors

• Enter a valid client name

  Resolution: The client name has a special character. The client name must not contain any special characters except "_" and "&".

• Enter a valid JavaScript Domain URI

  Resolution: The JavaScript domain is incorrect. Specify valid JavaScript domains, separated by commas, and they must start with 'http'.

• Enter a valid redirect URI

  Resolution: The redirect URI is incorrect. Specify a valid redirect URI in the format "https://www.your-domain.com/callback".

• Enter a valid homepage URL

  Resolution: The homepage URL is invalid. Specify a valid homepage URL in the format "https://www.yourdomain.com".

Scopes

Scopes limit the level of access given to a client for protected resources. It enables a user to provide delegated access to a client. Zoho Service APIs use selected scopes, which control the type of resource that the client application can access. Tokens are usually created with various scopes to ensure improved security. For example, you can generate a scope to create or view a lead, or to view metadata and so on.
Scopes contain three parameters — service name, scope name, and operation type. The format to define a scope is scope=service_name.scope_name.operation_type

For example, ZService.modules.ALL

Here, ZService is the service API name, modules is the scope name, and ALL is the operation type.

• Service API name is the name of the service the client is making API calls to.

• Scope name is the name of the module in the service the client needs access to.

• Operation type is the type of operation that is permissible for the client. It can be ALL, CREATE, READ, UPDATE, DELETE. (ALL gives access to perform all operations).

Group Scopes

Group scope provide complete access to all functions the user can perform on the record. For instance, a group scope can allow a user to read, create, update, and delete records in all modules.

Example:

https://accounts.zoho.com/oauth/v2/auth?scope=ZService.modules.ALL,ZService.settings.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

In the above example, the user has access to all modules in the client ZService account.

Other examples are

• scope=ZService.modules.READ(Read-only permission)

• scope=ZService.modules.CREATE

• scope=ZService.modules.UPDATE

• scope=ZService.modules.DELETE

Separate Scopes

Separate scopes are used to provide access to data in a particular module without access to other modules.

https://accounts.zoho.com/oauth/v2/auth?scope=ZService.modules.leads.ALL,ZService.modules.deals.ALL,ZService.settings.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

The above scope gives the user access to only the leads and deals modules from the client Zoho Service account.

Additionally, you can set specific permissions, like read, create, update or delete, for each module. For examples:

• scope=ZService.modules.leads.READ(Read-only permission)

• scope=ZService.modules.leads.CREATE

• scope=ZService.modules.leads.UPDATE

• scope=ZService.modules.leads.DELETE

Multiple Scopes

Access tokens can also be generated with multiple scopes. In such cases, the scopes should be separated by commas. The format to provide multiple scope is service_name.scope_name.OPERATION_TYPE,service_name.scope_name.OPERATION_TYPE. For example, ZService.modules.READ,ZService.settings.READ.

Generate Access Token and Refresh Token

OAuth2.0 requests are usually authenticated with an access token, which is passed as bearer token. To use this access token, you need to construct a normal HTTP request and include it in an Authorization header along with the value of Bearer.

Note

• You must use your domain-specific Zoho accounts URL to generate access and refresh tokens. The following are the various domains and their corresponding accounts URLs.

  • For US: https://accounts.zoho.com

  • For AU: https://accounts.zoho.com.au

  • For EU: https://accounts.zoho.eu

  • For IN: https://accounts.zoho.in

  • For CN: https://accounts.zoho.com.cn

  • For JP: https://accounts.zoho.jp

  • For SA(Saudi Arabia): https://accounts.zoho.sa

  • For CA(Canada): https://accounts.zohocloud.ca

• If you have more than one organization, then the grant token generated will be specific to a particular organization, and the same applies to the access and refresh tokens generated using the grant token.

To generate access and refresh token:

1. Make a POST request with the following URL. Replace {accounts_URL} with your domain-specific Zoho accounts URL when you make the request.

   {accounts_URL}/oauth/v2/token

   Note: For security reasons, pass the below parameters in the body of your request as form-data.

   Request Parameters

   • grant_type

     Enter the value as "authorization_code".

   • client_id

     Specify client-id obtained from the connected app.

   • client_secret

     Specify client-secret obtained from the connected app.

   • redirect_uri

     Specify the Callback URL that you registered during the app registration.

   • code

     Enter the grant token you received after you made the authorization code request.

2. If the request is successful, you would receive the following:

   {
"access_token": "{access_token}",
"refresh_token": "{refresh_token}",
"api_domain": "https://www.zohoapis.com",
"token_type": "Bearer",
"expires_in": 3600
}

   
   

Response Parameters

• access_token

  Access token to access ZService APIs.

• refresh_token

  Refresh token to obtain new access tokens.

• expires_in

  Time in seconds after which the access token expires.

• api_domain

  Domain name of the API. Use this domain in your requests to make API calls to ZServices.

• token_type

  Type of token obtained. "Bearer" indicates this is an access token.

This completes the authentication. Once your app receives the access token, send the token in your HTTP authorization header to ZService API with the value "Zoho-oauthtoken {access_token}" for each endpoint (for each request).

Note

• Each access token is valid for only an hour and can be used only for the operations defined in the scope.

• A refresh token does not expire. Use it to refresh access tokens when they expire. For more details on the validity of the tokens, refer to Token Validity page.

• Use the value in the "api_domain" key to make API calls to ZServices. The URL varies based on the environment:

  • For sandbox, the domain would be sandbox.zohoapis.{domain}. Example: https://sandbox.zohoapis.eu

  • For developer, the domain would be developer.zohoapis.{domain}. Example: https://developer.zohoapis.au

• If your application has more than one environment, the access and refresh token generated for a user becomes organization-specific in an environment. Thus, you cannot use tokens generated for an organization in one environment to make API calls to the organization in another environment. For instance, you cannot use tokens generated for an organization in the Production environment to make API calls to the organizations in the sandbox or developer accounts.

Possible Errors

• invalid_client

  Resolution: You have passed an invalid Client ID or secret. Specify the correct client ID and secret.
  (or)
  There is a domain mismatch. You have registered the client and generated the grant token in a certain domain (US), but generating the tokens from a different domain (EU). Ensure that you generate the grant, access, and refresh tokens from the same domain using the same domain URL or Enable Multi-DC for your client to generate tokens from any domain.
  (or)
  You have passed the wrong client secret when multi-DC is enabled. Each DC holds a unique client secret. Ensure to pass the right client secret for that DC.

• invalid_code

  Resolution: The grant token has expired. The grant token is valid only for one minute in the redirection-based flow. Generate the access and refresh tokens before the grant token expires.
  (or)
  You have already used the grant token. You can use the grant token only once.
  (or)
  The refresh token to generate a new access token is wrong or revoked. Specify the correct refresh token value while refreshing an access token.

• invalid_redirect_uri

  Resolution: The redirect URI in the request mismatches the one registered in the developer console. Specify the correct redirect URI in the request.

Refresh Access Token

Access tokens expire after an hour of generation. To generate a new access token, use the refresh token you generated earlier.

• Make a POST request with the following URL:

  {Accounts_URL}/oauth/v2/token?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token

  Note

  You must use your domain-specific Zoho Accounts URL to refresh your access token.

  • For US: https://accounts.zoho.com

  • For AU: https://accounts.zoho.com.au

  • For EU: https://accounts.zoho.eu

  • For IN: https://accounts.zoho.in

  • For CN: https://accounts.zoho.com.cn

  • For JP: https://accounts.zoho.jp

  • For CA(Canada): https://accounts.zohocloud.ca

• If the request is successful, you will receive the following output:

  {
"access_token": "{new_access_token}",
"expires_in": 3600,
"api_domain": "https://www.zohoapis.com",
"token_type": "Bearer"
}

Note

• We have provided with a sample test OAuth in all the examples, so that you can test any example on your own. You can replace the sample OAuth Token with your actual token to test requests from your ZService account.

• For applications with multiple organizations, the refresh tokens generated for one organization in an environment cannot be used for another organization. For instance, you cannot use the refresh token generated for an organization in the Production environment to generate access tokens for the organizations in the sandbox or developer accounts.

• For information about the validity of the tokens, refer to the Token Validity page.

Revoking Refresh Token

If you want to revoke your refresh token,

• Make a POST request with the following URL:

  {Accounts_URL}/oauth/v2/token/revoke?token={refresh_token}

Note

• You must use your domain-specific Zoho Accounts URL to revoke your refresh token.See all the server-specific Account URLs.

• If you have multiple organizations, the refresh token that you revoke will be specific to a particular organization, and this action will not have an effect on other organizations in your application.

Client Credentials Flow

Compared to the flow of creating access tokens in the self-client flow, the client credentials flow can be used to perform one-time tasks like one-time data migration or testing ZService API calls, etc. We recommend using self client or server-based authorization for integration purposes. The main benefit of the client credentials flow is the simplicity in creating an access token, requiring only your client ID, client secret, scope, and soid.

Generating Access Token

To generate an access token using the client credentials flow, make an API call to the following endpoint with the mandatory parameters as discussed in the following "Parameters" section. The accounts-url is specific to the location (i.e., datacenter) where the client is registered. See all the server-specific URLs.

{accounts-url}/oauth/v2/token?client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials&scope={scope}&soid={soid}

Parameters

• client_idstring, mandatory

  Client ID (consumer key) that you obtained during client registration.

• client_secretstring, mandatory

  Client secret that you obtained during client registration.

• grant_typestring, mandatory

  Specify the value as "client_credentials".

• scopestring, mandatory

  The corresponding scope for the resource you want to access from the user's account. Multiple scopes can be given in comma separated format. Refer to the Scopes page for more details.

• soidstring, mandatory

  This parameter is derived from the unique ServiceOrg or organization or portal ID (zsoid).

  Syntax: ZService.{zsoid}. Example: ZService.600xxx46

  

  You can obtain zsoid from the UI by clicking on your profile picture where you will see the name of your organization. Click on the dropdown to view the name of the organization and the Org ID.

Response JSON

{
"access_token": "1000.b2caxxxxx3c6",
"scope": "ZService.org.ALL ZService.settings.ALL ZService.users.ALL ZService.templates.email.READ ZService.templates.inventory.READ ZService.modules.ALL",
"api_domain": "https://www.zohoapis.com",
"token_type": "Bearer",
"expires_in": 3600
}

• access_token

  Use this access token in the header of the API calls to access data in ZService. Note that the response does not contain a refresh token. When an access token expires, make an API call to the same endpoint to get a new access token (if required).

• scope

  The scope for the resource you want to access from the user's account that was provided in the parameters.

• api_domain

  Domain name of the API. Use this domain in your requests to make API calls to ZService.

• token_type

  Type of token obtained. "Bearer" indicates this is an access token.

• expires_in

  Time in seconds after which the access token expires.

Incremental Authorization

Incremental Authorization is an OAuth strategy that allows a client to request specific authorization scopes as and when needed. This means that the client does not have to request every possible scope that might be needed upfront, which might result in a bad user experience. Incremental Authorization is considered a best practice in Oauth Authorization Request as:

• Users are not overloaded with scopes in the initial stage

• Users can control the amount of data they share

For detailed information on implementing incremental authorization in your application, refer to the Zoho Accounts Incremental Authorization page.

Token Validity

Grant Token (Authorization code)

• Grant token is a one-time use token and valid for three minutes, by default. If you want to extend the expiry time, choose the required time from the drop-down while generating the token from the API console (applicable only to self-clients).

• You can generate a maximum of 10 grant tokens in a span of 10 minutes per client ID. If the limit is reached, "access_denied" exception will be thrown for the remaining time.

Access Token

• Each access token is valid for one hour.

• A maximum of 15 active access tokens can be stored per refresh token. When the 16th token is requested, the oldest token is invalidated. When an invalid access token is used, "INVALID_OAUTHTOKEN" exception will be thrown.

• You can generate a maximum of 10 access tokens from a refresh token in a span of 10 minutes.

• If the 10-minute throttle limit is reached, "Access Denied" error will be thrown. Reuse valid tokens to avoid this exception.

  {

"error_description":"You have made too many requests continuously. Please try again after some time.",

"error":"Access Denied",

"status":"failure"

}

Refresh Token

• Refresh tokens do not expire until a user revokes them.

• A maximum of 20 refresh tokens can be stored per user.

• When you generate the 21st refresh token, the first created refresh token gets invalidated.