Integrating Zoho Desk
Auth: OAuth 2.0 · Partner program: not required · Setup time: about 25 minutes · Last verified: 2026-05-23
Zoho Desk is Zoho’s help-desk product, tightly coupled to the rest of the Zoho One suite. The adapter wraps the Zoho Desk REST API v1 and exposes tickets, contacts, accounts, agents, departments, and tasks into the canonical customer-support schema.
Auth model
Section titled “Auth model”- OAuth 2.0 Authorization Code grant via the Zoho Accounts service. Authorize at
https://accounts.zoho.{region}/oauth/v2/auth. Exchange via POST tohttps://accounts.zoho.{region}/oauth/v2/token. - Access tokens expire after
3600seconds. Refresh tokens are long-lived (unlimited until revoked); the adapter handles refresh transparently. {region}is the user’s data center TLD:com(US),eu,in,com.au,jp,com.cn,ca,sa. The token response includeslocation/accounts-server— pin the region for every subsequent request.
Prerequisites
Section titled “Prerequisites”- A Zoho Desk org at desk.zoho.com (or your regional URL).
- A registered client in the Zoho API Console (api-console.zoho.com) of type Server-based Application. Note the Client ID, Client Secret, and registered redirect URI.
Configure in admin
Section titled “Configure in admin”- Open
/platformsin the admin UI, filter to Customer Support, click Zoho Desk. - Fill Configure:
clientId— from the Zoho API Console.clientSecret— from the Zoho API Console.redirectUri—${PUBLIC_BASE_URL}/auth/customer-support/zoho-desk/callback.
- Enable the adapter.
Required scopes
Section titled “Required scopes”Zoho scopes are dotted strings of the form Desk.<module>.<operation>. Request at minimum:
Desk.tickets.ALL— full ticket CRUD.Desk.contacts.ALL— contacts.Desk.basic.READ— organizations, agents, departments.Desk.tasks.ALL— tasks attached to tickets.Desk.search.READ— search.Desk.events.ALL— event timeline.
Operations are one of READ, CREATE, UPDATE, DELETE, ALL.
Webhooks
Section titled “Webhooks”Zoho Desk does not sign webhook bodies and issues no webhook secret. Each delivery carries an X-ZDesk-JWT header: an RS256 JWT over its header and claims only, with iss = orgId:<id> and aud = webhookId:<id>, verified against Zoho’s published keys (Webhook document, “Verifying the authenticity of event information using JWT”).
- Create the webhook in Zoho Desk with an HTTPS callback URL of
<public base>/webhooks/customer-support/zoho-desk, and subscribe toTicket_Add,Ticket_Update,Contact_Add,Contact_Updateand any other events you need. - Store the webhook’s id on the connection:
PUT /admin/connections/<connection_id>/webhook-secretwith{ "secret": "<Zoho webhookId>" }. Until it is set, deliveries for that connection are rejected with 401.
Because the body is unsigned, events carry only the event type, resource type, action and resource id, with payload: { "bodyVerified": false }. Re-read the resource through the API rather than trusting the delivery. Details are in the adapter README (apps/integration-server/src/verticals/customer-support/adapters/zoho-desk/README.md).
Quirks worth knowing
Section titled “Quirks worth knowing”- Region is sticky and required. Every data center has its own accounts host and its own Desk API host (
desk.zoho.eu,desk.zoho.in, …). Mixing hosts results inINVALID_OAUTH_TOKENerrors. - 5 refresh tokens per minute, 20 active per user. Generation is rate-limited; cache refreshes per credential.
Desk.basic.READis not optional. Most ticket payloads embed agent + department references that are unreadable without it.- Self Client tokens are for testing only. Production deploys must use the standard authorization code flow.
References
Section titled “References”opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.