TrainerCentral 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.
1. Go to https://accounts.zoho.com/developerconsole on your web browser.
2. Click Add Client ID and enter the following details:
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 TrainerCentral 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. |
prompt | Value must be consent. |
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.
The final step to access TrainerCentral' 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, TrainerCentral will issue a response to your application with the following information:
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.
| 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,
Example: Query String
https://accounts.zoho.com/oauth/v2/token/revoke?refresh_token=1000.dd7e47321d48b8a7e312e3d6eb1a9bb8.b6c07ac766ec11da98bf6a261e24dca4
Learn more about the OAuth 2.0 here.