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:
3. Generate the access and 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.
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:
| Parameter | Description |
| scope | The scope required for your extension. |
| client_id | Client ID obtained during client registration. |
| state | A generated value that correlates the callback with its associated authorization request. |
| response_type | "code" |
| redirect_uri | The redirect URL given during client registration. |
| access_type | The 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.
| Parameter | Description |
| code | Authorization code obtained during grant token generation. |
| client_id | Client ID obtained during client registration. |
| client_secret | Client secret obtained during client registration. |
| redirect_uri | Redirect URL given during client registration. |
| grant_type | authorization_code |
| scope | Specify the scope allowed for your extension. |
| state | A 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.
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:
| Parameter | Description |
| client_id | Client ID obtained during client registration. |
| client_secret | Client secret obtained during client registration. |
| redirect_uri | Redirect URL given during client registration. |
| grant_type | refresh_token |
| refresh_token | The refresh token obtained during access token generation. (Step 3) |
| scope | Specify 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 Name | Header Value |
| Authorization | Zoho-oauthtoken<space>{{access token}} |
| contentType | application/json |
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