Authentication

All Zoho Learn's API's need to be authenticated using an OAuth token.

You can obtain an OAuth token by registering your extension with Zoho's Developer Console.
 

Register as a new client by accessing this website:

https://accounts.zoho.com/developerconsole

1. Click on Add Client ID and give the following :

• Client Name

• Client Domain

• Authorized redirect URLs 

   

2. Click Create.
   Upon providing the necessary details for registering, you are given a set of OAuth credentials known as client id and client secret exclusive for your extension. These credentials will be known to both Zoho and your extension.

Authorization by generating grant token  

Redirect the user to the authorization URL, and the authorization will be done when the user grants access in the "user consent" page.

Mandatory case-sensitive fields to be passed in the authorization URL are as below:

Sample request to generate grant token

GET oauth/v2/auth

Host: https://accounts.zoho.com

Query String:

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoLearn.space.READ&client_id=xxxx.yyy &state=zzz &response_type=code &redirect_uri=http://application_name.com/&access_type=offline

Sample response on generating grant token 

http://accounts.zoho.com/oauth2callback?state=zzz&code=xxx

Getting the access token

Once your extension receives the Auth code, a new request can be made to receive an access token using which your app will receive the user credentials.

The code parameter can be obtained from the response of the initial request sent.

Below are parameters to be passed in the URL.

Once the request along with the authorization code is sent, Zoho will issue a response to your app which will give you the following information.

• expires_in - Time in milliseconds that the token remains valid.

• token_type - Type of token. It is bearer in this case.

• access_token - Access token for the user. This token can be used for the final API calls and will be valid only for an hour.

• refresh_token - Refresh token to use when the token has timed out. This token is permanent and can be used multiple times (limit - 20) to refresh the app and get a new access token.

   

All REST APIs should be accessed with an OAuth token. Send the access token as a header when you call a Zoho Learn REST API.

All headers should have the following:

• Header name: Authorization

• Header value: Zoho-oauthtoken<space>access token

• Content type:"application/json"

Sample request to generate access token  

POST oauth/v2/token

Host: https://accounts.zoho.com 

Query String:

https://accounts.zoho.com/oauth/v2/token?code=xxx&grant_type=authorization_code&scope=ZohoLearn.course.CREATE, ZohoLearn.course.READ, ZohoLearn.manual.UPDATE,ZohoLearn.article.DELETE&client_id=xxx.yyy&client_secret=xxx&redirect_uri=http://application_name.com/

Sample response on generating the access token  

{ "access_token": "f2*********************4f", "refresh_token": "12*********************0c", "token_type":"Bearer", "expires_in": 3600000 }

Example of using the access token  

Request URL: GET https://learn.zoho.com/nativeapi/v2/tasks

Request Header: Authorization: Zoho-oauthtoken<space>xxx

Generating the access token from refresh token 

You can request for a refresh token to be generated along with the access token. To request for a refresh token, add access_type=offline in the authentication request.

The refresh token will always be generated by prompt=consent

In most cases, the access tokens expire in one hour. Until then, the access token has unlimited usage. Once the access token expires, the refresh token can be used to generate a new access token.

Example for generating the access token using refresh token  

Request URL: POST https://accounts.zoho.com/oauth/v2/token

Host: https://accounts.zoho.com

Query String :

https://accounts.zoho.com/oauth/v2/token?refresh_token=xxx.yyy.zzz&grant_type=refresh_token&scope=ZohoLearn.course.CREATE, ZohoLearn.course.READ, ZohoLearn.manual.UPDATE,ZohoLearn.article.DELETE&client_id=xxx.yyy&client_secret=xxx&redirect_uri=http://application_name.com/