Hello everyone!
Welcome back to yet another post in Kaizen! Earlier in this series, we discussed OAuth2.0 and Self Client. In continuation of that, we will now discuss the various errors that you may face while using OAuth2.0 and how you can handle them.
For better understanding, we have grouped the errors based on the OAuth2.0 flow itself.
You may face errors while
- Registering a client
Generating the authorization code (grant token)
a. For web-based applications
b. For self client applications
- Generating access and refresh tokens from the grant token
1. Registering a Client
You can register a client in Zoho Developer Console either as a web application or a self client as displayed in the below image. The below table explains the errors you may face while registering your client, and how you can handle them.
Error
| Reason
| Resolution
|
Enter a valid client name
| The client name has a special character.
| The client name must not contain any special characters except "_" and "&".
|
Enter a valid JavaScript Domain URI
| The JavaScript domain is incorrect.
| Specify valid JavaScript domains, separated by commas, and they must start with 'http'.
|
Enter a valid redirect URI
| The redirect URI is incorrect.
| |
Enter a valid homepage URL
| The homepage URL is invalid.
| |
The following images will give you an idea of these errors.
On a side note, the following are the mandatory entries for different client types. You will see an error when you do not specify any of these mandatory entries.
Client Type
| Client Name
| Homepage URL
| Redirect URIs
| JS Domains
|
Java Script
| Y
| Y
| Y
| Y
|
Web-based
| Y
| Y
| Y
| NA
|
Mobile
| Y
| Y
| Y
| NA
|
Self Client
| N
| N
| N
| NA
|
| Y
| Y
| N
| NA
|
2. Generating the Authorization Code (Grant token)
As you already know, there are two ways in which you can generate the grant token based on the client type.
a. Web-based redirection
In this authorization flow,
As you can see, the request URL has the parameters "scope", "response_type", and "redirect_uri".
The user sees the authorization prompt and approves the app's request as shown in the below image.
The user is redirected back to the application with an authorization code in the query string.
- The application exchanges the authorization code for an access token.
The user may face one of the below errors when the application makes an authorization request with one or many incorrect parameters mentioned in step 1.
Error
| Reason
| Resolution
|
ERROR_invalid_response_type
| a) The value of the "response_type" key is not "code". b) You have not passed the mandatory keys in the request. | a) The value of the "response_type" key must be "code".
b) Pass all the mandatory keys in the request to generate the grant token.
|
ERROR_invalid_client
| The client ID is wrong or empty.
| Pass the right client ID. You can check your client ID from the developer console.
|
ERROR_invalid_redirect_uri
| The redirect URI value passed, and the one registered in the developer console mismatches.
| Pass the right redirect URI.
|
ERROR_invalid_scope
| The scope is invalid.
| Pass valid scopes. You can refer to the list of scopes here. |
As you can see, the scope ZohoCRM.user.ALL is incorrect and hence, the system throws the error.
The application must again make the authorization request with proper scopes.
b. Self Clients
After registering your application as a self client, you must provide the necessary scopes in the UI under the Generate Code tab.
The system throws an error when you enter one or more incorrect scopes.
Enter valid scopes and click Generate to generate the code as shown below.
3. Generating Access and Refresh Tokens from the Grant Token
To generate the access and refresh tokens,
- Make a POST API call with the URL "{{accounts-domain}}/oauth/v2/token".
In the request body, pass the values of the following parameters.
a. client_id
b. client_secret
c. redirect_uri
d. code(this is the generated grant token)
e. grant_type
You may face errors when one or more of the above parameters have a wrong value as shown in the below image.
Error
| Reason
| Resolution
|
invalid_client
| a) You have passed an invalid Client ID or secret.
b) Domain mismatch. You have registered the client and generated the grant token in a certain domain (US), but generating the tokens from a different domain (EU).
c) You have passed the wrong client secret when multi-DC is enabled.
| a) Specify the correct client ID and secret.
b) Ensure that you generate the grant, access, and refresh tokens from the same domain using the same domain URL
(or)
Enable Multi-DC for your client to generate tokens from any domain.
c) Each DC holds a unique client secret. Ensure to pass the right client secret for that DC.
|
invalid_code
| a) The grant token has expired.
b) You have already used the grant token.
c) The refresh token to generate a new access token is wrong or revoked.
| a) The grant token is valid only for one minute in the redirection-based flow. Generate the access and refresh tokens before the grant token expires.
b) You can use the grant token only once.
c) Specify the correct refresh token value while refreshing an access token.
|
invalid_redirect_uri
| The redirect URI in the request mismatches the one registered in the developer console.
| Specify the correct redirect URI in the request.
|
Points to note
- For redirection-based authorization, the grant token is valid only for a minute.
- For self client apps, the grant token is valid for the time you selected while authorizing your application.
- If the generation of access and refresh tokens from the grant token fails, the grant token becomes invalidated. You must generate another grant token.
- You can generate a grant token only up to five times in a minute.
- The access token is valid only for an hour. You must use the refresh token to generate new access tokens.
- The refresh token does not expire. It is invalidated only when you revoke the refresh token.
- Each user in an organization can have a maximum of 20 refresh tokens. Also, each refresh token can have a maximum of 30 active access tokens.
- When a user creates the 31st access token, the system deletes the first created access token. Similarly, when the user creates the 21st refresh token, the system deletes the first created refresh token.
We hope you found this post useful. Keep a tab on this series for more exciting topics!
Reach out to us at support@zohocrm.com if you have any questions, or let us know in the comment section.
Cheers!