Toll free - 1800 102 9944Mon - Sat 9am to 6pm IST+91 7305654908Contact Us

OAuth

Zakya 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 every time a user logs in. Follow the steps listed here, to access Zakya'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

United States

.com

https://accounts.zoho.com/

India

.in

https://accounts.zoho.in/

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 Client Secret.

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 these credentials anywhere.

Step 2: Generating Grant Token

Redirect to the following authorization URL with the given params

https://accounts.zoho.com/oauth/v2/auth?

Parameter

Description

scope*

SCOPE for which the token to be generated. Multiple scopes can be given which has to be separated by commas. Ex : ZakyaAPI.FullAccess.all

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.

response_type*

code

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 offline and 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. By default it is taken as online

prompt

Prompts for user consent each time your app tries to access user credentials. Ex: Consent

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 code and 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

Request ExampleCopy
https://accounts.zoho.com/oauth/v2/auth?scope=ZakyaAPI.invoices.CREATE,ZakyaAPI.invoices.READ,ZakyaAPI.invoices.UPDATE,ZakyaAPI.invoices.DELETE&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&state=testing&response_type=code&prompt=consent&redirect_uri=http://www.zakya.com&access_type=offline

Step 3: Generate Access And Refresh Token

After getting code from the above step, make a POST request for the following URL with given params, to generate the access_token.

https://accounts.zoho.com/oauth/v2/token?

Parameter

Description

code*

code which is obtained in the above step

client_id*

Client ID obtained during Client Registration

client_secret*

Client secret obtained during Client Registration

redirect_uri*

This param should be same redirect url mentioned while adding Client

grant_type*

authorization_code

scope

SCOPE for which token to be generated. Ex : ZakyaAPI.fullaccess.all. Multiple scopes has to be separated by commas.

state

An opaque string that is round-tripped in the protocol; that is to say, value will be passed back to you.

Note: Fields with * are mandatory

In the response, you will get both access_token and refresh_token.

1. The access_token will expire after a particular period (as given in expires_in param in the response).

2. The 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.
Request ExampleCopy
https://accounts.zoho.com/oauth/v2/token?code=1000.dd7exxxxxxxxxxxxxxxxxxxxxxxx9bb8.b6c0xxxxxxxxxxxxxxxxxxxxxxxxdca4&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf&redirect_uri=http://www.zoho.com/inventory&grant_type=authorization_code

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

https://accounts.zoho.com/oauth/v2/token?

Parameter

Description

refresh_token

REFRESH TOKEN which is obtained in the above step

client_id

Client ID obtained during Client Registration

client_secret

Client secret obtained during Client Registration

redirect_uri

This param should be same redirect url mentioned while adding Client

grant_type

refresh_token

Request ExampleCopy
https://accounts.zoho.com/oauth/v2/token?refresh_token=1000.8ecdxxxxxxxxxxxxxxxxxxxxxxxx5cb7.463xxxxxxxxxxxxxxxxxxxxxxxxebdc&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf&redirect_uri=http://www.zoho.com/inventory&grant_type=refresh_token

Step 5: Revoking A Refresh Token

To revoke a refresh token, call the following POST URL with the given params

https://accounts.zoho.com/oauth/v2/token/revoke?

Parameter

Description

token

REFRESH TOKEN which is to be revoked

Copy
https://accounts.zoho.com/oauth/v2/token/revoke?token=1000.8ecdxxxxxxxxxxxxxxxxxxxxxxxx5cb7.4638xxxxxxxxxxxxxxxxxxxxxxxxebdc

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 Authorization
  • Header value should be Zoho-oauthtoken {access_token}

List of scopes available in Zakya :

Scope

Description

contacts

To access contacts related APIs Availabe types: ZakyaAPI.contacts.CREATE, ZakyaAPI.contacts.UPDATE, ZakyaAPI.contacts.READ, ZakyaAPI.contacts.DELETE

items

To access item related APIs Availabe types: ZakyaAPI.items.CREATE, ZakyaAPI.items.UPDATE, ZakyaAPI.items.READ, ZakyaAPI.items.DELETE

composite items

To access item related APIs Availabe types: ZakyaAPI.compositeitems.CREATE, ZakyaAPI.compositeitems.UPDATE, ZakyaAPI.compositeitems.READ, ZakyaAPI.compositeitems.DELETE

inventory adjustments

To access inventory adjustments related APIs Availabe types: ZakyaAPI.inventoryadjustments.CREATE, ZakyaAPI.inventoryadjustments.READ, ZakyaAPI.inventoryadjustments.DELETE

transfer orders

To access transfer order related APIs Availabe types: ZakyaAPI.transferorders.CREATE, ZakyaAPI.transferorders.READ, ZakyaAPI.transferorders.DELETE

settings

To access users, taxes, currencies related APIs Availabe types: ZakyaAPI.settings.CREATE, ZakyaAPI.settings.UPDATE, ZakyaAPI.settings.READ, ZakyaAPI.settings.DELETE

preferences

To access preferences related APIs Availabe types: ZakyaAPI.preferences.CREATE, ZakyaAPI.preferences.UPDATE, ZakyaAPI.preferences.READ, ZakyaAPI.preferences.DELETE

salesorder

To access salesorder related APIs Availabe types: ZakyaAPI.salesorders.CREATE, ZakyaAPI.salesorders.UPDATE, ZakyaAPI.salesorders.READ, ZakyaAPI.salesorders.DELETE

packages

To access Package related APIs Availabe types: ZakyaAPI.packages.CREATE, ZakyaAPI.packages.UPDATE, ZakyaAPI.packages.READ, ZakyaAPI.packages.DELETE

shipmentorders

To access Shipment order related APIs Availabe types: ZakyaAPI.shipmentorders.CREATE, ZakyaAPI.shipmentorders.UPDATE, ZakyaAPI.shipmentorders.READ, ZakyaAPI.shipmentorders.DELETE

invoices

To access invoices related APIs Availabe types: ZakyaAPI.invoices.CREATE, ZakyaAPI.invoices.UPDATE, ZakyaAPI.invoices.READ, ZakyaAPI.invoices.DELETE

customerpayments

To access customer payments related APIs Availabe types: ZakyaAPI.customerpayments.CREATE, ZakyaAPI.customerpayments.UPDATE, ZakyaAPI.customerpayments.READ, ZakyaAPI.customerpayments.DELETE

vendorpayments

To access vendor payments related APIs Availabe types: ZakyaAPI.vendorpayments.CREATE, ZakyaAPI.vendorpayments.UPDATE, ZakyaAPI.vendorpayments.READ, ZakyaAPI.vendorpayments.DELETE

creditnotes

To access credit notes related APIs Availabe types: ZakyaAPI.creditnotes.CREATE, ZakyaAPI.creditnotes.UPDATE, ZakyaAPI.creditnotes.READ, ZakyaAPI.creditnotes.DELETE

debitnotes

To access vendor credit related APIs Availabe types: ZakyaAPI.debitnotes.CREATE, ZakyaAPI.debitnotes.UPDATE, ZakyaAPI.debitnotes.READ, ZakyaAPI.debitnotes.DELETE

purchaseorder

To access purchaseorder related APIs Availabe types: ZakyaAPI.purchaseorders.CREATE, ZakyaAPI.purchaseorders.UPDATE, ZakyaAPI.purchaseorders.READ, ZakyaAPI.purchaseorders.DELETE

purchase receives

To access purchase receive related APIs Availabe types: ZakyaAPI.purchasereceives.CREATE, ZakyaAPI.purchasereceives.READ, ZakyaAPI.purchasereceives.DELETE

bills

To access bills related APIs Availabe types: ZakyaAPI.bills.CREATE, ZakyaAPI.bills.UPDATE, ZakyaAPI.bills.READ, ZakyaAPI.bills.DELETE