How does the OAuth 2.0 authentication work?

Terminologies

The following are the terms you need to know before you start using the Zoho Billing APIs.

Term	Description
Protected Resources	The Zoho Billing resources such as Invoices, Customers, SalesOrders, etc.
Resource Server	The Zoho Billing server that hosts the protected resources.
Resource Owner	An end-user of your organization who can grant access to the protected resources.
Client	An application that sends requests to the resource server to access the protected resources on behalf of the end-user.
Client ID	The consumer key generated from the connected application.
Client Secret	The consumer secret generated from the connected application.
Authentication Server	The server that provides the necessary credentials,such as Access Tokens and Refresh Tokens, to the client. In this case, Zoho Billing is the authorization server.
Authentication Code	The authorization server creates a temporary token and sends it to the client via the browser. The client will send this code to the authorization server to obtain access and refresh tokens.
Tokens
Access Token	The token that is sent to the resource server to access the user's protected resources. It provides secure and temporary access to Zoho Billing APIs and is used by the applications to make requests to the connected app. Each access token is valid only for an hour and can be used only for the operations that are specified in the scope.
Refresh Token	The token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.

Note: Access Tokens must be kept confidential since they define the type of API that you use. Do not expose your Access Tokens anywhere in public forums, public repositories, or on your website's client-side code like HTML or JavaScript. Exposing it to the public may lead to data theft, loss, or corruption.

Scopes

Scope determines which protected resource of an end-user a client has requested access to. A scope has three parameters: service name, scope name, and operation type.

The format to define a scope is
scope = service_name.scope_name.operation_type

Operation type: CREATE, READ, UPDATE, DELETE, ALL

List of scopes available in Zoho Billing:

Scope	Description	Available Operation Types
customers	Access the APIs of the Customers modules.	ZohoSubscriptions.customers.CREATE, ZohoSubscriptions.customers.UPDATE, ZohoSubscriptions.customers.READ, ZohoSubscriptions.customers.DELETE, ZohoSubscriptions.customers.ALL
subscriptions	Access the APIs of the Subscriptions modules.	ZohoSubscriptions.subscriptions.CREATE, ZohoSubscriptions.subscriptions.UPDATE, ZohoSubscriptions.subscriptions.READ, ZohoSubscriptions.subscriptions.DELETE, ZohoSubscriptions.subscriptions.ALL
invoices	Access the APIs of the Invoices modules.	ZohoSubscriptions.invoices.CREATE, ZohoSubscriptions.invoices.UPDATE, ZohoSubscriptions.invoices.READ, ZohoSubscriptions.invoices.DELETE, ZohoSubscriptions.invoices.ALL
creditnotes	Access the APIs of the Creditnotes modules.	ZohoSubscriptions.creditnotes.CREATE, ZohoSubscriptions.creditnotes.READ, ZohoSubscriptions.creditnotes.DELETE, ZohoSubscriptions.creditnotes.UPDATE, ZohoSubscriptions.creditnotes.ALL
products	Access the APIs of the Products modules.	ZohoSubscriptions.products.CREATE, ZohoSubscriptions.products.UPDATE, ZohoSubscriptions.products.READ, ZohoSubscriptions.products.DELETE, ZohoSubscriptions.products.ALL
plans	Access the APIs of the Plans modules.	ZohoSubscriptions.plans.CREATE, ZohoSubscriptions.plans.UPDATE, ZohoSubscriptions.plans.READ, ZohoSubscriptions.plans.DELETE, ZohoSubscriptions.plans.ALL
addons	Access the APIs of the Addons modules.	ZohoSubscriptions.addons.CREATE, ZohoSubscriptions.addons.UPDATE, ZohoSubscriptions.addons.READ, ZohoSubscriptions.addons.DELETE, ZohoSubscriptions.addons.ALL
coupons	Access the APIs of the Coupons module.	ZohoSubscriptions.coupons.CREATE, ZohoSubscriptions.coupons.UPDATE, ZohoSubscriptions.coupons.READ, ZohoSubscriptions.coupons.DELETE, ZohoSubscriptions.coupons.ALL
hostedpages	Access the APIs of the Hostedpages module.	ZohoSubscriptions.hostedpages.CREATE, ZohoSubscriptions.hostedpages.READ
payments	Access the APIs of the Payments module.	ZohoSubscriptions.payments.CREATE, ZohoSubscriptions.payments.UPDATE, ZohoSubscriptions.payments.READ, ZohoSubscriptions.payments.DELETE, ZohoSubscriptions.payments.ALL
settings	Access the APIs related to Taxes, Currencies, and Organization preferences in Settings	ZohoSubscriptions.settings.READ
webhooks	Access the APIs related to Events.	ZohoSubscriptions.webhooks.READ

Steps to generate and use OAuth token

1. Registering New Client

To make requests using the Zoho Billing APIs, you need to register your application with Zoho Billing. Here's how:

• Go to the Zoho Developer Console.
• Choose a client type.

Client Type	Description
Client-based Applications	Applications that are built to run exclusively on browsers independent of the web servers.
Server-based Applications	Web-based applications that are built to run with a dedicated HTTP server and intended for use by multiple Zoho accounts. These applications may address specific use cases for different Zoho accounts and should have both a dedicated backend server and web UI to handle the authorization process and the application's logic. The application redirects users to Zoho for the authorization process using a web browser, allowing users to grant permission for the app to access their Zoho data on their behalf.
Mobile-based Applications	Applications that are built to run on smartphones and tablets.
Non-browser Applications	Applications that run on devices without browsers such as smart TVs and printers.
Self Client	Applications that do not have a redirect URL or a web UI, operating solely in the backend without requiring user interaction. A self-client is commonly employed when both the application and Zoho services are managed by the same person, aiming to establish secure communication between them.

Note: For more details on Client types, refer to https://www.zoho.com/accounts/protocol/oauth.html

• Enter the following details.
• Client Name: The name of your application you want to register with Zoho Billing.
• Homepage URL: The URL of your webpage.
  Only the following client types require this:
1. Client-based applications
2. Server-based applications
3. Mobile-based applications
4. Non-browser applications
• Authorized Redirect URLs: A valid URL of your application to which Zoho Accounts redirects you with a grant token (code) after successful authentication.
  Only the following client types require this:
1. Client-based applications
2. Server-based applications
3. Mobile-based applications
4. Non-browser applications
• Click CREATE. You will receive the Client ID and Client Secret.

2. Make the Authorization Request

• An Access token is an OAuth token used to access Zoho's protected resources. The method for generating the access token depends on the app used. For example, server-based apps can use the authorization code flow to generate an access token, while client-based apps can use the implicit flow.
• However, in any method, the access token will be provided only after the user grants permission through consent. The access tokens are always granted for the specific scopes which are mentioned in the request, and the scopes will be displayed to the user while asking for permission.
• To use the Zoho Billing APIs, the users must authenticate the application to make API calls on their behalf with an access token. The access token, in return, must be obtained from a grant token (authorization code). The Zoho Billing APIs use the authorization code grant type to provide access to protected resources.
• There are two ways in which you can generate the grant token based on the client type.
1. Web based applications
2. Self client

i) Web Based applications

Note: Replace {Accounts_URL} with your domain specific Zoho Accounts URL while generating tokens.

To generate a grant token for web-based applications, hit the below GET HTTP request in any browser:

Request:

HTTP Request Type: GET

URI Endpoint: {Accounts_URL}/oauth/v2/auth

Request Parameters:

Mandatory:

client_id - Obtained from registering your client in the Zoho Accounts developer console.

response_type - Value must be code.

redirect_uri - The URI endpoint that Zoho Accounts will redirect the web browser to with the authorization code after authorizing the client.
Make sure the authorized redirect URI is the same as the one provided while registering your client.

scope - Sample scope - "ZohoSubscriptions.invoices.READ"

Optional:

access_type - Value can be offline or online. If the access_type is not mentioned as offline, by default it will be considered as online.

• If the value is offline, you will receive a refresh token along with the access token the first time you make the request. Once the access token expires, you can use the refresh token to regenerate it.
• If the value is online, you will receive only the access token. If you forget your refresh token or cannot access it, use the following parameter along with access_type to receive a new refresh token.

prompt - Value must be consent. If this parameter is included in the query, whenever you generate an OAuth token, the user's consent approval will be mandatory.

Example Request: To receive another refresh token, include access_type=offline and prompt=consent in your authorization request.

Response:

With the request, you'll be redirected to the 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 will be valid for 2 minutes.

On clicking Deny, the server will return an error.

ii) Self Client

Use this method to generate the organization-specific grant token if your application does not have a domain and a redirect URL. You can also use this option when your application is a standalone server-side application performing a back-end job.

To generate grant token:

1. Go to Zoho Developer Console and log in with your Zoho Billing username and password.
2. Choose Self Client from the list of client types, and click Create Now.
3. Click OK in the pop-up to enable a self client for your account. Your Client ID and Client Secret will be available in the Client Secret tab.
4. Click the Generate Code tab and enter the required scope separated by commas. Refer to our list of Scopes[Scopes link will be attached], for more details. The system will throw the Enter a valid scope error when you enter one or more incorrect scopes.
5. Select the Time Duration for which the grant token should be valid. Note that after the specified time, the grant token will expire.
6. Enter a description and click Create. The grant token code for the specified scope will be displayed. Copy it.

Possible errors:

1. invalid_redirect_uri in /oauth/v2/auth

Solution:

Ensure the Redirect uri you pass in /oauth/v2/auth matches the one you have registered in the developer console.

3. Generating Access and Refresh Tokens

OAuth2.0 requests are usually authenticated with an access token, which is passed as bearer token. To use this access token, you need to construct a normal HTTP request and include it in an authorization header along with the value of bearer.

Note: Replace {Accounts_URL} with your domain specific Zoho Accounts URL while generating tokens.

To generate access and refresh token, hit the below POST HTTP request:

Request:

HTTP Request Type: POST

URI Endpoint: {Accounts_URL}/oauth/v2/token

Request Parameters:

grant_type - Enter the value as authorization_code.

client_id - Specify the Client ID obtained from the connected app.

client_secret - Specify the Client Secret obtained from the connected app.

redirect_uri - Specify the Callback URL that you registered during the app registration.

code - Enter the grant token generated from step 2

Response:

• The access_token will expire after a particular period(in ms) (as given in the expires_in param of the response).
• The refresh_token is permanent and will be used to generate new access token if the current access token is expired.
• Each access token is only valid for one hour and can be used only for the operations defined in the scope.
• A refresh token does not expire. Use it to regenerate access tokens when they expire.
• Use the value in the api_domain key to make API calls to Zoho Billing

Note: Each time a re-consent 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.

Possible errors:

1. Facing "server error" occurred in /oauth/v2/token

Solution:

The endpoint /oauth/v2/token supports only POST request. Requests you hit directly from the browser are GET request. Since the token generation request contains sensitive information like client secret, refresh token, the GET request is not allowed for this endpoint.

When you make a POST request, the data sent to the server is stored in the request body of the HTTP request and they don't remain in browser history and is never cached.

POST request can be made from REST client tools like postman, advanced rest client, or from your application code.

2. invalid_code in /oauth/v2/token ( If the grant_type is authorization_code )

Solution:

The code value generated using /oauth/v2/auth is valid only for two minutes and is only one time usable. You will get invalid_code when you use have already used the code or you try to use an expired code.

3. Refresh Token missing in response

Solution:

a. To receive refresh token for the first time:

Include access_type=offline in /oauth/v2/auth to get refresh token along with the access token as a response for /oauth/v2/token.

b. To receive another refresh token:

• Passing access_type=offline will give the refresh token along with the access token only the first time you use.
• Adding the prompt=consent prompts for user consent whenever your app tries to access a user's details.
• To receive another refresh token, include access_type=offline and prompt=consent in your authorization request (/oauth/v2/auth).

4. invalid_client or invalid_client_secret in /oauth/v2/token

Solution:

Remove the new line character or extra space between the parameters.
Ensure you're using the client id and secret registered in the same domain where you're trying to generate token

5. invalid_client in /oauth/v2/token

Solution:

The values required for /oauth/v2/token must be sent as params. This request does not support sending params as a JSON object or as an array in the body. Therefore, ensure that you include the parameters in the query string.

4. Refreshing Access Token

Note: Replace {Accounts_URL} with your domain specific Zoho Accounts URL while generating tokens.

Access tokens expire after an hour of generation. To generate a new access token, use the refresh token you generated earlier in step 3. Make a HTTP POST request with the following URL:

Request:

HTTP Request Type: POST

URI Endpoint: {Accounts_URL}/oauth/v2/token

Request Parameters:

refresh_token - Refresh token generated.

grant_type - Enter the value as refresh_token.

client_id - Specify the Client ID obtained from the connected app.

client_secret - Specify the Client Secret obtained from the connected app.

Response:

The new access token will be received in response

Possible errors:

1. invalid_code in /oauth/v2/token ( If the grant_type is refresh_token )

Solution:

Ensure the refresh_token has not been deleted. It may be deleted in the following cases:

1. You revoked it from the Connected Apps in your Zoho Accounts.
2. You revoked it using https://accounts.zoho.com/oauth/v2/token/revoke?token={refresh_token}
3. You changed your Zoho Accounts password and opted for the removal of the web sessions.

5. Revoking Refresh token

Note: Replace {Accounts_URL} with your domain specific Zoho Accounts URL while generating tokens.

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

Request:

HTTP Request Type: POST

URI Endpoint: {Accounts_URL}/oauth/v2/token/revoke

Request Parameters:

token - Refresh token that has to be revoked.

6. Calling an API

The access Token can be passed only in the header and cannot be passed in the request param

• Header name - Authorization
• Header value - Zoho-oauthtoken {access_token} (Strictly follow this format.)

Possible errors:

1. If the OAuth token is not properly sent in the headers, unauthorized error may occur.

Solution:

Make sure the format of Header value is correct as mentioned above

Token Validity

Grant Token (Authorization code)

For Self Client: - The grant token is a one-time use token and it is valid for three minutes, by default. If you want to extend its expiration time, choose the required time from the drop-down while generating the token from the API console.

For Other Clients: - The grant token is a one-time use token and it is valid for two minutes.

You can generate a maximum of 10 grant tokens in a span of 10 minutes per client ID. If the limit is reached, "access_denied" exception will be thrown for the remaining duration.

Access Token

Each access token is valid for one hour.

A maximum of 15 active access tokens can be stored per refresh token. When the 16th token is requested, the oldest token is invalidated. When an invalid access token is used, "INVALID_OAUTHTOKEN" exception will be thrown.

You can generate a maximum of 10 access tokens from a refresh token in a span of 10 minutes.

If the 10-minute throttle limit is reached, "Access Denied" error will be thrown. Re-use valid tokens to avoid this exception.

Refresh Token

Refresh tokens do not expire until a user revokes them.

A maximum of 20 refresh tokens can be stored per user.

When you generate the 21st refresh token, the oldest refresh token will become invalid.

Multi DC support

To access information of the users from different regions you can use the Multi DC feature. If you want to use the Client ID created in one DC in other DCs, you need to enable Multi DC for that specific client ID from your developer console. To enable:

• Open Zoho Developer Console.
• Select the required client.
• Go to Settings and enable Multi DC

Once enabled, you will be able to make /oauth/v2/token call to the respective DC based on the user's location. (.com,.eu,.in, and other DCs).

To know the region to which a user belongs, check the response to your /oauth/v2/auth call. The response will look like:

[redirect-url]?code=1000.0fxxxxxxxxxxxxxxe5.cfffcfxxxxxxx89&location=eu&accounts-server=https://accounts.zoho.eu&

The location value and the accounts-server represents to the location where the user account resides.

If the user account is in the EU, the generated code will also be in EU only and not in other DCs. Therefore, the correct request would be https://accounts.zoho.eu/oauth/v2/token

You must use your domain-specific Zoho Accounts URL to generate grant token, access and refresh tokens, and to revoke tokens. The following are the various domains and their corresponding accounts URLs.

Data Center	Domain	Base API URI
United States	.com	https://www.zohoapis.com/billing/
Europe	.eu	https://www.zohoapis.eu/billing/
India	.in	https://www.zohoapis.in/billing/
Australia	.com.au	https://www.zohoapis.com.au/billing/
Japan	.jp	https://www.zohoapis.jp/billing/
Canada	.ca	https://www.zohoapis.ca/billing/
China	.com.cn	https://www.zohoapis.com.cn/billing/
Saudi Arabia	.sa	https://www.zohoapis.sa/billing/