Getting Started - Oauth token generation

Zoho ShowTime APIs follows the OAuth 2.0 protocol to authorize and authenticate your requests. OAuth 2.0 is a token based authorization framework that enables limited access to the third-party application. It acts as an intermediary on behalf of the user and provides controlled access, i.e. access only to the resources authenticated by the user and blocking the rest. This strengthens the security of user data.

Follow the steps to generate an OAuth token:

1. Register your application

2. Generate the grant token

3. Generate the access and refresh token

4. Regenerate access tokens

5. Revoke the refresh token

1. Register your application (as a new client)

1. Go to https://accounts.zoho.com/developerconsole on your web browser.

2. Click Add Client ID and enter the following details:

  • Client Name is the name of your application.
  • Client Domain is your URL to access the application.
  • Redirect URL is the callback URL of your application to which the user will be redirected upon successful authorization. The server returns a code parameter as a query string in the redirect URL. This code is used to obtain access and refresh tokens.

3. Finally, click Create.

4. On successful registration, you will be given a set of OAuth credentials known as the Client ID and Client Secret which are unique to your application. These credentials will be known to both Zoho and your application.

2. Generate the grant token

1. Enter the authorization URL https://accounts.zoho.com/oauth/v2/auth along with values of the below parameters as a query string.

The mandatory case-sensitive parameters to be passed with the authorization URL are given in the table below:

ParameterDescription
scopeThe scope required for your extension.
client_idClient ID obtained during client registration.
stateA generated value that correlates the callback with its associated authorization request.
response_type"code"
redirect_urlThe redirect URL given during client registration.
access_typeThe access type will be either online or offline.

2. You will be prompted for consent in user authorization page. Click Accept.
Note: This code will be valid for two minutes and can be used to obtain access and refresh token. 

3.Generate the access and refresh token

The final step to access Zoho Showtimes' APIs is to authenticate with an access token. The authorization code obtained in the step above under Generate the grant token request can be used to get your access and refresh token. 

Note: This code can be used only once. If the code expires then it has to be regenerated.

1. Make a POST request to the following URL https://accounts.zoho.com/oauth/v2/token using the parameters in the table below.

ParameterDescription
codeAuthorization code obtained during grant token generation.
client_idClient ID obtained during client registration.
client_secretClient secret obtained during client registration.
redirect_urlRedirect URI given during client registration.
grant_typeauthorization_code
scopeSpecify the scope allowed for your extension.
stateA generated value that correlates the callback with its associated authorization request. Must be kept the same during the entire process for authenticity.

2. On successful authorization, Zoho will issue a response to your application with the following information:

  • expires_in: Time in milliseconds that the token remains valid.
  • token_type: Type of token. In this case, it will be bearer.
  • access_token: Access token for the user. This token can be used for the final API calls and will only be valid for one hour.
  • refresh_token: Refresh token to use when the token has timed out. This token is permanent and can be used up to 20 times to refresh the app and get a new access token.

4. Regenerate Access Token

Access tokens have limited validity. In most cases, access tokens expire in one hour. The access token can be used an unlimited number of times during this period. Once the access token expires, the refresh token can be used to generate a new access token.

  • Make a POST request to https://accounts.zoho.com/oauth/v2/token with the parameters below:
ParameterDescription
client_idClient ID obtained during client registration.
client_secretClient secret obtained during client registration.
redirect_urlRedirect URI given during client registration.
grant_typerefresh_token
refresh_tokenThe refresh token obtained during access token generation. (Step 3)
scopeSpecify the scope allowed for your extension.

Sample request using the OAuth token

The access token must be passed as a header when you call any REST API. Please note that the access token can only be passed as a request header and not as a request parameter.

The list of mandatory headers is:

Header NameHeader Value
AuthorizationZoho-oauthtoken<space>{{access token}}
contentTypeapplication/json

5. Revoke the refresh token

If you no longer want to access the application, you can revoke the access as below, 

  • Make a POST request to the following URL https://accounts.zoho.com/oauth/v2/tokenrevoke

Example: Query String

https://accounts.zoho.com/oauth/v2/token/revoke?refresh_token=1000.dd7e47321d48b8a7e312e3d6eb1a9bb8.b6c07ac766ec11da98bf6a261e24dca4