Zendesk - Serval Documentation

About Zendesk

Zendesk is a customer-service platform for support ticketing and self-service knowledge. Serval connects to a single Zendesk instance and, through one connection, covers both Zendesk Support (tickets, comments, users, organizations, custom statuses) and Zendesk Guide (Help Center categories, sections, and articles). Zendesk is registered in Serval as both a ticket source and a knowledge source. Authentication: OAuth 2.0 client credentials - you create a confidential OAuth client in Zendesk Admin Center and give Serval its Client ID and Client Secret. Serval requests tokens with the read write scopes; within those, everything Serval can do is bounded by the role of the Zendesk user who created the OAuth client.

Zendesk is retiring API tokens as an authentication method: new Zendesk accounts cannot create tokens after July 28, 2026, no one can create new tokens after October 27, 2026, and all API tokens stop working on April 30, 2027. New Serval connections therefore use OAuth. If you connected Zendesk with an email + API token, switch the connection to OAuth before April 30, 2027 - see Migrating an API-token connection to OAuth.

Data sync: Workflow API calls run on demand. Ticket sync is a two-way background sync - Serval checks connected channels for new and updated tickets every 30 seconds and pushes Serval-side changes (new tickets, comments, status, priority, and field updates, including custom statuses) back to Zendesk. Zendesk Guide knowledge sync discovers all Help Center categories, sections, and articles, then ingests article content per item - newly discovered items start out excluded from sync, so you opt in exactly the content you want indexed. Group sync is off until an admin enables resource sync on the connection; once on, Serval refreshes Zendesk groups and their membership every two hours.

What the Zendesk integration enables

Capability	Description
Full Zendesk Support API access	A typed API action covering 424 Zendesk Support endpoints, generated from Zendesk’s official OpenAPI specification - tickets, users, organizations, ticket fields, custom statuses, automations, custom objects, brands, audit logs, and more. Rate-limited requests are retried automatically.
Two-way ticket sync	Use Zendesk as a Serval help desk channel. Serval pulls tickets and comments in the background (with an incremental sync for channels configured to capture historical and new tickets, and a bulk backfill if a channel falls more than 48 hours behind) and writes Serval-side ticket creates, updates, and comments back to Zendesk. Priorities map between systems (Zendesk urgent/high/normal/low ↔ Serval urgent/high/medium/low; Serval “none” is written to Zendesk as low). You can optionally scope a channel to a single agent group with Filter by Zendesk Group in the ticket source settings: only tickets assigned to that group are then synced, and a tracked ticket moved out of the group stops receiving updates. Leave it unset to sync all tickets.
Zendesk Guide knowledge sync	Syncs Help Center categories, sections, and articles into Serval’s knowledge base, preserving the category → section → article hierarchy. Each item has an include-in-sync setting, and newly discovered items start out excluded, so you scope exactly which Guide content Serval indexes.
Group sync	Turn on resource sync for the connection and Serval keeps your Zendesk groups, and their agent membership, current as Serval groups on a scheduled background sync. Those groups can then be used in access-profile conditions. Membership is managed in Zendesk - Serval reads it and never writes it back.
Guide permission sync	With permission sync enabled on the knowledge source, Serval mirrors each article’s user-segment visibility, and with enforcement turned on it only answers from articles the requester can view in your Help Center. Segment membership (user type, tags, organizations, groups) is checked against Zendesk at question time, so Zendesk itself evaluates the rules.
Shipped workflow: List Zendesk Tickets	A pre-installed workflow (runs without approval by default) that lists all tickets with cursor pagination and optional filters: an external ID, and a support-type scope of all, agent, or ai_agent (defaults to agent).
Help Center article link recognition	Paste a Zendesk Help Center article link in Serval and it resolves to the matching synced article automatically.

Anything defined in the Zendesk API can be accessed through Serval.

Get your credentials

You need an OAuth client created in your Zendesk instance. You must be a Zendesk administrator to create one. See Zendesk’s OAuth guide for full details.

Zendesk attributes every API action performed with a client-credentials token to the user who created the OAuth client - ticket comments, audit log entries, everything. Create the client while signed in as a dedicated service account (e.g. “Serval Integration”) rather than a personal admin account, so attribution stays stable when people leave and actions are clearly labeled in your audit trail. Serval’s access mirrors that user’s Zendesk role, so it should be an admin or an agent whose permissions cover reading and updating tickets and reading the Help Center.

Open the OAuth clients page

In Zendesk Admin Center, click Apps and integrations in the sidebar, then select APIs → OAuth clients (labeled “Zendesk API OAuth clients” in some accounts).

Create the client

Click Add OAuth client and give it a recognizable name, e.g. “Serval Integration”. Set Client kind to Confidential (not Public) - this is required. Leave Redirect URLs blank: client credentials is a server-to-server flow with no browser step, so no redirect URL is needed.

Save and copy the credentials

Click Save to generate the client. Copy the Unique Identifier (the Client ID) and the Secret immediately - Zendesk shows the full secret only once.

Client kind must be Confidential. Serval authenticates with the OAuth 2.0 client-credentials grant, and Zendesk permits that grant only for confidential clients. A Public client saves and its Client ID and Secret are accepted, but every token request is then rejected, so the connection fails its health checks with unauthorized_client (“The authenticated client is not authorized to use the access grant type provided”). If you see that, recreate the client as Confidential. This is the most common Zendesk setup mistake.

Zendesk displays the client secret only once, at creation time. Copy it before closing the window - Serval never displays it again either (it is shown obfuscated, with only the last 4 characters visible).

Connect in Serval

Open the Zendesk integration in Serval and fill in the connect form.

Instance Name (optional)

A friendly name for this Zendesk integration instance (e.g., “Production Zendesk”); if empty, we will use the domain. When set, the connection displays as “Name (domain)”.

Domain

Your Zendesk subdomain or domain - company and company.zendesk.com both work, and a pasted Zendesk URL is normalized automatically. Host-mapped or vanity domains will not authenticate; the connection always targets the canonical .zendesk.com address.

Client ID

The Unique Identifier of the OAuth client you created in Zendesk Admin Center. This is a password field.

Client Secret

The Secret of that OAuth client. This is a password field.

Submit

Save the connection. If saving fails, the error begins with “Failed to install integration” (first-time connect) or “Failed to update integration” (editing an existing connection), followed by details when available.

When you edit an existing connection, the form opens pre-filled with your saved settings; secrets appear masked with only the last 4 characters visible. Masked values are ignored when you save, so stored secrets are preserved unless you paste in a new one - and if you clear the Domain or Instance Name, the stored value is kept too.

Migrating an API-token connection to OAuth

Connections created before OAuth support use an email address + API token. Those keep working for now, but Zendesk disables all API tokens on April 30, 2027, so every token-based connection must be switched to OAuth before then. The migration is being rolled out to workspaces with existing Zendesk connections - if you don’t see the authentication-method selector yet, contact support@serval.com.

Create an OAuth client in Zendesk

Follow Get your credentials above - remember to create the client as a dedicated service account.

Switch the existing connection

Edit your existing Zendesk connection in Serval (don’t create a new one - your ticket sync, knowledge sync, and workflows all stay attached to the existing connection). Set Authentication method to OAuth 2.0, paste the Client ID and Client Secret, and save.

Verify

Re-run the health checks. All four should pass exactly as before.

Roll back if something breaks

Your API token stays stored (until Zendesk’s final cutoff): switching Authentication method back to API token (legacy) and saving reverts the connection without re-entering the token. Fix the OAuth client, then switch forward again.

After switching to OAuth, ticket comments and audit entries in Zendesk are attributed to the OAuth client’s creator instead of the email/token user - another reason to create the client from a dedicated service account.

Verifying the connection

Serval runs four health checks against your Zendesk connection. Test Zendesk Connection - confirms the domain and credentials work by fetching the connected user’s profile.

Success: “Successfully authenticated with Zendesk as [name]”
Failure: “Unable to authenticate with Zendesk. Please verify your credentials (OAuth client ID and secret, or email and API token) are correct.”

List Zendesk Tickets - confirms the account can list tickets (a small sample of ticket fields is recorded for diagnostics).

Success: “Successfully listed tickets from Zendesk (sample size: [number])”
Failure: “Unable to list tickets from Zendesk. Please verify your API credentials have permission to read tickets. This is required for the integration to function.”

List Zendesk Organizations - confirms the account can list organizations.

Success: “Successfully listed organizations from Zendesk (sample size: [number])”
Failure: “Unable to list organizations from Zendesk. Please verify your API credentials have permission to read organizations.”

List Zendesk Knowledge Articles - confirms the account can read Zendesk Guide knowledge base articles.

Success: “Successfully listed knowledge articles from Zendesk Guide (sample size: [number])”
Failure: “Unable to list knowledge articles from Zendesk Guide. Please verify your API credentials have permission to read the knowledge base, or that Zendesk Guide is enabled for your account.”

If the first three checks pass but List Zendesk Knowledge Articles fails, the most likely cause is that Zendesk Guide is not enabled for your account, or the connecting user cannot read the Help Center. Ticket features continue to work - only knowledge sync is affected.

Gotchas and troubleshooting

Health checks fail to authenticate (unauthorized_client) - the OAuth client is Public, not Confidential

If the connection saves but the health checks cannot authenticate, and the underlying error is unauthorized_client (“The authenticated client is not authorized to use the access grant type provided”), the OAuth client was created with Client kind: Public. Zendesk allows the client-credentials grant only for Confidential clients, so a public client’s Client ID and Secret are accepted but every token request is rejected. Recreate the client as Confidential in Zendesk Admin Center, then re-save the connection with the new Client ID and Secret. This is different from an invalid_client error, which means the Client ID, Secret, or Domain is wrong rather than the client kind.

API tokens are going away - migrate by April 30, 2027

Zendesk disables all API tokens on April 30, 2027 (and blocks creating new ones from October 27, 2026). Token-based Serval connections stop working at that point. Switch your existing connection to OAuth using the migration steps above - editing the existing connection keeps your ticket sync, knowledge sync, and workflows intact, while creating a new connection would not.

Actions are attributed to the OAuth client's creator

With client-credentials OAuth, Zendesk attributes every API action to the user who created the OAuth client. Create the client from a dedicated service account so ticket comments and audit entries are clearly labeled and survive personnel changes. Serval’s permissions mirror that account’s Zendesk role.

No inline form validation - mistakes surface as health-check failures

The connect-form fields have minimal format checks (only the Domain is validated), so the form can save with missing or malformed credentials. If something is wrong, the health checks will tell you - start with Test Zendesk Connection, which validates the domain and credentials together.

Domain must be a real .zendesk.com domain

Serval only sends credentials to *.zendesk.com addresses, and all traffic is routed to the subdomain derived from your configured Domain. Host-mapped or vanity Help Center domains will not authenticate - enter your canonical subdomain (company or company.zendesk.com).

Permissions mirror the connecting Zendesk user

Serval requests the read write OAuth scopes; within those, everything it can read or write is bounded by the Zendesk role of the OAuth client’s creator (or, for legacy connections, the agent or admin whose email and token you supplied). Writing tickets back to Zendesk (creates, updates, custom statuses, ticket fields) and syncing Guide knowledge each require the corresponding Zendesk permissions on that account.

Zendesk Guide must be enabled for knowledge features

Knowledge sync and the knowledge-articles health check both read the Help Center. If Guide is not enabled for your account (or the connecting user cannot read it), the ticket checks pass while the knowledge check fails - its failure message calls this out explicitly.

Knowledge items start excluded from sync

When Serval first discovers your Help Center content, every category, section, and article is created with sync turned off. Nothing is indexed until you explicitly include the items you want - so an empty knowledge base right after connecting is expected, not a failure.

Guide permission sync works best with an admin account

Permission enforcement checks a requester’s segment membership through Zendesk’s user-segments API. When the connecting account is a non-admin agent, Zendesk only reports the segments that agent shares with the requester, so restricted articles can be withheld from users who are actually entitled to them (never the reverse). Connect with an admin account for full-fidelity enforcement.

Zendesk’s account-level “Require sign in” Help Center setting is not exposed through the articles API, so articles without a user segment are treated as unrestricted in Serval even when your whole Help Center requires sign-in. Restrict sensitive articles with user segments if you need Serval to enforce their visibility.

Editing the connection keeps existing values

The edit form opens pre-filled, and clearing a field does not wipe anything: a cleared Domain keeps the existing domain, a cleared Instance Name keeps the existing display name, and masked secrets are ignored on save so stored credentials are preserved. To rotate a secret, paste the new value over the masked one and save. On a legacy connection, changing the Email Address alone also works - Serval recombines the new email with the stored API token.

Zendesk shows secrets only once

Copy the OAuth client secret (or, for legacy connections, the API token) when you create it in Zendesk Admin Center. Serval never displays it again either - reads show it obfuscated, with only the last 4 characters visible. If a secret is lost, generate a new one in Zendesk and paste it into the connection form in Serval.

Rate limits are handled automatically

When Zendesk rate-limits a request, Serval retries automatically - waiting the time Zendesk specifies, or backing off progressively when no wait time is given. Very high-volume workflows can still exhaust your instance’s limit; workflows that fetch large amounts of data should use cursor pagination to minimize the number of calls.

Help Center reads sit outside the typed action surface

The typed API action covers the 424 Zendesk Support endpoints from Zendesk’s official specification; Zendesk Guide (Help Center) endpoints are not part of that typed list. Guide content is still fully reachable - the built-in health check and the knowledge sync use it directly, and custom workflow calls to Guide work through the same authenticated connection, just without typed assistance.

Need help? Contact support@serval.com for assistance with your Zendesk integration.