Zendesk connector: support history on demand, customer replies after approval

This page is for the Zendesk admin who will connect a Support instance to OrgRelay. It explains the five tools, the OAuth client login, what changes for accounts still on API tokens, and what an approver should check before a reply reaches a customer.

#What staff can ask

Zendesk questions come from support staff and from colleagues outside support who need ticket context. Some typical ones, especially when an order question also touches a store connected through the Shopify connector:

• "What's the full history on ticket 48213?" calls tickets.get. It returns the ticket fields and every comment, public and private, with author and time.
• "Show pending tickets that mention 'customs'." calls tickets.search with status: pending and keyword: customs. That becomes the Zendesk search query type:ticket status:pending customs.
• "Is [email protected] a known requester?" calls customers.search with the email.
• "Reply to 48213 that the replacement shipped today with tracking 1Z999." calls tickets.reply and waits for approval.
• "Mark 48213 as solved." calls tickets.update_status with status: solved, also after approval.

#Tools

Pagination depends on the path. Without filters, tickets.search lists /api/v2/tickets.json with cursor pagination (page[size], page[after]), and the cursor is Zendesk's after_cursor. With a keyword or status, it switches to /api/v2/search.json, which uses page numbers, so the cursor is simply the next page number. customers.search returns the first limit matches with no further pages, so refine the name or use the full email. limit defaults to 20 with a maximum of 100, following the limit plus cursor convention of the connector spec. Ticket fields map onto the shared standard tools shape, which the HubSpot connector also uses for its tickets.

The status enum for updates leaves out new and closed on purpose. Zendesk sets new itself, and closed is reached by its own automations after solved.

#Credentials and scopes

The connection form has one required field and two ways to sign in:

• Zendesk subdomain, required: yourcompany from yourcompany.zendesk.com. Pasting the full host also works, because OrgRelay strips .zendesk.com.
• OAuth client ID and OAuth client secret: the recommended method, and the only one open to accounts without an API token. The secret is stored encrypted and shown only by its last four characters (see security).
• Agent email and API token: the legacy method, optional. Use these only if the account already has an active token.
• Advanced: an API base URL, for instances behind a host mapping or proxy. Leave it empty otherwise.

When a client ID and secret are present, OrgRelay uses them. It posts grant_type=client_credentials to https://{subdomain}.zendesk.com/oauth/tokens with the scope read write, caches the access token for as long as expires_in allows, and requests a new one a minute before expiry or after a 401. This grant has no refresh token, so the only thing to rotate is the client secret. OAuth client login requires OrgRelay 1.4.0 or later. On Connect, OrgRelay calls /api/v2/users/me.json, shows the user's name and host, and records which sign-in method is active.

Zendesk's OAuth migration guide sets the ground rules for this grant. The client must be of kind Confidential. Calls are attributed to the Zendesk user who created the OAuth client, so that user's permissions are the real boundary and that user's name appears on every reply. Zendesk lets you restrict a client's allowed scopes. Because OrgRelay asks for read write, keep the allowed scopes blank or make sure they include read and write. The scope names in OrgRelay's catalogue (tickets:read, tickets:write, users:read) describe what the tools use. OrgRelay's auth guide covers how per-connection credentials are kept apart from staff logins.

If you still use an API token. Zendesk's announcement retires tokens in three steps. Since 28 July 2026, tokens unused for 30 days are deactivated. Since 27 October 2026, no new tokens can be created. On 30 April 2027, all remaining tokens stop working. A token connection authenticates with HTTP Basic as {email}/token and acts with that agent's permissions. If it starts failing with 401, the error message points at this timeline. Create an OAuth client, enter its ID and secret in the same connection, and clear the email and token fields.

#Which actions need approval and what the approver sees

Both writes create approval requests, and both are PUT /api/v2/tickets/{id}.json calls:

• tickets.reply. The approver sees the ticket ID, the full reply text and the public flag. Public is the default. If the AI or the requester did not say otherwise, approving sends the comment to the requester through Zendesk's normal notification triggers. An internal note needs public: false, and the result message confirms which kind was added. Approvers should open the ticket from the ID and check that the reply answers the latest comment. A ticket can move on between request and approval.
• tickets.update_status. The approver sees the ticket ID and the target status. Setting solved usually fires the requester's "ticket solved" email and starts the timer toward closed, depending on your triggers and automations.

The comment is written as the connection's Zendesk user (the OAuth client's creator, or the token's agent), not as the staff member who asked. For that reason, many teams create the OAuth client from a named account such as "Support (via OrgRelay)". The audit log records who asked and who approved. The support agent page shows a typical routing where team leads approve public replies.

#Set it up

1. Decide which Zendesk user OrgRelay's calls should be attributed to. A dedicated admin account named for OrgRelay keeps the ticket history readable. Sign in to Admin Center as that user.
2. Open Apps and integrations → APIs → OAuth clients and click Add OAuth client. Name it OrgRelay, choose client kind Confidential, and save. Copy the Unique identifier (client ID) and the Secret, which Zendesk shows once.
3. In OrgRelay, go to Admin → Business systems → App directory, choose Zendesk, enter the subdomain, client ID and secret, and click Connect.
4. Check that the name OrgRelay shows is the user you meant. The quickstart shows the same Connect and check flow for custom connectors.
5. Grant the connection to roles. Keep tickets.reply with the support team, and give other departments the read tools only.
6. Accounts moving from an API token: enter the client ID and secret in the existing connection, click Connect, then clear the email and token fields. Tokens are listed under Apps and integrations → APIs → API tokens if you want to deactivate the old one yourself.

#Limits and things it deliberately does not do

• Zendesk rate limits per plan: Team 200 requests per minute, Professional 400, Enterprise 700, and 2,500 with the High Volume API add-on. Both write tools hit the Update Ticket endpoint, which has its own limits: 100 requests per minute per account (300 with High Volume), and 30 updates per user per ticket in 10 minutes.
• OrgRelay's own limits apply on top: 120 calls per minute per connection, a 60-second pause after three consecutive failures, and about 12,000 characters of each result for the AI. Long tickets with many comments can exceed that, so ask for a summary of the latest comments.
• Not exposed: assignment, tags, custom fields, macros, merges, deleting tickets, satisfaction ratings, Help Center articles, Talk and Chat.
• Attachments are not downloaded, and comment bodies use Zendesk's plain-text version.
• Trial accounts. A Zendesk trial account is a good place to try approvals before connecting production.
• HTTP 429 from Zendesk is treated as a rate limit rather than a failure: an approved reply that hits it is queued and retried later.

#Official MCP server and OrgRelay

Zendesk's developer documentation does not describe a general-purpose MCP server for the Support API. Community-built Zendesk MCP servers exist. OrgRelay can add one as a third-party MCP connection when it serves Streamable HTTP and accepts a bearer token or OAuth client credentials. Servers that only run over stdio, or that need an interactive OAuth sign-in, cannot be connected directly. The official servers page explains how OrgRelay treats vendor servers, and the MCP overview covers the protocol basics.

Whichever route you use, OrgRelay contributes the same things. Ticket tools are granted per role and department, every reply and status change waits for an approver, Zendesk calls share one audit log with your CRM and order systems, and everything runs on the company's own machine. Enterprise patterns describes this set-up for larger support teams. The human-in-the-loop page explains why replies to customers in particular are worth a second look, and Codex or Claude Desktop users can compare it with a personal MCP set-up.

#Common questions

Zendesk no longer lets me create API tokens. How do I connect? Create a confidential OAuth client in Admin Center and enter its client ID and secret. OrgRelay exchanges them for access tokens with the client_credentials grant and renews them on its own. This requires OrgRelay 1.4.0 or later. An existing API token still works until Zendesk retires all tokens on 30 April 2027.

Whose permissions does OrgRelay use in Zendesk? With an OAuth client, Zendesk attributes every call to the user who created that client, typically an admin. With the legacy token method, it is the agent whose email you enter. Create the client while signed in as a dedicated user, so replies and audit entries show that name.

Does an approved reply go to the customer? By default, yes. tickets.reply posts a public comment unless public is set to false, in which case it becomes an internal note. The approval card shows which one it is.

#Related

• All connectors
• Shopify connector for order context behind tickets
• Security
• Enterprise patterns
• Connector check tool