How to Connect Zendesk to Macha with OAuth (in 5 Minutes)

This guide walks the whole thing end to end. It takes about five minutes, most of which is Zendesk's own consent screen loading.

The short version

If you just want the steps:

1. In Macha, open Connectors and pick Zendesk.
2. Enter your Zendesk subdomain (the yourcompany in yourcompany.zendesk.com).
3. Click Connect — you're redirected to Zendesk's Authorize screen.
4. Sign in as a Zendesk admin and click Allow.
5. You land back in Macha with the connector live, tools enabled, and Help Center sync ready to switch on.

That's it. The rest of this post explains what each step does, why OAuth is the default now, and how to avoid the two or three things that trip people up.

Why OAuth (and why you don't need to create anything in Zendesk)

Connecting any third-party app to Zendesk over OAuth normally means an admin has to register an OAuth client inside Admin Center → Apps and integrations → APIs → OAuth clients, set redirect URLs, choose a client kind, and then run an authorization-code grant — Zendesk documents this whole dance in its developer docs. It works, but it's fiddly, and it's the kind of setup that stalls a trial on day one.

Macha removes that step entirely. On April 9, 2026, Zendesk approved Macha's global OAuth client — a vendor-level client that Zendesk vets once and every customer reuses. A global OAuth client means you, the customer, never create or configure a client of your own. You just hit Authorize, confirm the scopes as an admin, and you're done. From that date, OAuth became the default authentication method for new Zendesk connections, replacing API key auth.

Two practical consequences of OAuth being the default:

• No long-lived API token sitting in a settings field. OAuth issues an access token plus a refresh token. Macha refreshes the access token automatically — proactively before expiry, and as a 401 fallback if a call ever comes back unauthorized — with per-subdomain locking so two webhooks firing at once can't clobber each other's tokens. You don't manage any of this.
• Revocable from Zendesk's side. Because it's a granted authorization rather than a pasted key, an admin can revoke Macha's access from Zendesk at any time without you having to rotate a secret.

One nuance worth knowing: the onboarding flow — the very first connection Macha walks you through when you sign up — has historically used API key auth for a simpler first-run experience. The full, default OAuth path lives in the Connectors screen, which is the route this guide takes and the one to use for any production connection.

Before you start: the one prerequisite

You need Zendesk admin rights on the account you're connecting. OAuth's authorization-code grant requires a Zendesk admin to approve access on the consent screen — that's a Zendesk requirement, not a Macha one. If you're not an admin, the Allow button on Zendesk's screen won't grant the connection. Grab whoever owns your Zendesk instance for the 60 seconds it takes to click through.

You do not need: a paid Macha plan to start (a 7-day free trial, no credit card required is enough), a developer, or anything installed inside Zendesk beforehand.

Step 1 — Open Connectors in Macha

From the Macha dashboard, head to Connectors. If you're brand new, the onboarding screen nudges you to connect your first tool here — Zendesk is the natural first pick since it's the source of the tickets your agents will work.

The Connectors view lists every integration Macha supports — helpdesks (Zendesk, Freshdesk, Gorgias, Front), commerce and billing (Shopify, Stripe, Razorpay), and knowledge and comms (Notion, Confluence, Google Workspace, Slack, Airtable, and more). Find Zendesk and click it.

Step 2 — Enter your subdomain and connect

Macha asks for one thing: your Zendesk subdomain. That's the first part of your Zendesk URL — if your team lives at acme.zendesk.com, your subdomain is acme. Macha uses it to build the right authorization URL (https://{subdomain}.zendesk.com/oauth/...) so you're sent to your Zendesk instance and nobody else's.

Click Connect. Macha redirects you to Zendesk.

Step 3 — Authorize on Zendesk's screen

This is the only part that happens outside Macha. Zendesk shows its own consent page listing the access Macha is requesting. Sign in if you aren't already, confirm you're acting as an admin, and click Allow (Zendesk may label it Authorize).

Behind the scenes, Zendesk hands Macha an authorization code, Macha exchanges it for an access token and a refresh token, and stores them securely. You're redirected straight back to the Macha connector — no copy-pasting tokens, ever.

Step 4 — Confirm the connector is live and pick your tools

Back in Macha, the Zendesk connector now shows as connected. This is where the connector earns its keep: it exposes a full set of tools your agents can call on a live ticket. You decide which ones are on.

The Zendesk connector ships 17 tools, grouped by what they do:

A couple of these are gated for safety. High-impact write tools like Add Public Reply and Update Status show an activation confirmation modal when you toggle them on — a deliberate friction so you never accidentally let an agent post to customers before you mean to. Read tools are safe to leave on from the start.

Step 5 — Turn on Help Center sync (optional but recommended)

The single highest-leverage switch on the Zendesk connector is Sync Knowledge Base. Flip it on and Macha syncs your Help Center articles into its knowledge base as a live source, kept current with webhook updates — so when your agents answer a "how do I…" ticket, they're drawing on the same articles your customers see, and edits in Zendesk Guide flow through automatically.

What you've actually enabled

With the connector live, you can now point a trigger at Zendesk so agents run autonomously instead of waiting for a human to invoke them. The connector exposes eight:

• New Ticket — fires on the first customer message, before any agent replies (the classic deflection/triage entry point).
• Customer Reply — fires on every customer comment on any ticket.
• Status Changed, Priority Changed, Ticket Assigned, Ticket Closed — lifecycle events you can hook automations to.
• Messaging — WhatsApp, Messenger, Instagram, LINE, Telegram, and web chat.
• Custom Webhook — generates a URL you attach to your own Zendesk trigger in Admin Center for surgical control over exactly which tickets fire.

If you've ever wondered how the layer-on-top model works in practice: a New Ticket trigger fires, your agent reads the ticket and its custom fields, checks the Help Center, drafts or posts a reply, sets tags and status, and routes to the right group — all through the tools you just enabled, inside your existing Zendesk. See the Macha on Zendesk page for the full picture, or the Connectors docs for the reference.

Reconnecting later (and why it won't break your agents)

OAuth grants don't last forever, and admins occasionally revoke access. When that happens you don't rebuild anything — the connector modal has a Reconnect button that re-authenticates in place. It keeps the same connector ID, so it doesn't strip your tools or break the agents that depend on them, and the re-auth path preserves existing credential fields like webhook IDs and signing secrets rather than replacing the whole record. A reconnect is a 30-second click, not a re-setup.

Watch-outs and when this won't be smooth

OAuth is the easy path, but be honest with yourself about these:

• You must be a Zendesk admin. Non-admins can't approve the grant. This is the number-one reason a connection stalls — line up the admin before you start.
• Subdomain, not full URL. Enter acme, not https://acme.zendesk.com. The wrong value sends you to the wrong (or a nonexistent) authorization page.
• Onboarding vs. Connectors. The first-run onboarding may connect Zendesk via API key for simplicity. For a production connection on the default OAuth path, use the Connectors screen as shown here. If you want to move an early API-key connection to OAuth, reconnect from the connector modal.
• Multiple brands or instances. Macha lets you link more than one Zendesk account — each instance gets its own connection and credentials. Connect them one at a time; don't try to authorize two subdomains in a single pass.
• Tools default to safe. Don't expect an agent to post public replies the moment you connect. The write tools that touch customers require an explicit confirmation toggle. That's by design — turn them on when you've tested the agent, not before.

What it costs

Connecting Zendesk is free — there's no per-connector charge. What consumes credits is the work your agents do once connected: each AI action (reading a ticket, drafting a reply, calling a tool) draws from your credit balance, 0.5–9 credits depending on the model, with the default GPT-5.4 Mini at 1 credit per action. Connecting and syncing your Help Center costs nothing on its own. See the pricing page for plans and credit allowances.

FAQ

Do I need to create an OAuth client in Zendesk first? No. Macha uses a Zendesk-approved global OAuth client, so you skip the Admin Center → APIs → OAuth clients setup entirely. You just authorize.

Do I still need an API key? Not for the default flow. OAuth replaced API key auth as the default for new Zendesk connections in April 2026. API key auth still exists (and the simplified onboarding flow may use it), but the Connectors screen uses OAuth.

Who can connect Zendesk? A Zendesk admin — the authorization-code grant requires an admin to approve access on Zendesk's consent screen. You don't need admin rights in Macha beyond being able to manage connectors.

Will my tokens expire and break things? Macha refreshes the OAuth access token automatically — proactively before expiry and as a fallback on a 401 — with per-subdomain locking so concurrent refreshes don't conflict. If a grant is revoked, use Reconnect to re-authorize in place without touching your agents.

Can I connect more than one Zendesk account? Yes. Link multiple Zendesk instances; each gets its own connection and credentials. Connect them one at a time.

What does Macha get access to? Reading tickets, custom fields, and attachments; posting replies and notes; updating status, priority, type, tags, and fields; assigning and routing; and searching/syncing your Help Center. You choose which tools are enabled, and high-impact write tools require an explicit confirmation to switch on.

Connect yours

If Zendesk is where your support lives, this is the five-minute step that turns it into something your AI agents can actually act on. Start a 7-day free trial, no credit card required, open Connectors, pick Zendesk, and authorize — then read the Zendesk integration overview or the Connectors docs to wire up your first trigger.

Written by Abbas (Customer Support & AI, Macha) · Reviewed by Ankeet Guha (Co-founder & CTO) · Published 2026-06-24 · Last updated 2026-06-24.

Sources

• Zendesk, Creating and managing OAuth connections
• Zendesk, Set up a global OAuth client
• Zendesk, Using OAuth authentication with your application