Integrating Zendesk
Auth: OAuth 2.0 · Partner program: not required · Setup time: about 20 minutes · Last verified: 2026-05-23
Zendesk is the reference implementation for the customer-support vertical. The adapter targets the Zendesk Ticketing REST API and surfaces tickets, users, organizations, comments, macros, triggers, and views into the canonical customer-support schema.
Auth model
Section titled “Auth model”- OAuth 2.0 Authorization Code grant. Subdomain-scoped: authorize at
https://{subdomain}.zendesk.com/oauth/authorizations/new. Exchange via POST tohttps://{subdomain}.zendesk.com/oauth/tokens. - Tokens are bearer tokens with no fixed expiry — Zendesk will accept the same token until the OAuth client is revoked or the user’s account is deactivated. Re-prompt on
401.
Prerequisites
Section titled “Prerequisites”- A Zendesk Support account at
https://{subdomain}.zendesk.com. - Under Admin Center → Apps and integrations → APIs → Zendesk API → OAuth Clients, register a client. Note the Unique Identifier (client id) and Secret, and add the redirect URL.
Configure in admin
Section titled “Configure in admin”- Open
/platformsin the admin UI, filter to Customer Support, click Zendesk. - Fill Configure:
clientId— your OAuth client’s Unique Identifier.clientSecret— your OAuth client’s Secret.redirectUri—${PUBLIC_BASE_URL}/auth/customer-support/zendesk/callback.subdomain— the connecting tenant’s Zendesk subdomain (e.g.acmeforacme.zendesk.com).
- Enable the adapter.
Required scopes
Section titled “Required scopes”Zendesk supports both broad and resource-scoped scopes. For full canonical coverage request:
read,write— broad CRUD across the ticketing surface.- Optional
impersonate— required only if admins need to act as end-users on the connected tenant.
To least-privilege, swap read/write for resource-specific scopes such as tickets:read, tickets:write, users:read, users:write, organizations:read, webhooks:write.
Webhooks
Section titled “Webhooks”Configure under Admin Center → Apps and integrations → Webhooks. Choose Signed authentication and supply a shared secret — Zendesk signs deliveries with HMAC-SHA256 over ${timestamp}.${body} and sends:
X-Zendesk-Webhook-Signature— base64 HMAC.X-Zendesk-Webhook-Signature-Timestamp— Unix timestamp (seconds), required input to the HMAC.
The adapter verifies both. Subscribe to ticket events plus relevant trigger-fired notifications.
Quirks worth knowing
Section titled “Quirks worth knowing”- Subdomain in the URL. Zendesk’s OAuth endpoints are subdomain-scoped —
acme.zendesk.com/oauth/..., not a single global host. Store the subdomain with the credential. - Tokens never expire. No refresh-token dance; on a 401 you must re-prompt.
- Triggers + Webhooks are decoupled. A webhook is an outbound destination; a trigger is what fires it. The canonical “ticket.updated” stream is wired by creating a trigger that targets your webhook.
- Rate limits scale by plan. 700 requests/minute on Enterprise; lower on Suite Growth. The adapter honours
Retry-Afteron 429. - Sandboxes are per-tenant. Enterprise customers can spin sandboxes at
{subdomain}{sandbox-id}.zendesk.com; OAuth clients are scoped per-instance.
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.