API Docs
/
No Results Found
OAuth

OAuth

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

Data Center Domain Base API URI
United States .com https://accounts.zoho.com/
Europe .eu https://accounts.zoho.eu/
India .in https://accounts.zoho.in/
Australia .com.au https://accounts.zoho.com.au/
Japan .jp https://accounts.zoho.jp/

Step 1: Registering New Client

First, you will have to register your application with Zoho's Developer Console to get your Client ID and Client Secret.

To register your application, go to https://api-console.zoho.com and click Add Client ID.

On the API Console website, you'll be faced with multiple client types to choose from, we'd recommend to select either Server-based Applications or Self Client as your client type. Learn more about registering a new client.

After successfully registering your client, you will be provided with a set of OAuth 2.0 credentials namely, the Client ID and Client Secret , which 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 has to be generated. Multiple scopes can be given which have to be separated by commas. E.g. : ZohoSubscriptions.fullaccess.all
client_id * Client ID obtained while registering the client
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 parameter 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. E.g. 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 Example

Click to copy
https://accounts.zoho.com/oauth/v2/auth? scope=ZohoSubscriptions.invoices.CREATE,ZohoSubscriptions.invoices.READ,ZohoSubscriptions.invoices.UPDATE,ZohoSubscriptions.invoices.DELETE& client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V& state=testing& response_type=code& redirect_uri=http://www.zoho.com/subscriptions& 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 while registering the client
client_secret* Client secret obtained while registering the client
redirect_uri* This parameter should be the same redirect url mentioned while registering the client
grant_type* authorization_code
scope Scope for which token has to be generated. Eg : ZohoSubscriptions.fullaccess.all. Multiple scopes have to be separated by commas.
state An opaque string that is round-tripped in the protocol; i.e, the 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 Example

Click to copy
$ curl https://accounts.zoho.com/oauth/v2/token \ -X POST \ -d 'code=1000.dd7e47321d48b8a7e312e3d6eb1a9bb8.b6c07ac766ec11da98bf6a261e24dca4' \ -d 'client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V' \ -d 'client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf' \ -d 'redirect_uri=http://www.zoho.com/subscriptions' \ -d '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 that is obtained in the previous step
client_id Client ID obtained while registering the client
client_secret Client secret obtained while registering the client
redirect_uri This parameter should be the same redirect url mentioned while registering the Client
grant_type refresh_token

Request Example

Click to copy
$ curl https://accounts.zoho.com/oauth/v2/token \ -X POST \ -d 'refresh_token=1000.8ecd474019e31d52d2f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc' \ -d 'client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V' \ -d 'client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf' \ -d 'redirect_uri=http://www.zoho.com/subscriptions' \ -d '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.

Request Example

Click to copy
$ curl https://accounts.zoho.com/oauth/v2/token/revoke \ -X POST \ -d 'token=1000.8ecd474019e31d522f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc' \

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 Zoho Subscriptions :

Scope Description
customers To access customer related APIs
Availabe types: ZohoSubscriptions.customers.CREATE, ZohoSubscriptions.customers.UPDATE, ZohoSubscriptions.customers.READ, ZohoSubscriptions.customers.DELETE
subscriptions To access subscriptions related APIs
Availabe types: ZohoSubscriptions.subscriptions.CREATE, ZohoSubscriptions.subscriptions.UPDATE, ZohoSubscriptions.subscriptions.READ, ZohoSubscriptions.subscriptions.DELETE
invoices To access invoice,unbilled charge related APIs
Availabe types: ZohoSubscriptions.invoices.CREATE, ZohoSubscriptions.invoices.UPDATE, ZohoSubscriptions.invoices.READ, ZohoSubscriptions.invoices.DELETE
creditnotes To access credit note related APIs
Availabe types: ZohoSubscriptions.creditnotes.CREATE, ZohoSubscriptions.creditnotes.READ, ZohoSubscriptions.creditnotes.DELETE
products To access product related APIs
Availabe types: ZohoSubscriptions.products.CREATE, ZohoSubscriptions.products.UPDATE, ZohoSubscriptions.products.READ, ZohoSubscriptions.products.DELETE
plans To access plan related APIs
Availabe types: ZohoSubscriptions.plans.CREATE, ZohoSubscriptions.plans.UPDATE, ZohoSubscriptions.plans.READ, ZohoSubscriptions.plans.DELETE
addons To access addon related APIs
Availabe types: ZohoSubscriptions.addons.CREATE, ZohoSubscriptions.addons.UPDATE, ZohoSubscriptions.addons.READ, ZohoSubscriptions.addons.DELETE
coupons To access coupon related APIs
Availabe types: ZohoSubscriptions.coupons.CREATE, ZohoSubscriptions.coupons.UPDATE, ZohoSubscriptions.coupons.READ, ZohoSubscriptions.coupons.DELETE
hostedpages To access hostedpage related APIs
Availabe types: ZohoSubscriptions.hostedpages.CREATE, ZohoSubscriptions.hostedpages.READ
payments To access payments related APIs
Availabe types: ZohoSubscriptions.payments.CREATE, ZohoSubscriptions.payments.UPDATE, ZohoSubscriptions.payments.READ, ZohoSubscriptions.payments.DELETE
settings To access taxes,organization related APIs
Availabe types: ZohoSubscriptions.settings.READ
webhooks To access events related APIs
Availabe types: ZohoSubscriptions.webhooks.READ