Prerequisite - Generate OAuth Token

The Zoho SalesIQ REST API uses the OAuth 2.0 protocol to authorize and authenticate calls. OAuth is an industry open standard for authorization. It provides secure access to protected resources thereby reducing the hassle of asking for a username and password every time a user logs in.

You can follow some basic steps to access SalesIQ's Rest APIs using Oauth 2.0.

How to register your Application with Zoho's Developer Console?

You will have to first register your application with Zoho's Developer console in order get your user's client ID and client secret. To register your application:

  • Enter the required details in the form. Add your Client Name, Client Domain and the Authorized Redirect URI and click “Create”.

  • You will be provided with a set of OAuth 2.0 credentials such as a client ID and client secret that are known to both Zoho and your application.

How to get Authorization?

Next, you will have to call the authorization URL. The authorization URL should contain the following parameters.

Note: The first 4 parameters mentioned here are mandatory while the remaining three parameters are recommended.

Parameter Type Description
Client IDUnique IdentifierThe ID that was assigned to your app when you registered it.
response_typestring”code”
redirect_urlURLYour callback URL with authorization code and response token. This should be the same link which you used during registration.
ScopesstringSpecifies the scope allowed for your app. Has to be separated by commas.
Syntax:
Servicename.Scopename.Operation
Example: SalesIQ.chatdetails.READ
access_typestringOffline/Online (By default it is taken as Online).
The “Online” access_type gives your application only the access_token which is valid for one hour.
The “Offline” access_type will give the application an access-token as well as a refresh_token.
promptstringPrompt=”Consent”.
Prompts for user consent each time your app tries to access user credentials.
statestringA generated value that correlates the callback with its associated authorization request.

The Scope Name and Operations to the APIs.

API NameScope NameOperation
Chat ListchatdetailsREAD
Chat InfochatdetailsREAD
Chat TranscriptchattranscriptREAD
AttachmentschatdetailsREAD
VisitorDetailsvisitordetailsREAD
Update Visitor InfovisitordetailsUPDATE
Push NotificationPushNotificationsUPDATE

Example:

GET oauth/v2/auth
Host:: https://accounts.zoho.com

Query String:

https://accounts.zoho.com/oauth/v2/auth
?response_type=code&access_type=offline 
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&scope=SalesIQ.chatdetails.UPDATE
&redirect_uri=https://www.zylker.com/support &state=-5466400890088961855

Once this authorization URL is called, the user is now shown a “user consent page.”

If the user clicks “Accept” then Zoho redirects the user back to your site with an “Authorization code”. Your application can now request Zoho for an access token using the auth_code. If the user clicks “Deny” then the server returns an error.

Prompting re-consent

You can prompt the user to re-authorize your app every time the user logins in by adding the prompt=consent parameter to the authentication request. When prompt=consent is included, the consent screen is displayed every time the user logs into your app. For this reason, include prompt=consent only when necessary.

How to get the Access Token?

Once your application receives the Auth code, a new request can be made to receive an access token using which your app will receive the user credentials. This is an important step in the entire process and so be careful while setting the parameters for the same.

Note: The first 6 parameters mentioned here are mandatory while the remaining one parameter is recommended.

Parameter Type Description
CodeStringAuthorization Code obtained from the initial request.
Client IDUnique IdentifierThe ID that was assigned to your app when you registered it.
Client SecretStingYour app's secret.
Assigned when you register your app and available in your profile.
redirect_urlURLYour callback URL with authorization code and response token.
scopesstringSpecifies the scope allowed for your app. Has to be separated by commas.
statestringHas to be maintained the same during the entire process for authenticity.

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

expires_in - Time in milliseconds that the token remains valid.
token_type - Type of token. (”bearer”)
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.
You can store this data so that there is no need for authorization each time this user accesses your app.

Example:

POST oauth/v2/token
HOST:: https://accounts.zoho.com

Query String:

https://accounts.zoho.com/oauth/v2/token
?code=1000.fadbca4c2be2f08b0ce82a54f6344313.ba532585103af6f12a0f160
&grant_type=authorization_code
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&redirect_uri=https://www.zylker.com/support
&scope=SalesIQ.chatdetails.READ

How to use the Access Token?

Send the access token as a header when you call a Zoho SalesIQ REST API.

Example:

GET oauth/user/info

Query String:

GET
HOST: https://accounts.zoho.com/
Header:
Authorization= Zoho-oauthtoken <space> <access token>

When this access token with the available scopes invoke the URL the info as permitted in the scope is granted to the application. The user credentials is thus obtained and the regular sign up flow can be implemented.

How to get and use the Refresh Token?

In your request for access you can request a refresh token to be returned along with the access token. A refresh token provides your app access to Rest APIs even when the user is not logged in. To request a refresh token, add access_type=offline to the authentication request.

The refresh token will always be generated by the Prompt=consent. The max number of refresh token = 20. Once the limit is reached the first refresh token in terms of time will be deleted.

The Access Tokens have limited validity. In most general cases the access tokens expire in one hour. Until then, the access token has unlimited usage. Once it expires, your app will have to use the refresh token to request for a new access token.

For this new request, the parameters to be included are,

Parameter Type Description
client_idUnique IdentifierThe ID that was assigned to your app when you registered it.
client_secretStingYour app's secret.
Assigned when you register your app and available in your profile.
grant_typeStingrefresh_token
redirect_urlURLYour callback URL.
refresh_tokenstringThe refresh token provided along with the access token.

Example:

POST https://accounts.zoho.com/oauth/v2/token
HOST:: https://accounts.zoho.com

Query String:

?refresh_token=1000.4069dacb5684b2df29b60ed6865e889f.fd1f173360871d254bcf902062390367
&grant_type=refresh_token
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&redirect_uri=https://www.zylker.com/support
&scope=SalesIQ.chatdetails.UPDATE

You will now receive a new access token using which you can continue getting user credentials. This access token will also have a time limit of one hour.