Zoho CRM Integration via API

Purpose

This guide explains how to create a Zoho Self Client in the Zoho API Console and use it to generate the OAuth 2.0 refresh token Logsign USO needs to pull Zoho CRM audit log records for security analytics and forensic purposes.

Zoho CRM does not expose audit records through a live "list" endpoint. Instead, Logsign schedules an asynchronous export job, polls its status, and downloads the resulting CSV once it finishes. This is the only way to retrieve CRM audit data via API; there is no syslog or agent-based alternative for this data.

Prerequisites

The Zoho user who grants consent must be a CRM Administrator (or hold the CEO role). A lower-privileged user's consent will only expose audit records for that user and their subordinates, not the full organization.

You need access to the Zoho API Console (api-console.zoho.<dc>) for your Zoho data center to create the Self Client used in Step 2.

Step 1: Identify Your Zoho Data Center

Zoho operates separate, non-interoperable data centers per region. Confirm which one your organization is provisioned on by checking the domain you use to sign in to Zoho CRM, then map it below. Logsign asks for this as the Region field, and it determines every host used for authentication and API calls.

The ca region uses the zohocloud.ca domain, not zoho.ca; this is a common copy-paste mistake. Your accounts host, CRM API host, and refresh token must always belong to the same region; mixing them returns an authentication error.

Step 2: Create a Self Client in the Zoho API Console

1. Sign in to https://api-console.zoho.<dc> (use your region's domain from Step 1) with the Administrator account.
2. Click Add Client and choose Self Client.
3. Once created, open the client and copy the Client ID and Client Secret shown on the Client Secret tab. These are entered directly into the Logsign form.

Step 3: Generate a Grant Code and Exchange It for a Refresh Token

1. In the Self Client, open the Generate Code tab.
2. In the Scope field, paste the following (comma-separated, no spaces); the third scope is easy to miss but is required to download the finished export file, not just to schedule it: 
   ZohoCRM.settings.audit_logs.CREATE,ZohoCRM.settings.audit_logs.READ,ZohoCRM.users.READ,ZohoFiles.files.READ
3. Set Time Duration to the maximum, 10 minutes, and click Create.

4. Copy the generated grant code immediately and exchange it for a refresh token before it expires, using the accounts host for your region from Step 1:

   curl --location "https://accounts.zoho.<dc>/oauth/v2/token" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "grant_type=authorization_code" \
     --data-urlencode "code={GrantCode}" \
     --data-urlencode "client_id={ClientID}" \
     --data-urlencode "client_secret={ClientSecret}"

5. The response contains a refresh_token field. Copy it; Zoho shows it only once, at this exchange, and it does not expire on its own.

If the grant code has already expired (they last only 1-2 minutes) or was already used, the token endpoint still replies with HTTP 200 and a body of {"error":"invalid_code"} instead of an error status. Generate a fresh code from the Self Client and try again immediately.

Step 4: Configure the Integration in Logsign USO

Add a new Zoho CRM data source in Logsign USO and provide:

Logsign exchanges the refresh token for a short-lived access token automatically (valid ~3600 seconds) and re-exchanges it as needed; no manual renewal is required. On each cycle Logsign schedules a CRM audit export job for the time window since the last successful run, polls its status, and downloads and parses the resulting CSV once it reports finished.

Notes and Limits

• Only one CRM export job can run at a time per Zoho organization. If Logsign's job request collides with another in-flight export, Zoho returns ALREADY_SCHEDULED; Logsign detects this and adopts the existing job instead of failing.
• An export request window cannot exceed 180 days. This only matters if the integration is disabled for a long stretch and then re-enabled; Logsign automatically caps the request window rather than failing outright.
• A refresh token can be exchanged for at most 10 access tokens per 10 minutes, and a Zoho client/user pair may hold at most 20 live refresh tokens; a 21st consent silently revokes the oldest one. If you re-run the Self Client consent flow repeatedly while testing, make sure the last refresh token you generate is the one entered into Logsign.
• The download step (ZohoFiles.files.READ) is easy to omit from the scope list since it is not obviously related to CRM; if omitted, job scheduling and status checks succeed but the file download fails with an authorization error. Re-run the consent flow with the full scope list from Step 3.
• CSV column headers for the audit export are not officially documented by Zoho; Logsign normalizes incoming headers to lowercase/snake_case before mapping them, so minor header wording differences across Zoho CRM editions are tolerated.
• Zoho CRM audit history itself is retained for about 3 years and a single export job is capped at 1,000,000 rows; this is a platform limit, not a Logsign one.