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 a 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 the 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.
redirect_urlURLYour callback URL with an 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.
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.
Prompts for user consent each time your app tries to access the user credentials.
statestringA random value(can be a number, a character or a string of characters) that you can assign to correlate the callback with its associated authorization request.

The Scope Name and Operations to the APIs - Click here.

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

GET oauth/v2/auth

Query String:

If the user clicks “Accept”, Zoho redirects the user back to your site where you can procure the authentication code from the parameter Code in the URL. Your application can now request Zoho for an access token using the 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 SecretStringYour 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 for which 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 can be used when the access token has timed out. This token can be used for 20 times 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.


POST oauth/v2/token

Query String:

How to use the Access Token?

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


GET oauth/user/info

Query String:

Authorization= Zoho-oauthtoken <space> <access token>

When this access token with the available scopes invokes the URL, the info as permitted in the scope is granted to the application. The user credentials are 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 the 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 maximum number of refresh tokens is 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 an 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_secretStringYour app's secret.
Assigned when you register your app and available in your profile.
redirect_urlURLYour callback URL.
refresh_tokenStringThe refresh token provided along with the access token.



Query String:


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