How to Authenticate API Requests to Bigin?
What Does This Guide Cover? (Quick Summary)
Every call to the Bigin by Zoho CRM API needs proof that your application has permission to read or change data. Bigin uses OAuth 2.0 for that proof. This guide explains how to register a client, request scopes, generate access and refresh tokens, and send authenticated requests. It also covers token limits, common errors, and security habits. Follow these steps to connect your app to Bigin safely and keep the connection stable.
| Item | Detail |
|---|---|
| Goal | Send authorized requests to the Bigin API |
| Protocol | OAuth 2.0 with the Authorization Code grant |
| Key credentials | Client ID, client secret, access token, refresh token |
| Access token lifetime | About one hour |
| Easiest start | The Self Client type in the Zoho API console |
How Does Bigin API Authentication Work?
The Bigin API uses the OAuth 2.0 protocol for authorization. Instead of a username and password, your application sends an access token with each request to read, create, update, or delete data. Bigin uses the Authorization Code grant type, so your application trades an authorization code for the access token.
This design protects your users. OAuth tokens have limited validity, and users can revoke an application’s access at any time. As a result, a leaked token causes less damage than a leaked password.
Which Terms Should You Know?
Zoho’s OAuth overview defines a few core terms. Learn them first, because they appear in every step.
| Term | Meaning |
|---|---|
| Client | The application that requests access on a user’s behalf |
| Client ID | The identifier you receive when you register the client |
| Client secret | A secret key that helps the server identify your client |
| Authorization code | A short-lived code that you exchange for tokens |
| Redirect URI | The callback address that receives the code |
| Access token | A temporary credential for protected resources |
| Refresh token | A token that generates new access tokens |
Which Data Can the API Reach?
Protected resources include the items in your Bigin account, such as Team Pipelines, Sub-pipelines, Contacts, Companies, and Notes. The scopes you request decide which of these your token can access.
Which Client Type Should You Choose?
Zoho offers several client types, and your choice shapes the whole flow. Pick the one that matches how your application runs.
When Should You Use a Self Client?
Use the Self Client type for stand-alone or server-side applications that do not need a user to approve access each time. Zoho gives the example of sending your application’s server data to Bigin or synchronizing records between your system and Bigin. The Self Client also suits first experiments with your own Bigin account.
When Should You Use a Web-Based Client?
Choose the web-based type when other people will connect their own Bigin accounts to your application. Your app sends users to an authorization screen, and each user grants or denies access. Zoho’s FAQ recommends this route when you want others to generate tokens with your client ID.
Why Does Bigin Not Support Client Credentials?
Bigin lets users work with multiple organizations, and a token must belong to a session where the user chooses the specific organization. For that reason, Bigin does not support client credentials. Zoho suggests the Self Client for server-to-server needs instead.
How Do You Register Your Application?
Registration comes first. You register in the Zoho API console, which issues your client ID and client secret.
What Does Registration Involve?
For a Self Client, you register the application and receive the client ID and secret. Zoho states that the domain and redirect URL are not required for this type. For a web-based client, you also add an authorized redirect URI that matches the one you use in requests.
Why Must the Redirect URI Match?
Bigin returns an invalid_redirect_uri error when the redirect URI in your authorization request differs from the authorized URI in the API console. Copy the value exactly, including the protocol and any trailing path.
How Do You Get Access and Refresh Tokens Step by Step?
The flow has a few clear stages. Follow them in order.
Step 1: How Do You Generate the Authorization Code?
For a self-client, you generate the code directly in the API console, and it stays usable only for a limited time. For a web-based client, your app sends the user to the authorization endpoint at /oauth/v2/auth. Zoho’s sample request includes the response type, client ID, a scope such as Zoho Bigin modules. ALL, an access type, and the redirect URI. After the user approves, Bigin sends the code to your redirect URI.
Step 2: Why Should You Set Access Type to Offline?
Bigin issues a refresh token only when you set the access type to offline in the authorization request. If you choose online, the token response omits the refresh token. Set offline from the start if your app needs long-term access.
Step 3: How Do You Exchange the Code for Tokens?
Send a POST request to the token endpoint, /oauth/v2/token, on the accounts server for your data center. Zoho lists several regional domains, including accounts.zoho.com for the US, accounts.zoho.eu for the EU, and accounts.zoho.in for India. Browsers cannot make this request, because it needs POST and carries secrets. Use a REST client, a tool such as Postman, or your application code.
Step 4: How Do You Handle the Response?
The response contains an access token and, when you requested offline access, a refresh token. Store the refresh token securely on your backend, because it stays valid until you delete it. The documentation notes that refresh tokens have no expiry time limit.
How Do You Send an Authenticated API Request?
Once you hold an access token, you add it to the Authorization header of each request. Zoho’s examples use this format:
Authorization: Zoho-oauthtoken <ACCESS_TOKEN>
What Does a Sample Request Look Like?
Zoho’s sample retrieves the list of modules in an organization. The request goes to the API domain for your data center, followed by the Bigin path and the modules endpoint. For US accounts, the API domain is www.zohoapis.com. Replace the placeholder with your own access token, and keep real tokens out of screenshots and public code.
Why Does the Data Center Matter?
Your token and your API domain must belong to the same data center. If you generate a token through accounts.zoho.com but call www.zohoapis.eu, Bigin returns INVALID_OAUTHTOKEN. Use the location value Bigin returns with the token to pick the right domains.
Which API Version Should You Call?
Zoho’s documentation shows both v1 and v2 paths in different examples. Check the current version in Bigin’s developer docs before you hard-code a path, and keep the version in one configuration value so you can update it easily.
How Do You Refresh an Expired Access Token?
Access tokens last about one hour. When one expires, you use the refresh token to generate a new one without involving the user.
What Does the Refresh Request Include?
Send a POST request to the token endpoint with the refresh token, your client ID, your client secret, and the grant type set to refresh_token. The response returns a fresh access token and its expiry in seconds. Build this step into your application so calls recover automatically.
How Often Should You Refresh?
Refresh only when needed, not before every request. Bigin limits how often you can call the token endpoint, so a refresh before each call quickly triggers errors. Cache the access token and reuse it until it nears expiry.
What Limits Apply to Tokens?
Bigin sets clear limits, and ignoring them causes confusing errors.
| Limit | Detail |
|---|---|
| Authorization requests | Five requests per minute for the same client ID |
| Token generation | Five requests per minute for the same client ID and refresh token |
| Lockout | An access_denied response for 10 minutes after exceeding the token limit |
| Active refresh tokens | 20 per user-generated client ID; the oldest token disappears beyond that |
| Active access tokens | 15 per refresh token; the oldest token disappears beyond that |
| Authorization code | Valid for two minutes and usable once |
What Do These Limits Mean for Your Design?
Generate tokens rarely and store them. Never create a new refresh token for every job. Share one refresh token across your workers, and refresh the access token centrally.
How Do You Fix Common Authentication Errors?
Bigin returns specific error codes. Match your symptom to the cause.
| Error | Likely Cause | Fix |
|---|---|---|
| invalid_code | The code expired, someone used it already, or the refresh token no longer exists | Generate a new code or refresh token |
| invalid_client | A new line or extra space sits between parameters | Remove stray characters from the request |
| invalid_client_secret | The secret belongs to a different data center | Use the secret for the right data center |
| invalid_redirect_uri | The redirect URI does not match the console | Copy the authorized URI exactly |
| access_denied | You exceeded the request limit | Wait, then reduce request frequency |
| INVALID_OAUTHTOKEN | Token expired, wrong data center, or revoked refresh token | Refresh the token and check the domain |
| OAUTH_SCOPE_MISMATCH | The token’s scope does not cover the endpoint | Generate a token with the right scope |
Why Does a Refresh Token Suddenly Stop Working?
Several events delete refresh tokens. Zoho lists these causes: generating more than 20 tokens, revoking through the revoke endpoint, changing your account password, deleting device sessions, removing the app from Connected Apps, and deleting the OAuth client. If tokens vanish unexpectedly, check for one of these events first.
What Are the Best Practices for Secure Authentication?
Tokens grant real access to customer data, so protect them like passwords.
How Do You Protect Your Credentials?
- Store secrets safely: Use a secrets manager or encrypted environment variables.
- Keep secrets out of code: Never commit the client secret to a repository.
- Request minimal scopes: Ask only for the modules your app needs.
- Use HTTPS only: Bigin redirects HTTP to HTTPS, and you should call HTTPS directly.
- Revoke compromised tokens: Use the revoke option if a token leaks.
How Do You Manage Tokens in Production?
Log token errors without logging the tokens themselves. Monitor failures and alert your team when refresh requests fail. Document who owns the Bigin integration user, because a password change by that person can break the connection.
Why Do Scopes Deserve Extra Care?
A narrow scope limits damage from mistakes. A reporting tool needs read access, not delete access. Bigin by Zoho CRM ties each token to its scopes, so you can separate tools by purpose and reduce risk.
How Can Solution for Guru Support Your Bigin API Project?
Authentication is only the first step of an integration. Solution for Guru is a CRM and software implementation consultancy that helps businesses plan, build, and secure integrations between Bigin and other systems. Its specialists can design your scope strategy, set up token storage, and test error handling before launch. Expert support shortens development time and reduces security risk.
What Are the Key Conclusions About Authenticating Bigin API Requests?
Bigin authentication follows a clear OAuth 2.0 pattern: register a client, request scopes, exchange a code for tokens, and send the access token with each call. Choose the Self Client for server-side work, request offline access to receive a refresh token, and refresh access tokens when they expire.
Bigin by Zoho CRM rewards careful token handling with a stable, secure connection. Respect the rate limits, match your data center and scopes, and store secrets safely. Confirm current endpoints, scope names, and API versions in Bigin’s developer documentation before you build, since Zoho updates them over time.
Frequently Asked Questions
An access token typically lasts one hour. When it expires, your application uses the refresh token to generate a new one without user involvement. Refresh tokens remain valid until someone deletes or revokes them.
Bigin includes a refresh token only when the authorization request sets the access type to offline. If you used online, request a new code with offline access. To obtain another refresh token later, Zoho says to add the consent prompt to the request.
No. Bigin does not support client credentials because users can work with multiple organizations, and each token must belong to a chosen organization. Use the Self Client option for server-side or automated integrations.
