Zoho Lens - Authentication

Authentication

All Zoho Lens APIs need to be authenticated using an oauth token.

OAuth 2.0 is an open authorization protocol which grants third party applications limited access to user accounts on an HTTP service. The authentication and authorization process is facilitated only between the end-user and the HTTP service. Zoho APIs use OAuth 2.0 to provide dependable security for your application data. It delegates authorization and authentication for web and desktop applications, and mobile devices.

You can obtain an OAuth token by following the steps mentioned below:

• Register your application

• Get an authorization grant

• Get an access token

• Refreshing your Access Tokens

• Revoking a refresh token

• Token validity

1. Register your application

Before integrating Zoho APIs with your application using OAuth, you must register your application with Zoho. This can be done through the developer console of your Zoho account, where you will have to provide details regarding your application like Name , Website , Redirect URI, or Callback URL. Once the authorization is approved or denied, the user will be redirected to the callback URL specified at the time of registration.

Once your application is registered, the service will issue a client ID and a client secret. Client ID is used by Zoho to verify the identity of the application and has a public visibility. Client secret is used to authorize the appropriate resources that can be accessed by the authenticated application. Client secret will be known only to Zoho APIs and the authenticated application.

2. Get an authorization grant

To use the Zoho Lens 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 Lens APIs use the authorization code grant type to provide access to protected resources.

HTTP request type : GET

Request params :

• scope = Scopes for which token has to be generated (Ex: ZohoLens.userapi.READ,ZohoLens.sessionapi.CREATE,ZohoLens.reportapi.READ)
• client_id = Obtained from registering your client at the Zoho Accounts developer console.
• state = An opaque string that will be returned as a URI parameter.
• response_type = Value must be 'code'

  Note: For Client-based Applications, the 'response_type' value must be 'token'

• redirect_uri = https://app.example.com/oauth (Use the Authorized redirect URIs that you specified in the API console registration process)

Optional parameters

• access_type = Value can be 'offline' or 'online'. If the value is offline, you will receive a refresh token along with an access token for the first time you make the request. Once the access token expires you can use the refresh token to regenerate them. Whereas if the value is online, you will receive only an access token. If you forget your refresh token or cannot access it, use the following parameter along with access_type to receive a new refresh token.
Note : If the access_type is not mentioned as offline, by default it will be considered as online.
• prompt> - Value must be 'consent'. If this parameter is included in the query, every time you generate an OAuth token, the user's consent approval will be mandatory.
• Example: To receive another refresh token, include access_type=offline and prompt=consent in your authorization request.

Response params

• code - A two-minute authorization token that can be exchanged for an access token at Zoho Accounts and the code can be used only once.
• locationDetermines the user's domain location. Clients must make access token requests to that particular domain URI.

Available scopes :

• Userapi: Know who you are on Zoho Lens.
• Sessionapi: Create your remote assistance sessions using Zoho Lens.
• Reportapi: View remote assistance reports on Zoho lens.

3. Get an access token

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.

After getting the authorization grant, post it to the API to get the access token and the refresh token.

HTTP request type : POST

Request params :

• code = Obtained in the above step.
• client_id = Obtained from registering your client at the Zoho Accounts developer console.
• client_secret = Obtained from registering your application at the Zoho Accounts developer console
• redirect_uri = Same URI that was used in the above step.
• grant_type = Value must be 'authorization_code'

Response params

• access_token - A client-authorized key that lets the client access protected resources from Zoho. The client can make API requests using this access token for up to an hour after the creation of the token.
• refresh_token - Used to obtain a new access token after the old one expires. A refresh token does not expire. The maximum number of allowed refresh tokens per account is 20. The 21st refresh token will replace the first created refresh token.
• token_type - Provides the client with the information required to make an API request.
• expires_in - Time taken for an access token to expire, in seconds.

4. Refreshing your access tokens

Access tokens expire after an hour of generation. To generate a new access token, use the refresh token you generated earlier.

HTTP request type: POST

Request params:

• client_id - Obtained from registering your client at the Zoho Accounts developer console.
• grant_type - Value must be 'refresh_token'.
• client_secret - Obtained from registering your application at the Zoho Accounts developer console.
• refresh_token - A refresh token is used to obtain a new access token after the old one expires.

Response params:

• access_token - A client-authorized key that lets the client access protected resources from Zoho. The client can make API requests using this access token for up to an hour after the creation of the token.
• token_type - Provides the client with the information required to make an API request.
• expires_in - Time taken for an access token to expire, in seconds.

5. Revoking a refresh token

You may choose to revoke a refresh token when you no longer need access to data for a particular scope. To revoke a refresh token, you must send a revoke token request.

HTTP request type: POST

Token Validity

Grant Token (Authorization code)

• Grant token is a one-time use token and valid for three minutes, by default. If you want to extend the expiry time, choose the required time from the drop-down while generating the token from the developer console (applicable only to self-clients).
• You can generate a maximum of 10 grant tokens in a span of 10 minutes per client ID.

Access Token

• Each access token is valid for one hour.
• You can generate a maximum of 10 access tokens in a span of 10 minutes.
• When you generate the 11th access token, the first created access token will be deleted.

Refresh Token

• Refresh tokens do not expire until a user revokes them.
• You can generate a maximum of 10 access tokens from a refresh token in a span of 10 minutes.
• You can generate a maximum of 20 refresh tokens in a span of 10 minutes per client ID.
• When you generate the 21st refresh token, the first created refresh token gets deleted.