Zoho REST APIs uses the OAuth 2.0 protocol to authorize and authenticate calls. It provides secure access to protect resources thereby reducing the hassle of asking for a username and password everytime a user logs in. Follow the steps listed here, to access Zoho’s APIs using OAuth 2.0
Note:The API URLs in this section should be modified, based on your domain.
|Data Center||Domain||Base API URI|
You can read more about this here.
Step 1: Registering New Client
You will have to first register your application with Zoho's Developer console in order get your
Client ID and
To register your application, go to https://accounts.zoho.com/developerconsole and click on
Add Client ID. Provide the required details to register your application.
On successful registration, 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. Do not share this credentials anywhere.
Step 2: Generating Grant Token
Redirect to the following authorization URL with the given params
|scope *||SCOPE for which the token to be generated. Multiple scopes can be given which has to be separated by commas. Ex :
|client_id *||Client ID obtained during Client Registration|
|state||An opaque string that is round-tripped in the protocol; ie., whatever value given to this will be passed back to you.|
|redirect_uri *||One of the redirect URI given in above step. This param should be same redirect url mentioned while registering the Client|
|access_type||The allowed values are
|prompt||Prompts for user consent each time your app tries to access user credentials. Ex:
Note: Fields with
* are mandatory
On this request, you will be shown with a "user consent page".
Upon clicking “Accept”, Zoho will redirect to the given redirect_uri with
state param. This code value is mandatory to get the access token in the next step and this code is valid for 60 seconds.
On clicking “Deny”, the server returns an error
Follow the below steps to generate grant token from the Client ID:
- Go to https://accounts.zoho.com/developerconsole
- Click the Overflow icon and select Self Client from the options.
- Enter the scope and set the expiry time.
- Click View Code to generate the code.
Step 3: Generate Access and Refresh Token
code from the above step, make a POST request for the following URL with given params, to generate the
|client_id*||Client ID obtained during Client Registration|
|client_secret*||Secret key obtained during Client Registration|
|redirect_uri*||This param should be same redirect url mentioned while adding Client|
Note: Fields with
* are mandatory
In the response, you will get both
access_token will expire after a particular period (as given in
expires_in param in the response).
refresh_token is permanent and will be used to regenerate new
access_token, if the current access token is expired.
Note: Each time a re-consent page is accepted, a new refresh token is generated. The maximum limit is 20 refresh tokens per user. If this limit is crossed, the first refresh token is automatically deleted to accommodate the latest one. This is done irrespective of whether the first refresh token is in use or not.
2.Step 1, 2 and 3 are one time processes that you need to follow when you are accessing Zoho's API for the first time. From the next time, you can jump to step 4 and use the refresh_token to generate a new access_token.
Step 4: Generate Access Token From Refresh Token
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. Redirect to the following POST URL with the given params to get a new access token
|refresh_token||REFRESH TOKEN which is obtained in the above step|
|client_id||Client ID obtained during Client Registration|
|client_secret||Secret key obtained during Client Registration|
|redirect_uri||This param should be same redirect url mentioned while registering Client|
Step 5: Revoking a Refresh Token
To revoke a refresh token, call the following POST URL with the given params
|token||REFRESH TOKEN which is to be revoked|
Step 6: Calling An API
Access Token can be passed only in header and cannot be passed in the request param.
- Header name should be
- Header value should be
List of scopes available in Zoho Invoice :
|contacts||To access contacts related APIs
|settings||To access items, expense categories, users, taxes, currencies related APIs
|estimates||To access estimates related APIs
|invoices||To access invoices related APIs
|customerpayments||To access customer payments related APIs
|creditnotes||To access credit notes related APIs
|projects||To access projects related APIs
|expenses||To access expenses related APIs