Authentication is the foundation of any secure integration. The Zoho Books API v3 uses the OAuth 2.0 protocol to ensure that your financial data is accessed securely without ever sharing your password with third-party apps.
At Kalki LLP, we ensure your integrations are built on these robust security standards.
Before starting, understand these key terms:
Client ID: The unique identifier for your application.
Client Secret: A private key used to authenticate your application with Zoho.
Redirect URI: The URL where Zoho sends the "Authorization Code" after the user grants permission.
Grant Type: The method used to acquire an access token (usually authorization_code or refresh_token).
Depending on your data center, use the following base URLs for authentication:
| Region | Accounts URL (Authorization & Tokens) |
| US (.com) | https://accounts.zoho.com/oauth/v2/ |
| India (.in) | https://accounts.zoho.in/oauth/v2/ |
| Europe (.eu) | https://accounts.zoho.eu/oauth/v2/ |
| Australia (.com.au) | https://accounts.zoho.com.au/oauth/v2/ |
Key Paths:
Authorize: /auth
Token Generation: /token
Token Revocation: /token/revoke
Scopes define what your application can and cannot do. For a successful integration, you must request the correct scope:
| Scope | Permission Level | Use Case |
ZohoBooks.fullaccess.all | Full Access | Recommended for most internal Kalki LLP automations. |
ZohoBooks.contacts.READ | Read Only | Syncing customers to a CRM. |
ZohoBooks.invoices.CREATE | Create Only | Generating invoices from an e-commerce site. |
ZohoBooks.settings.READ | Read Only | Fetching tax rates or organization details. |
For developers working within Zoho Creator or CRM, we recommend using Zoho Connections to handle the OAuth handshake automatically.
Go to Settings > Connections in your Zoho app.
Select Zoho OAuth and pick Zoho Books.
Select the required scopes (e.g., ZohoBooks.fullaccess.all).
Name your connection (e.g., kalki_books_connection).
Once the connection is active, you no longer need to manage manual token refreshes. Use the connection parameter:
// Fetching invoice details via Kalki Connection
response = invokeurl
[
url :"https://www.zohoapis.in/books/v3/invoices?organization_id=XXXXX"
type :GET
connection :"kalki_books_connection"
];
info response.get("code"); // Should return 0 for success
If your API call fails during the authentication phase, look for these specific messages in your logs:
invalid_client: Your Client ID or Client Secret is incorrect. Ensure you aren't using a US ID on an Indian (.in) data center.
invalid_code: The authorization code has expired (they are usually valid for only 1 minute).
access_denied: The user clicked "Reject" on the consent screen.
invalid_scope: You requested a scope that doesn't exist or isn't enabled for your account.
code: 57 (Not Authorized): This usually happens when the API domain doesn't match the OAuth data center (e.g., trying to call .com with a .eu token).
Access Token: Valid for 1 hour.
Refresh Token: Permanent (until revoked).
Limit: Zoho allows a maximum of 20 refresh tokens per user per application. If you exceed this, the oldest token is automatically revoked.
Managing OAuth lifecycles, refresh token rotations, and multi-region data centers can be complex. Kalki LLP specializes in building high-security Zoho Books integrations that never "expire."