Frequently Asked Questions - OAuth 2.0

What is the purpose of using OAuth? #

OAuth is the industry standard protocol for authentication and authorization, providing enhanced security compared to Auth Tokens. Unlike Auth Tokens, OAuth tokens have a limited validity, ensuring better protection for user data. With OAuth, an application needs to request the user's permission for accessing their information through a web session. Users grant delegated access to resources authenticated by them, and they can revoke the access granted to applications at any time. Most importantly, OAuth eliminates the need for your application to repeatedly request permission from the user each time it accesses their data.

Why don't we support client credentials to access Bigin resources? #

Bigin allows users to work with multiple organizations. To create a token, users must be in a session and choose the specific organization for which they want the token to be generated. Therefore, client credentials are not supported to access Bigin resources. Instead, we suggest users use Self Client for such requests.

What is the significance of the client ID? #

The client ID serves as a unique identifier for your application, which is registered in the API console. When your application interacts with Bigin APIs using the access token (generated using the registered client ID), the client ID helps Bigin identify and authenticate your application.

Why do I receive the "Cookie is disabled in your browser. Please enable the cookie to continue." message? #

If you receive this message, it indicates that cookies are disabled in your browser settings. To resolve this issue, first ensure that you have enabled cookies in your browser settings. If cookies are already enabled and you still get the message, try disabling browser extensions and attempt to make a request to /oauth/v2/auth from your browser again.

What is the HTML response when making a GET request to authenticate users (oauth/v2/auth)? #

When you make a GET request for user authorization (/oauth/v2/auth), the HTML response will display the user prompt screen. Here, users will be prompted to select the specific organization for which they want to provide access and to grant or deny permission for the application to access their details. This process requires a web session. After users grant authorization, the authorization server will send an authorization grant code to the redirect URI. Therefore, we recommend trying this process from a browser.

Why do we need the redirect_uri? #

The redirect_uri specified in the GET request for user authorization (oauth/v2/auth) is used within your application to receive the response after the user grants or denies access to their information in Bigin. It's essential when you want to access a Bigin user's details through your application.

Why does invalid_redirect_uri occur when I make a GET request for user authorization (oauth/v2/auth)? #

The redirect_uri used in the GET request for user authorization (oauth/v2/auth) must match with the Authorized Redirect URIs specified for the registered OAuth client in the API console.

How can I automate Bigin's OAuth flow from the backend, bypassing the prompt and generating tokens without user intervention through a web browser? #

To automate the OAuth flow without user intervention through a web browser or bypass Bigin's OAuth prompt and generate tokens from the backend, use the Self Client option available in the API console. This involves obtaining an authorization grant code, which can then be exchanged for an access token and a refresh token via a POST request to the endpoint /oauth/v2/token.

Upon obtaining the access token and refresh token, use the access token to authenticate API requests. When the access token expires (typically after one hour), use the refresh token to generate a new access token without requiring any web session or user intervention. It's important to securely store the refresh token on your backend, as it remains valid until manually deleted.

For more detailed information, refer to the Authorization process for self client guide.

How can I allow others to generate tokens for their accounts using my client ID? #

To allow other users to generate tokens for their accounts using your client ID, you can use the web-based application type provided in the API console. This process involves obtaining an authorization grant code by making a GET request for user authorization (oauth/v2/auth) with a valid redirect URI.

Sample request for user authorization:

https://accounts.zoho.com/oauth/v2/auth?response_type=code&client_id=1000.690CGFL9IO0QAAXY7904YOBT4IHLGY&scope=ZohoBigin.modules.ALL&access_type=offline&redirect_uri=https://www.yourdomain.com/callback

Sample response of oauth/v2/auth:

https://www.yourdomain.com/callback?code=1000.aa75abd2cd57603af9cd152be0a4a724.681a79ac0ad10a7c66713be8dbbe8541&location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com&

The code obtained with the redirect URI can then be exchanged for an access token and a refresh token through a POST request to the endpoint /oauth/v2/token.

For more detailed information, refer to the Authorization process for web-based applications guide.

Why am I receiving a '301 moved permanently' response? #

We implement redirection from http URLs to https to ensure secure serving of requests. This is why you see the '301 moved permanently' message. We recommend using https:// instead of http:// for improved security.

Why is the response returning as access_denied when I make a GET request for user authorization (oauth/v2/auth)? #

The access_denied response occurs when you make a GET request to authenticate users (/oauth/v2/auth) because there's a limit of five requests per minute using the same client ID. It's important to note that you don't need to make multiple requests to /oauth/v2/auth because the generated code stays valid for two minutes. You can use this code to get a permanent refresh token and an access token, which is valid for one hour, through /oauth/v2/token.

Why is the response returning as access_denied when I make a POST request to generate tokens (oauth/v2/token)? #

The access_denied response occurs when you make a POST request to generate tokens (/oauth/v2/token) because there is a limit of five requests per minute using the same client ID and refresh token. If you exceed this limit, we will throw an access_denied exception for 10 minutes, starting from the time of the last call. We recommend securely storing the refresh token on your end so that you can use it to generate a new access token when the current one expires (typically after one hour).

Why am I getting an error while processing the token generation request (oauth/v2/token)? #

image-error-while-processing-oauth-token

The endpoint for generating tokens (oauth/v2/token) is a POST request, which cannot be made using a web browser.

GET requests are most commonly used in web browsers. However, GET requests are not suitable for generating tokens, because they contain sensitive information such as client_secret and refresh_token. On the other hand, POST requests save data in the request body of the HTTP request and do not save it in the browser history or cache.

You can use POST requests through tools like Postman or other rest clients, or directly from within your application code. Here is an example request for generating tokens (oauth/v2/token) using Postman:

image-oauth-token-generation-postman

Why is the response returning as invalid_code when I make a POST request to generate tokens (oauth/v2/token) with the grant_type set as authorization_code? #

The code obtained from the callback URL after a successful user authorization through a GET request to authenticate users (oauth/v2/auth) has a validity of two minutes and can only be used once. If an already used or expired code is used to generate tokens (oauth/v2/token), it will result in an invalid_code error.

Why is the response returning as invalid_code when I make a POST request to generate tokens (oauth/v2/token) with the grant_type set as refresh_token? #

The refresh token obtained through a POST request to generate tokens (oauth/v2/token) has been deleted. Using a deleted refresh token to generate tokens (oauth/v2/token) will result in an invalid_code error.

What are the possible reasons for the deletion of a refresh token? #

The deletion of a refresh token may occur due to any of the following reasons:

We maintain an active limit of 20 refresh tokens per user-generated client ID. If the user creates more than 20 refresh tokens, the oldest refresh token will be deleted to maintain the active limit.
When you use the /token/revoke endpoint to explicitly revoke the refresh token.
When you change your account password or choose to delete device sessions.
When you revoke the access granted for the client from the Connected Apps section in your account.
When you delete the OAuth client that is registered in the API console, all refresh tokens linked to that client will be deleted as well.

Why is the response returning as invalid_client when I make a POST request to generate tokens (oauth/v2/token)? #

The invalid_client error is returned if you include a new line character or extra space between the parameters.

Sample failed request:

https://accounts.zoho.com/oauth/v2/token?client_id=1000.70FT7TMXXMGU93289P1QKUXQYLOD3H&client_secret=8baddfde46a07747e26939fba63d91206f391bd391&redirect_uri=http://inocrea.be/callback&grant_type=authorization_code&code=1000.186a618465cbab1e6cf0bbdacabf56e5.5da7a8d7586961d5fb5149a3e4c1c5c4

Why is the response returning as invalid_client_secret when I make a POST request to generate tokens (oauth/v2/token)? #

When you register your application in the API console, you might have enabled Multi-DC setup to access user information from various regions. Each Data Center (DC) typically has its own client secret associated with the client ID. Therefore, if you're making a POST request to generate tokens (oauth/v2/token) with a client_secret that belongs to a different Data Center, it will result in an invalid_client_secret response.

Why is the refresh token missing in a token generation response? #

If the access_type is set as online in the GET request for user authorization (oauth/v2/auth), the token generation response will not include the refresh token.

Steps to obtain a refresh token for the first time:

In order to obtain the refresh token along with the access token in the token generation response, you need to set the access_type as offline in the GET request for user authorization (oauth/v2/auth).

Sample request

Steps to obtain another refresh token:

To obtain another refresh token, you need to set the access_type as offline and the prompt as consent in the GET request for user authorization (oauth/v2/auth). By specifying the prompt as consent, the user will be prompted to grant access every time the app requests their details.

Sample request

How can I obtain information about the user associated with the token? #

We don't provide any user information in the response of /oauth/v2/token. To get user details, you need to send a GET request to the API endpoint – https://profile.zoho.com/api/v1/user/self/profile. Include the header named Authorization with the header value Zoho-oauthtoken <access token value you received>. It's important to note that when generating tokens, you should include the scope zohoprofile.userinfo.read in the scope parameter for /oauth/v2/auth.

Sample request:

curl "https://profile.zoho.com/api/v1/user/self/profile" \
-X GET \
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response:

image-oauth-token-info-postman

Why does INVALID_OAUTHTOKEN occur when I try to access Bigin APIs? #

The INVALID_OAUTHTOKEN may occur due to any of the following reasons:

If the request for token generation (oauth/v2/token) is made through accounts.zoho.com and the token is used to access resources at www.zohoapis.eu, the response will be INVALID_OAUTHTOKEN. Ensure that the token generated for API access is in the same data center (DC) for which it was generated.
When an access token used to access Bigin resources expires after its one-hour validity period. We maintain an active limit of 15 access tokens per refresh token. If the user creates more than 15 access tokens, the oldest access token will be deleted to maintain the active limit.
If the refresh token you generated is revoked due to a password change or deletion of connected apps from your accounts, the response will be INVALID_OAUTHTOKEN.
If you've used authorization code to make API calls for accessing Bigin resources instead of access_token, the response will be INVALID_OAUTHTOKEN.

Why does OAUTH_SCOPE_MISMATCH occur? #

The OAUTH_SCOPE_MISMATCH may occur when the scope needed to access the Bigin API endpoint differs from the scope used to generate the access token.

Why do I receive the message "Javascript is disabled in your browser. Please enable the javascript to continue"? #

JavaScript support is necessary for your browser to access client-based applications. If you've disabled JavaScript in your browser due to privacy reasons, we recommend that you enable it to avoid this message.

Steps to enable JavaScript in the following browsers:

Chrome

Open the Chrome browser.
Go to Settings > Privacy and security.
Click Site settings, and scroll down to Content.
Click JavaScript and enable it.

Mozilla

Open the Mozilla Firefox browser.
In the address bar, type about:config and press Enter.
Click Accept the Risk and Continue.
Search for javascript.enable and ensure it is true.

Edge

Open the Microsoft Edge browser.
Go to Settings > Cookies and site permissions, scroll down to All permissions.
Click JavaScript and enable it.

What steps need to be taken to access Bigin APIs using JavaScript-based clients? #

If you're using a JavaScript-based client for accessing Bigin APIs, to generate tokens and use the APIs, you'll need to follow these steps:

To obtain a client ID and client secret for your JavaScript app, register it as a Client-based application type in the Zoho API Console.
To obtain an access token for accessing API endpoints, you must construct an access token request link and provide a way for the users to access the request link.
The access token request link is as follows:
https://accounts.zoho.com/oauth/v2/auth?response_type=token&client_id={client-id}&redirect_uri={authorized_redirect_uri}&prompt=consent&scope={required_scopes_seperated_by_comma}
A sample access token request with required and recommended query parameters looks like the following:
https://accounts.zoho.com/oauth/v2/auth?response_type=token&client_id=1000.TM6DZZCD25LQ52CTMPJ5Z25UR12JOL&redirect_uri=https://www.yourdomain.com/callback&prompt=consent&scope=ZohoBigin.settings.modules.READ,ZohoBigin.settings.modules.WRITE,ZohoBigin.settings.DELETE
When the access token request link opens in a web browser, the user must sign in to verify their Bigin account (if they aren't already) and then approve the request. The authorization server sends the browser back to the redirect URI with the access token. A sample redirect URI response looks like this:
https://www.yourdomain.com/callback#access_token=1000.461b7c8a3bf30d224ee93a161fa1917c.d81e0e553af469dd336ef10cd1623dc2&expires_in=3600&location=us&api_domain=https%3A%2F%2Fwww.zohoapis.com&scope=ZohoBigin.settings.modules.READ%20ZohoBigin.settings.modules.WRITE%20ZohoBigin.settings.DELETE&granted_for_session=true
Note: When a user grants permission for the entire session while approving the above request, you'll receive the value of granted_for_session as true along with the access token. This will allow you to further generate or refresh tokens without requiring the user interaction until the user logs out.
Make the Ajax request to the Bigin API endpoint by including the previously obtained access token as a header for authorization.
A sample Ajax request to the Modules API for obtaining a list of modules in an organization:
var settings = {
"url": "https://www.zohoapis.com/bigin/v2/settings/modules",
"method": "GET",
"timeout": 0,
"headers": {
"Authorization": "Bearer 1000.461b7c8a3bf30d224ee93a161fa1917c.d81e0e553af469dd336ef10cd1623dc2"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});

To refresh the access token when it expires without requiring the user interaction:

Make a get request to /oauth/v2/auth/refresh with the same parameters as the access token request (/oauth/v2/auth). The refresh token request is as follows:
https://accounts.zoho.com/oauth/v2/auth/refresh?response_type=token&client_id={client-id}&redirect_uri={authorized_redirect_uri}&prompt=consent&scope={required_scopes_seperated_by_comma}
A sample refresh token request with required and recommended query parameters looks like the following:
https://www.yourdomain.com/callback#access_token=1000.33aed7d2fb2cbaf3dd675b307ad4544c.7f83e43cd0a74cec909c7c028910dd0c&expires_in=3600&location=us&api_domain=https%3A%2F%2Fwww.zohoapis.com&scope=ZohoBigin.settings.modules.READ%20ZohoBigin.settings.modules.WRITE%20ZohoBigin.settings.DELETE
A sample refresh token response looks like this:
https://www.yourdomain.com/callback#access_token=1000.33aed7d2fb2cbaf3dd675b307ad4544c.7f83e43cd0a74cec909c7c028910dd0c&expires_in=3600&location=us&api_domain=https%3A%2F%2Fwww.zohoapis.com&scope=ZohoBigin.settings.modules.READ%20ZohoBigin.settings.modules.WRITE%20ZohoBigin.settings.DELETE
The refresh token request is only valid until the user logs out. An error will occur with the parameter client_not_granted when the user has not granted permission for the entire session or has logged out of the session.