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

HTTP request type : GET

Request params :

  • scope = Scopes for which token has to be generated (Ex: ZohoLens.userapi.READ,ZohoLens.sessionapi.CREATE)
  • 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 = code
  • redirect_uri = https://app.example.com/oauth (Use the Authorized redirect URIs that you specified in the API console registration process)
  • 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.

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

CopiedOn calling the above request API, it will redirect to the 'redirect_uri' given with the authorization grant appended to it like below:

https://app.example.com/oauth?state=tempstate&code=1000.47b8fa1a1676bda5da938decdf0cf0d6.d3f48797707de05fcac81d135dc7b6c0

3. Get an access token

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.

 

Sample HTTP request

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

Sample response

Copied {
   "expires_in" : 3000,
   "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
}