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:

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.

Organization-Specific Grant Token (Authorization Code)

  • The user can choose to grant access to the application only to a particular organization (either in the Production, Sandbox, or Developer environment of Lens). Therefore, the access and refresh token generated for a user becomes organization-specific in an environment. For instance, the application owner cannot use tokens generated for an organization in the Production environment to make API calls to the organizations in the sandbox or developer accounts.
  • If your web-based application has more than one organization in multiple environments (for instance, one in production, and two each in sandbox and developer environments), the user will be allowed to choose the organization for which the grant token must be generated. On the contrary, if your application has only one organization (for instance, one in production and none in sandbox or developer environments), the system automatically generates the grant token for the same, without asking for any choices.
  • For self-clients, the system presents the list of available organizations, irrespective of the number of organizations in your application.

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 :

Scope

Scope operations available

userapi

 

ZohoLens.userapi.READ


 
sessionapi

 

ZohoLens.sessionapi.CREATE


 
reportapi

 

ZohoLens.reportapi.READ

 

 

  • 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.

Sample HTTP request

Copiedhttps://accounts.zoho.com/oauth/v2/auth?
scope={scope}&
client_id={client_id}&
response_type=code&
access_type={"offline"or"online"}&
redirect_uri={redirect_uri}

Sample response

Copiedhttps://www.zylker.com/oauthredirect
?code={code}
&location=us

Zoho Accounts authenticates the user and displays a consent screen for confirming authorization request. Once the end user grants the authorization request, Zoho Accounts sends an authorization grant code to the redirect URI client. On calling the above request API, it will redirect to the 'redirect_uri' given with the authorization grant appended to it like above.

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'

Note: A Refresh Token will be generated only once for the registered application.

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.
Note:
  • Using a refresh token a client can create up to ten access tokens in a span of ten minutes. If the limit is reached, the access token creation will be blocked for the rest of the ten minutes.
  • You can save the refresh and access tokens and reuse them.

 

Sample HTTP request

Copiedhttps://accounts.zoho.com/oauth/v2/token?
client_id={client_id}&
client_secret={client_secret}&
code={code}&
grant_type={authorization_code}&redirect_uri={redirect_uri}

Sample response

Copied {
   "expires_in" : 3000,
   "token_type" : "Bearer",
   "refresh_token" : "{new_refresh_token}",
   "access_token" : "{new_access_token}",
 }

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.

Sample HTTP request

Copiedhttps://accounts.zoho.com/oauth/v2/token?
client_id={client_id}&
grant_type=refresh_token&
client_secret={client_secret}&
refresh_token={refresh_token}

Sample response

Copied{
    "access_token" : "{new_access_token}",
    "token_type" : "Bearer",
    "expires_in" : 3600
}

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

Note:

  • You must use your domain-specific Zoho Accounts URL to revoke your refresh token.
  • If you have multiple organizations, the refresh token that you revoke will be specific to a particular organization, and this action will not have an effect on other organizations in your application.
  • When you revoke a refresh token, the system revokes all the access tokens generated using that refresh token.

Sample request

Copiedhttps://accounts.zoho.com/oauth/v2/token/revoke?
token={refresh_token}

Sample response

Copied{"status": "success"}

If the refresh token is invalid, the revoke token request will not be executed and you will receive an HTTP status code 400.

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.