The Zoho Connector needs a refresh token before it can securely work with your Zoho CRM account. This is the most technical part of the setup, but you only need to complete it once for a client and environment.
Why this matters
Zoho gives the connector two kinds of access information:
- A short-lived access token, used for individual CRM requests.
- A longer-lived refresh token, used by the connector to request new access tokens when needed.
The connector stores and uses the refresh token. Do not enter the temporary grant token, the short-lived access token, or the entire response into the connector’s Refresh Token field.
Who should complete this
This guide is for the business owner, Zoho CRM administrator, or trusted website administrator who is allowed to create an integration and handle private credentials.
You will need:
- Access to the Zoho CRM organization that should be connected.
- Permission to create a Self Client in the Zoho API Console.
- Permission to manage the Zoho Connector settings.
- Windows PowerShell, or another tool that can send a secure web request.
If you do not have these permissions, ask the person who manages your Zoho account to complete the steps with you. Never ask someone to send you their client secret or token in plain text.
Before you start
For the first successful test, use the same data center as your Zoho organization and choose the Production environment. The current connector fills in supported Production URLs automatically after you choose the region.
Use these scopes for the standard connector setup:
ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoCRM.users.READ
The scopes determine what the connector can do. The connector needs CRM module access, CRM settings access for Website Membership setup, and user-read access for its connection test.
Step 1: Create a Zoho Self Client
A Self Client is appropriate when a standalone server-side integration needs to work with one Zoho organization and does not use a public sign-in page of its own.
- Open the Zoho API Console.
- Sign in with the Zoho CRM account that should authorize the connection.
- Choose Self Client.
- Select Create Now.
- Confirm by selecting OK.
- Open the Client Secret tab.
- Copy the Client ID and Client Secret to a safe temporary location.
You will enter those two values in the connector later. Keep them private.
For more detail, see Zoho’s Self Client authorization instructions.
Step 2: Generate the temporary grant token
The grant token gives Zoho permission to create the refresh token. It is temporary and single-use, so do not generate it until you are ready to exchange it immediately.
In the same Self Client, open Generate Code.
In Scope, enter exactly:
ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoCRM.users.READ
Choose the required time duration.
Enter a description, such as runsonUpendo Zoho Connector.
Select Create.
Choose the correct Zoho portal.
Choose the correct environment and organization.
Select Create again.
Copy the generated grant token immediately.
The grant token is not the value you will save in runsonUpendo. It is only the one-time value used in the next step.
Zoho’s documentation describes the Self Client flow and the organization-specific nature of the token. Read the official authorization guide.
Step 3: Exchange the grant token for a refresh token
You will now send the client ID, client secret, and temporary grant token to Zoho. Zoho will return a response containing the refresh token the connector needs.
Choose the correct Accounts URL
Use the Accounts URL for the same Zoho data center and environment used to create the grant token:
The current connector exposes these supported regions. Use the region selected in the connector, not a URL copied from a different Zoho data center.
Run the PowerShell request
Open PowerShell and replace the four placeholder values in this command with your own values. Do not include quotation marks inside the values themselves.
$body = @{ grant_type = "authorization_code"; client_id = "PASTE_CLIENT_ID_HERE"; client_secret = "PASTE_CLIENT_SECRET_HERE"; code = "PASTE_GRANT_TOKEN_HERE" }
Invoke-RestMethod -Method Post -Uri "https://accounts.zoho.com/oauth/v2/token" -Body $body -ContentType "application/x-www-form-urlencoded"
Replace the accounts.zoho.com portion with the Accounts URL for your region.
The response should contain fields similar to these:
{
"access_token": "short-lived value",
"refresh_token": "value needed by the connector",
"api_domain": "https://www.zohoapis.com",
"token_type": "Bearer",
"expires_in": 3600
}
Copy only the value beside refresh_token. Do not copy the label, quotation marks, commas, or the whole response.
For the full token-exchange rules, see Zoho’s Access and Refresh Tokens guide.
Save the refresh token in the connector
- Open the Zoho Connector settings.
- Select the same region used for the Zoho Self Client.
- Select Production for the first successful test.
- Select the same scopes used to generate the grant token.
- Paste the Client ID into Client ID.
- Paste the Client Secret into Client Secret.
- Paste only the value copied from refresh_token into Refresh Token.
- Leave Redirect URI blank for the Self Client flow unless you explicitly registered one in Zoho.
- Select Save connection.
- Select Test connection.
A successful test means Zoho accepted the credentials, the refresh token produced an access token, and the connector could read the current Zoho user.
Common problems
| Message or result |
What it usually means |
| invalid_client |
The client ID, secret, or Accounts URL does not match. |
| invalid_code |
The grant token expired or was already used. Generate a new one and exchange it immediately. |
| Invalid scope |
A scope is misspelled or separated incorrectly. |
| Authentication succeeds but testing fails |
The user-read scope may be missing, or the environment does not match. |
| No refresh token appears |
The grant was reused, expired, or generated through the wrong client flow. |
| Redirect URI error |
A URI was supplied that does not exactly match a URI registered for the client. |
Tokens are specific to the Zoho organization and environment that authorized them. A Production token cannot be used for a different Sandbox or Developer organization.
FAQs
Which token goes into the connector?
Only the value beside refresh_token in Zoho’s response goes into the connector’s Refresh Token field.
Can I use the access token instead?
No. An access token expires quickly. The connector uses the refresh token to obtain new access tokens when needed.
Can I reuse the grant token if PowerShell fails?
Usually not. The grant token is temporary and single-use. Generate a new grant token and exchange it promptly.
Why must the region match?
Zoho’s client, grant token, and refresh token are tied to the organization and data center that authorized them. A region mismatch can produce an invalid-client or authentication error.
Should I enter a Redirect URI?
Leave it blank for the Self Client flow unless you deliberately registered a redirect URI and Zoho requires it for your exchange.
Where do I save the final value?
Save only the refresh_token value in the Zoho Connector’s Refresh Token field, then select Save connection and Test connection.
What should I share with support if it fails?
Share the error message, selected region, environment, and approximate time of the attempt. Never share the client secret, grant token, access token, or refresh token.
Official references