Steps to Generate OAuth Token

Step 1: Registering a client

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

To register,

  1. Go to Zoho Developer Console.
  2. Choose a client type:
  • Java Script: Applications that run exclusively on a browser and are independent of a web server.
  • Web Based: Applications that are clients running on a dedicated HTTP server.
  • Mobile: Applications that are installed on smart phones and tablets.
  • Non-browser Mobile Applications: Applications for devices without browser provisioning such as smart TVs and printers.
  • Self Client: Stand-alone applications that perform only back-end jobs (without any manual intervention) like data sync.

For more details, refer to OAuth Overview.

  1. Enter the following details:
  • Client Name: The name of your application you want to register with Zoho.
  • Homepage URL: The URL of your web page.
  • Authorized Redirect URIs: A valid URL of your application to which Zoho Accounts redirects you with a grant token(code) after successful authentication.​

  1. Click CREATE
  • You will receive the following credentials:
  • Client ID: The consumer key generated from the connected app.
  • Client Secret: The consumer secret generated from the connected app.

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

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 "".

Enter a valid homepage URL
Resolution: The homepage URL is invalid. Specify a valid homepage URL in the format "".

Mandatory Entries for Different Client Types
The following are the mandatory entries for different client types.

Client TypeClient NameHomepage URLRedirect URIsJS Domains
Java ScriptYYYY
Self ClientNNNNA

Step 2: Authorization Request

To use the Zoho People APIs, the users must authenticate the application to make API calls on their behalf with an access token.
The access token, in return, must be obtained from a grant token (authorization code). The Zoho People APIs use the authorization code grant type to provide access to protected resources.

For Zoho People Application, there are two ways in which you can generate the grant token based on the client type.

  • Server-based application
  • Self-client

Server Based Application

Server-based applications are chosen when your application is used by multiple users and requires user intervention during authorization. For this client type, you must use redirection-based code generation. 
Below is the authorization flow:

  1. The user clicks the Login with Zoho button on any third-party web-based application. The application redirects the user to the Zoho Login page, and the user enters the Zoho credentials.

  1.  The web application redirects the user to the Zoho OAuth server with the required scope in the Accounts URL. With the Client ID generated in step 1, the Authorization URL in the browser, would be like this:{client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

client_idThe client ID string that you obtain from the above process
redirect_uriOne of the redirect URI obtained in above step
  1. In the result page, click Accept

  1. You will be redirect to the "redirect_uri" that you specified during registration of the app.
    The URL of the page would be like this:


Sample :******************b20aab8ec260557362&location=us&


  1. Note down the "code={grant_token}" parameter.
    By default, refresh token can by attained in step 3, If a refresh token is required anytime, the below param can be passed when generating grant token

Note: Only 20 refresh tokens are allowed per user.

Scopes can be given as comma seperated values

For example, if you are going to use insert record API  & attendance bulk import API
Then Scopes required are:
insertRecord API - ZOHOPEOPLE.forms.CREATE or ZOHOPEOPLE.forms.ALL
bulkImport API - ZOHOPEOPLE.attendance.CREATE
so the value for multiple scope parameter can be given as below:
scopes = ZOHOPEOPLE.forms.ALL, ZOHOPEOPLE.attendance.CREATE

Possible Errors

Resolution: The value of the "response_type" key is not "code". Update the value as "code".
You have not passed the mandatory keys in the request. Pass all the mandatory keys in the request to generate the organization-specific grant token.


Resolution: The client ID is wrong or empty. Pass the right client ID. You can check your client ID from the developer console.

Resolution: The redirect URI value passed, and the one registered in the developer console mismatches. Pass the right redirect URI.

Resolution: The scope is invalid. Pass valid scopes.

Self-Client option 

Use this method to generate the organization-specific grant token if your application does not have a domain and a redirect URL.
You can also use this option when your application is a standalone server-side application performing a back-end job.

  1. Choose Self Client from the list of client types, and click Create Now.
  2. Click OK in the pop up to enable a self client for your account.

  1. Now, your client ID and client secret are displayed under the Client Secret tab.

  1. Click the Generate Code tab and enter the required scope separated by commas. Refer to our list of Scopes, for more details. The system throws an 'Enter a valid scope' error when you enter one or more incorrect scopes.
  2. Select the Time Duration for which the grant token is valid. Please note that after this time, the grant token expires.
  3. Enter a description and click Create.

  1. The organization-specific grant token code for the specified scope is displayed. Copy the grant token.

Note: Generating the organization-specific grant token is a one-time process, provided you generate the access and refresh tokens within the time the grant token is valid for

Step 3: Generating Access Tokens and Refresh Tokens

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.

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:
  • For AU:
  • For EU:
  • For IN:
  • For CN:
  • For JP:

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:

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


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

Request Parameter

grant_typeEnter the value as "authorization_code".
client_idSpecify the client-id obtained from the connected app.
client_secretSpecify client-secret obtained from the connected app.
redirect_uriSpecify the Callback URL that you registered during the app registeration.
codeEnter the grant token generated from the previous step

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

    "access_token": "{access_token}",
    "refresh_token": "{refresh_token}",
    "api_domain": "",
    "token_type": "Bearer",
    "expires_in": 3600

Response Parameter

access_tokenAccess token to access ZohoPeople APIs
refresh_tokenRefresh token to obtain new access tokens.
expires_inTime in seconds after which the access token expires.
api_domainDomain name of the API, Use this domain in your requests to make API calls to Zoho People.
token_typeType 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 Zoho People API with the value "Zoho-oauthtoken {access_token}" for each endpoint (for each request).

​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.

Possible Errors

Resolution: You have passed an invalid Client ID or secret. Specify the correct client ID and secret.
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.
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.

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.
You have already used the grant token. You can use the grant token only once.
The refresh token to generate a new access token is wrong or revoked. Specify the correct refresh token value while refreshing an access token.

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

Step 4: Refresh Access Token

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

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

  • For US:
  • For AU:
  • For EU:
  • For IN:
  • For CN:
  1.  Make a POST request with the following URL: 


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

    "access_token": "{new_access_token}",
    "expires_in": 3600,
    "api_domain": "",
    "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 People 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.