#What the Zoho connector does

The Zoho connector is built on Olyron's shared connector SDK (src/lib/crm-connectors). It authenticates with Zoho's OAuth 2.0 endpoints, stores the resulting connection in the crm_connections table, and exposes read/write operations against Zoho's v2 REST API at https://www.zohoapis.com/crm/v2. Every request is authenticated with a Zoho-oauthtoken header.

On the integrations screen (/dashboard/settings/integrations), Zoho appears as an Available provider. HubSpot and Salesforce connector classes also ship in the codebase, and getSupportedProviders() in factory.ts now marks all three providers as implemented; this guide documents the Zoho connector.

#Before you connect

You need a Zoho API client (created in the Zoho Developer Console / API Console) and three environment variables set on the Olyron deployment. The connector reads these directly when exchanging and refreshing tokens.

ZOHO_CLIENT_IDstring

Client ID of your Zoho self-client or server-based app. Used to build the authorization URL and to exchange the code for tokens.

ZOHO_CLIENT_SECRETstring

Client secret for the same Zoho app. Used on the server during token exchange and refresh only.

ZOHO_REDIRECT_URIstring

The redirect URI registered in Zoho. Must match the callback Olyron uses (see the warning below), otherwise the token exchange fails.

CRM_ENCRYPTION_KEYstring

Symmetric key used by the SDK's token-encryption helpers in sdk.ts to encrypt OAuth tokens at rest with AES-256-GCM. Any string works — it is SHA-256 hashed into a 32-byte key. Required in production: the SDK throws if it is missing. In non-production it falls back to an insecure built-in dev key with a warning. Set a strong, stable value per environment.

When you register the Zoho app, request the scopes the connector uses: ZohoCRM.modules.ALL and ZohoCRM.settings.ALL. These are hard-coded into getAuthUrl() and grant access to the Leads, Deals, Tasks, and Notes modules.

#Connecting your Zoho account

1. 1
   Open Integrations

   Go to /dashboard/settings/integrations. Under Available Integrations, find the Zoho CRM card and choose Connect Zoho CRM.
2. 2
   Review scope and vendor options

   The connect screen (/dashboard/settings/integrations/zoho/connect) lists what will sync and lets you toggle Vendor enrollment sync and pick which vendor fields (plan name, status, effective date, termination date, premium) to include. Selecting Authorize Zoho CRM starts the flow.
3. 3
   Authorize in Zoho

   Olyron generates a CSRF state token of the form <tenantId>:<timestamp>, stashes your vendor-sync preferences in session storage, and redirects you to https://accounts.zoho.com/oauth/v2/auth with access_type=offline so a refresh token is issued. Sign in to Zoho and grant access.
4. 4
   Callback and token exchange

   Zoho redirects back to /api/crm-connectors/zoho/callback with a code and state. The route validates that both are present, reads the tenant ID from the state, and exchanges the code for tokens at https://accounts.zoho.com/oauth/v2/token.
5. 5
   Connection saved

   A row is written to crm_connections with status: active, storing the access token and refresh token (encrypted at rest with AES-256-GCM), the expiry, and instance_url (from Zoho's api_domain). You are redirected to the field-mapping step for the provider.

#How Olyron fields map to Zoho modules

The connector translates Olyron's internal lead/deal/task/note shapes to Zoho module fields. You can override the defaults with a fieldMappings record (Olyron field name to Zoho API name) passed into the connector; mapFields() in the SDK applies it, and anything under a record's custom_fields object is merged directly onto the Zoho payload.

Leads module

Deals, Tasks, and Notes

Vendor enrollment sync

syncVendorEnrollment(payload) records a vendor/carrier enrollment change in Zoho. When payload.member_external_id is set, it writes a Note on that member's Zoho Lead (via pushNote → POST /crm/v2/Notes with se_module: "Leads") titled Vendor enrollment: <vendor_name>. When the member has no linked Zoho lead id, it falls back to a standalone Zoho Task (POST /crm/v2/Tasks) with the same title, status: "Completed", medium priority, and Due_Date taken from the enrollment's effective date. The connector does not create or match a Zoho Lead on its own, so a Task (not a Note) is written whenever the member is not already linked to a Zoho lead.

The Note or Task body is a newline-separated summary assembled from whichever payload values are present: member name, plan, enrollment status, change type, effective date, termination date, and a free-text change description.

#API and endpoint reference

The only Olyron HTTP endpoint in the Zoho flow is the OAuth callback. Everything else happens server-side through the connector calling Zoho's API.

Token exchange (server-side)

POST https://accounts.zoho.com/oauth/v2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=$ZOHO_CLIENT_ID
&client_secret=$ZOHO_CLIENT_SECRET
&redirect_uri=$ZOHO_REDIRECT_URI
&code=<code from callback>

// Response fields consumed by Olyron:
// access_token, refresh_token, expires_in, api_domain

Example: push a lead to Zoho

POST https://www.zohoapis.com/crm/v2/Leads
Authorization: Zoho-oauthtoken <access_token>
Content-Type: application/json

{
  "data": [
    {
      "First_Name": "Dana",
      "Last_Name": "Ruiz",
      "Email": "dana@example.com",
      "Phone": "+1-555-0100",
      "Lead_Status": "Not Contacted",
      "Lead_Source": "Referral"
    }
  ]
}

// Olyron reads data[0].code === "SUCCESS" and returns
// data[0].details.id as the external_id

#How OAuth tokens are stored

Access and refresh tokens are encrypted at rest before they are written to crm_connections.access_token_enc and refresh_token_enc. The SDK's encryptToken() / decryptToken() helpers use AES-256-GCM (authenticated encryption) with a key derived from CRM_ENCRYPTION_KEY. BaseConnector decrypts on demand through its accessToken / refreshTokenValue getters, so plaintext tokens are never persisted.

• Ciphertext format is v1:gcm:<iv>:<tag>:<ciphertext>, with each component base64-encoded.
• CRM_ENCRYPTION_KEY is SHA-256 hashed into a 32-byte key, so any-length secret is accepted; keep it stable so existing tokens stay decryptable.
• In production the key is required — the SDK throws rather than store tokens unencrypted. Non-production falls back to an insecure built-in dev key and logs a warning.
• Legacy base64-only tokens written before this change are still readable and are transparently upgraded to AES-256-GCM the next time the token is persisted (isLegacyToken() detects them).

#Limits, honesty notes, and troubleshooting

• Vendor enrollment sync is implemented: syncVendorEnrollment() writes a Note on the member's Zoho Lead when member_external_id is known, and otherwise creates a standalone Zoho Task summarizing the enrollment. It does not create or match Zoho Leads itself, so unlinked members get a Task rather than a Note.
• The connector advertises webhooks and bidirectional capabilities, but there is no inbound Zoho webhook route in the app yet. Pulling data is on-demand via fetchLeads / fetchDeals, not push-from-Zoho.
• Token storage is real encryption (AES-256-GCM keyed off CRM_ENCRYPTION_KEY), not the old base64 placeholder. It is still a symmetric app-key scheme, so protect CRM_ENCRYPTION_KEY and database access, and set a strong key in production (the SDK refuses to store tokens without one).
• The post-connect redirect points at a per-provider field-mapping page; if that page is not present in your build, you will land on a route that does not yet render a mapping UI. Connections still save correctly.

Callback error codes

If the OAuth callback fails it redirects back to /dashboard/settings/integrations?error=<code>. Use the code to diagnose: