Kaizen #4 - Troubleshooting OAuth2.0

Kaizen #4 - Troubleshooting OAuth2.0

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
  1. Registering a client
  2. Generating the authorization code (grant token)
    a. For web-based applications
    b. For self client applications
  3. 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.
Specify a valid redirect URI in the format "https://www.your-domain.com/callback".
Enter a valid homepage URL
The homepage URL is invalid.
Specify a valid homepage URL in the format "https://www.yourdomain.com".

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
Device
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,
  1. The web application redirects the user to the Zoho OAuth server with the required scope in the Accounts URL.
    "https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.users.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}".
  2. As you can see, the request URL has the parameters "scope", "response_type", and "redirect_uri".
  3. The user sees the authorization prompt and approves the app's request as shown in the below image.

  4. The user is redirected back to the application with an authorization code in the query string.

  5. 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,
  1. Make a POST API call with the URL "{{accounts-domain}}/oauth/v2/token".
  2. 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

  1. For redirection-based authorization, the grant token is valid only for a minute.
  2. For self client apps, the grant token is valid for the time you selected while authorizing your application.
  3. If the generation of access and refresh tokens from the grant token fails, the grant token becomes invalidated. You must generate another grant token.
  4. You can generate a grant token only up to five times in a minute.
  5. The access token is valid only for an hour. You must use the refresh token to generate new access tokens.
  6. The refresh token does not expire. It is invalidated only when you revoke the refresh token.
  7. 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.
  8. 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!


    • Sticky Posts

    • Kaizen #197: Frequently Asked Questions on GraphQL APIs

      🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

    • Kaizen #198: Using Client Script for Custom Validation in Blueprint

      Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

    • Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

      Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs

    • Kaizen #193: Creating different fields in Zoho CRM through API

      🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

    • Client Script | Update - Introducing Commands in Client Script!

      Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands

    • Recent Topics

    • Download an email template in html code

      Hello everyone, I have created an email template and I want to download it as html. How can i do that? I know you can do it via the campaigns-first create a campaign add the template and download it as html from there. But what if i don't want to create

    • Attachment is not included in e-mails sent through Wordpress

      I have a Wordpress site with Zeptomail Wordpress plugin installed and configured. E-mails are sent ok through Zeptomail but without the included attachment (.pdf file) Zeptomail is used to send tickets to customers through Zeptomail. E-Mails are generated

    • Upcoming Changes to the Timesheet Module

      The Timesheet module will undergo a significant change in the upcoming weeks. To start with, we will be renaming Timesheet module to Time Logs. This update will go live early next week. Significance of this change This change will facilitate our next

    • Best way to schedule bill payments to vendors

      I've integrated Forte so that I can convert POs to bills and make payments to my vendors all through Books. Is there a way to schedule the bill payments as some of my vendors are net 30, net 60 and even net 90 days. If I can't get this to work, I'll have

    • Cant update image field after uploading image to ZFS

      Hello i recently made an application in zoho creator for customer service where customers could upload their complaints every field has been mapped from creator into crm and works fine except for the image upload field i have tried every method to make

    • Billing Management: #4 Negate Risk Free with Advances

      In the last post, we explored how unbilled charges accumulate before being invoiced. But what happens when businesses need money before service begins? Picture this: A construction company takes on a $500,000 commercial building project expected to last

    • Is there an equivalent to the radius search in RECRUIT available in the CRM

      We have a need to find all Leads and/or Contacts within a given radius of a given location (most likely postcode) but also possibly an address. I was wondering whether anyone has found a way to achieve this in the CRM much as the radius search in RECRUIT

    • Zoho CRM Inventory Management

      What’s the difference between Zoho CRM’s inventory management features and Zoho Inventory? When is it better to use each one?

    • Cannot Enable Picklist Field Dependency in Products or Custom Modules – Real Estate Setup

      Hello Zoho Support, I am configuring Zoho CRM for real estate property management and need picklist field dependency: What I’ve tried: I started by customizing the Products module (Setup > Modules & Fields) to create “Property Type” (Housing, Land, Commercial)

    • Get Workflow Metadata via API

      Is there a way to get metadata on workflows and/or custom functions via API? I would like to automatically pull this information. I couldn't find it in the documentations, but I'm curious if there is an undocumented endpoint that could do this. Moderation

    • Zoho Projects - Q2 Updates | 2025

      Hello Users, With this year's second quarter behind us, Zoho Projects is marching towards expanding its usability with a user-centered, more collaborative, customizable, and automated attribute. But before we chart out plans for what’s next, it’s worth

    • FSM setup

      So we have been tinkering with FSM to see if it is going to be for us. Now is the time to bite the bullet and link it to our zoho books and zoho crm. The help guides are good but it would really help if they were a bit more in depth on the intergrations.

    • Upcoming Updates to the Employees Module in Zoho Payroll (US)

      We've made a couple of updates to the Employees module in Zoho Payroll (latest version of the US edition). These changes will go live today. While creating an employee Currently, the Compensation Details section is part of the Basic Details step, where

    • Possible to Turn Off Automatic Notifications for Approvals?

      Hello, This is another question regarding the approval process. First a bit of background: Each of our accounts is assigned a rank based on potential sales. In Zoho, the account rank field is a drop-down with the 5 rank levels and is located on the account

    • ZOHO Creator subform link

      Dear Community Support, I am looking for some guidance on how to add a clickable link within a Zoho Creator subform. The goal is for this link to redirect users to another Creator form where they can edit the data related to the specific row they clicked

    • Allow Resource to Accept or Reject an Appointment

      I have heard that this can be done, is there any documentation on how?

    • Create new Account with contact

      Hi I can create a new Account and, as part of that process, add a primary contact (First name, last name) and Email. But THIS contact does NOT appear in Contacts. How can I make sure the Contact added when creating an Account is also listed as a Contact?

    • Custom Fonts in Zoho CRM Template Builder

      Hi, I am currently creating a new template for our quotes using the Zoho CRM template builder. However, I noticed that there is no option to add custom fonts to the template builder. It would greatly enhance the flexibility and branding capabilities if

    • Python - code studio

      Hi, I see the code studio is "coming soon". We have some files that will require some more complex transformation, is this feature far off? It appears to have been released in Zoho Analytics already

    • Sync desktop folders instantly with WorkDrive TrueSync (Beta)

      Keeping your important files backed up and accessible has never been easier! With WorkDrive desktop app (TrueSync), you can now automatically sync specific desktop folders to WorkDrive Web, ensuring seamless, real-time updates across devices. Important:

    • How To Insert Data into Zoho CRM Organization

      Hi Team I have this organization - https://crm.zoho.com/crm/org83259xxxx/tab/Leads I want to insert data into this Leads module, what is the correct endpoint for doing so ? Also I have using ZohoCRM.modules.ALL scope and generated necessary tokens.

    • Where can I get Equation Editor por Zoho Writer?

      I need to use Math Formulas in my document. Thank you.

    • How can I get base64 string from filecontent in widget

      Hi, I have a react js widget which has the signature pad. Now, I am saving the signature in signature field in zoho creator form. If I open the edit report record in widget then I want to display the Signature back in signature field. I am using readFile

    • Creator roadmap for the rest of 2022

      Hi everyone, Hope you're all good! Thanks for continuing to make this community engaging and informative. Today we'd like to share with you our plans for the near future of Creator. We always strive to strike a good balance of features and enhancements

    • Filtering repport for portal users

      Salut, I have a weird problem that I just cannot figure out : When I enter information as administrator on behalf of a "supplier" portal user (in his "inventory" in a shared inventory system), I can see it, "customer" portal users can see it, but the

    • Zoho Inventory. Preventing Negative Stock in Sales Orders – Best Practices?

      Dear Zoho Inventory Community, We’re a small business using Zoho Inventory with a team of sales managers. Unfortunately, some employees occasionally overlook stock levels during order processing, leading to negative inventory issues. Is there a way to

    • Zoho One - Syncing Merchants and Vendors Between Zoho Expense and Zoho Books

      Hi, I'm exploring the features of Zoho One under the trial subscription and have encountered an issue with syncing Merchant information between Zoho Expense and Zoho Books. While utilizing Zoho Expense to capture receipts, I noticed that when I submit

    • Is Zoho Sheet available for Linux ?

      Is Zoho Sheet available for Linux ?

    • Zoho Sheet for Desktop

      Does Zoho plans to develop a Desktop version of Sheet that installs on the computer like was done with Writer?

    • BUTTONS SHOWN AS AN ICON ON A REPORT

      Hi Is there any way to create an action button but show it as an icon on a report please? As per the attached example? So if the user clicks the icon, it triggers an action?

    • Dropshipping Address - Does Not Show on Invoice Correctly

      When a dropshipping address is used for a customer, the correct ship-to address does not seem to show on the Invoice. It shows correctly on the Sales Order, Shipment Order, and Package, just not the Invoice. This is a problem, because the company being

    • RFQ MODEL

      A Request for quotation model is used for Purchase Inquiries to multiple vendors. The Item is Created and then selected to send it to various vendors , once the Prices are received , a comparative chart is made for the user. this will help Zoho books

    • Will zoho thrive be integrated with Zoho Books?

      title

    • Product Updates in Zoho Workplace applications | August 2025

      Hello Workplace Community, Let’s take a look at the new features and enhancements that went live across all Workplace applications this August. Zoho Mail Delegate Email Alias Now you can let other users send emails on your behalf—not just from your primary

    • Notebook audio recordings disappearing

      I have recently been experiencing issues where some of my attached audio recordings are disappearing. I am referring specifically to ones made within a Note card in Notebook on mobile, made by pressing the "+" button and choosing "Record audio" (or similar),

    • Unable to send message; Reason:554 5.1.8 Email Outgoing Blocked

      Hi, I sent few emails and got this: Unable to send message; Reason:554 5.1.8 Email Outgoing Blocked And now I have few days since I cant send any email. Is there something wrong I did? Also can someone fix this please

    • Want to use Zoho Books in Switzerland. CHF support planned?

      Hi, We're a Swiss company using other Zoho suite software and I discovered Zoho Books and other accounting SaaS when looking for an accounting tool. Do you intend to cover Switzerland and CHF based accounting anytime soon? Roy

    • Zoho sheet desktop version

      Hi Zoho team Where can I access desktop version of zoho sheets? It is important as web version is slow and requires one to be online all the time to do even basic work. If it is available, please guide me to the same.

    • Weekly Tips : Teamwork made easy with Multiple Assignees

      Let's say you are working on a big project where different parts of a single task need attention from several people at the same time—like reviewing a proposal that requires input from sales, legal, and finance teams. Instead of sending separate reminders

    • Best way to share/download presentation files in Zoho without losing formatting?

      Hello Zoho Community, I often work with PPT/PDF files in Zoho Docs and share them with colleagues. While PDFs usually give a direct download option, I’ve noticed that PPT/PPTX files sometimes only open in the viewer without a clear download link. Is there

    • Next Page