Steps for generating OAuth Token | OAuth | Access | Zoho People (2024)

Steps to Generate OAuth Token

• Step 1: Registering a Client
• Step 2: Making the Authorization Request
• Step 3: Generating Tokens
• Step 4: Refreshing your Access Tokens

Step 1: Registering a client

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

To register,

1. Go toZoho 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.

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

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

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

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.

2. 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:

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

3. In the result page, clickAccept

​

4. 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:

{redirect_uri}?code={grant_token}&location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com

Sample :

5. 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
   prompt=consent​

Possible Errors

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.

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

4. 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.
5. Select the Time Duration for which the grant token is valid. Please note that after this time, the grant token expires.
6. Enter a description and click Create.

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

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.

{Accounts_URL}/oauth/v2/token

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

Request Parameter

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 Parameter

This completes the authentication. Once your app receives the access token, send the token in your HTTP authorization header to Zoho PeopleAPI 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 toToken Validity page.

Possible Errors

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: 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

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

2. 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 Peopleaccount.

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.