Zendesk OAuth Is Now the Default in Macha (and Why That Matters)

As of our April 9 release, that's no longer how it works. OAuth is now the default authentication method for new Zendesk connections in Macha, replacing API key auth. Zendesk approved Macha's global OAuth client, which means new connections hand your agents a scoped, expiring, automatically-refreshed token instead of a permanent all-access credential.

That sounds like a plumbing change. It isn't. It's a meaningful upgrade to how safely Macha touches your helpdesk — and it lands at exactly the moment Zendesk itself is phasing out API tokens entirely. This post explains the difference between Zendesk OAuth and API tokens, what changed in Macha, and what you should actually do about it.

Quick framing reminder: Macha is an AI agent layer that sits on top of Zendesk — it reads tickets, drafts and posts replies, updates statuses, and runs autonomously on triggers. It is not a Zendesk replacement. Which is exactly why how it authenticates into your Zendesk matters so much.

OAuth vs API token: the difference in one table

Both are ways for an outside system to call the Zendesk API on your behalf. They are not equally safe. Zendesk is blunt about it in its removal announcement: OAuth "is the industry standard for secure API access and provides security capabilities that cannot be retrofitted into the API token architecture." Zendesk's API tokens vs OAuth access tokens dev doc spells out the mechanics: an API token is limited only by the role of the email address it's paired with and isn't tied to a specific user, whereas an OAuth access token is associated with a specific Zendesk user and constrained by scopes.

The third row is the one most people miss. Per Zendesk's security and authentication guidance, any app, integration, or bot offered to multiple Zendesk customers must authenticate with a global OAuth client — "it is not permissible to use a customer's credentials (an API token or a customer's own OAuth client) to authenticate their external application." Macha is exactly that kind of app. Getting our global OAuth client approved is what lets us do this the way Zendesk intends.

How Zendesk OAuth actually works

If you've only ever pasted an API token, the OAuth flow can feel like a black box. It isn't — it's a standard authorization-code grant, and it's worth understanding the four moving parts because they're exactly what makes it safer than a token.

1. Redirect to authorize. Macha sends the connecting admin to a Zendesk URL — https://{subdomain}.zendesk.com/oauth/authorizations/new — carrying Macha's client_id, a redirect_uri, the scope being requested, and a response_type=code.
2. Consent. Zendesk authenticates the admin (using their Zendesk login — Macha never sees it) and shows a consent screen listing exactly what access is being granted. The admin approves or declines. This is the single most important step: a human with authority explicitly grants the access, instead of a token being silently minted and emailed around.
3. Authorization code → token exchange. On approval, Zendesk redirects back to Macha with a short-lived code. Macha's server exchanges that code (plus its client_secret) for an access token and a refresh token. The secret never leaves Macha's backend, and the code is single-use.
4. Scoped API calls. From then on, Macha calls the Zendesk API with Authorization: Bearer {access_token}. When the access token nears expiry, Macha uses the refresh token to mint a new one — no human, no re-consent.

Scopes and least privilege

The reason OAuth is "precisely-scoped" is the scope parameter in step 1. Zendesk exposes granular scopes such as read, write, tickets:read, tickets:write, and hc:read (Help Center). An app requests only the scopes it needs, and the resulting token can do only those things — even though the authorizing admin may be a full account owner. That's least privilege in practice: a leaked OAuth token can't impersonate an admin across the whole account the way an API token can, because the token itself is the ceiling, not the user behind it.

OAuth-client setup, in one paragraph. Behind the consent screen sits an OAuth client. For a multi-customer integration like Macha, that's a global OAuth client that Zendesk reviews and approves once (registered with a unique identifier, a client secret, the redirect URIs Zendesk is allowed to send codes to, and the scopes it may request). Individual customers never register or manage a client — they just hit "Allow." If you were wiring up your own internal integration instead, you'd create a local OAuth client under Admin Center → Apps and integrations → APIs → OAuth Clients, set its redirect URL, and use its client_id/secret to run the same flow. Macha handles all of this for you; the only thing you do is authorize.

What actually changed in Macha on April 9

Two things shipped together.

1. OAuth became the default for new Zendesk connections. When you connect a new Zendesk subdomain to Macha now, you're sent through Zendesk's OAuth authorization flow (steps 1–4 above) instead of being asked for an API token. You log into Zendesk, approve the access Macha is requesting on the consent screen, and Zendesk hands back a scoped token. Macha never sees or stores your Zendesk password, and there's no permanent key sitting in our database.

2. Automatic token refresh. OAuth tokens expire on purpose — that's the security win — but an expiring token is useless if your agents stop working every few hours. So Macha refreshes Zendesk tokens proactively (before they expire) and as a 401 fallback (if a call comes back unauthorized, refresh and retry). Critically, refresh is locked per subdomain so two concurrent requests can't trample each other's tokens. Your agents keep running; the token rotation happens invisibly underneath them.

If you want the deeper version of how connectors authenticate and stay healthy, the connectors documentation walks through it, and the Macha on Zendesk page covers the full set of Zendesk actions agents can take once connected.

Why the timing matters: Zendesk is removing API tokens

This isn't a change you can shrug off as "nice to have." Zendesk announced in mid-2026 that it is removing API tokens as an authentication method for the Support API (Zendesk help). The rollout has teeth:

• July 28, 2026 (Phase 1) — unused tokens start auto-deactivating. A token unused for 30+ days gets deactivated; once deactivated for 60+ days it is deleted permanently. New accounts can no longer create API tokens at all.
• October 27, 2026 (Phase 2) — creation is shut off for everyone: accounts can no longer create new API tokens via the UI or the API. Existing active tokens keep working, but you can't mint replacements.
• April 30, 2027 (Phase 3) — the path ends. All remaining API tokens stop functioning, reactivation becomes impossible, and the token-management pages disappear from Admin Center.

The stated reason is exactly the argument above: "permanent, all-or-nothing API tokens" are being replaced with OAuth to provide "safer, short-lived, and precisely-scoped access."

The practical upshot for Macha customers: if your Zendesk connection still uses an API key, it's on a clock. Moving to OAuth now means you migrate on your schedule instead of discovering a dead connection on a Monday morning when an old token silently deactivates.

Already connected with an API key? Here's the migration

You don't have to tear anything down. OAuth connectors in Macha have a Reconnect button right in the connector modal. Reconnecting re-authenticates in place — same connector ID, so your agents, tools, and triggers all stay wired up. There's no tool stripping and no agent breakage; you just swap the credential underneath.

A few details worth knowing, because we learned them the hard way:

• Re-auth preserves your credentials. The OAuth re-auth path keeps all existing credential fields — webhook IDs, signing secrets — instead of replacing the whole blob. Your autonomous triggers don't get orphaned.
• The refresh race is fixed. An earlier version had a sharp edge: two webhooks could race to refresh the same token on a single-process server and clobber each other, knocking a connection offline. That's resolved now with compare-before-write logic, so concurrent refreshes are safe.
• You can verify before trusting it. After connecting or reconnecting, use Test connection to confirm Macha can actually reach your Zendesk. A green "verified" check means tokens, scopes, and reachability are all good.

If a connection ever does break — token revoked, scopes changed — Macha tracks connector health, deactivates the affected agents so they don't fail silently, and emails your admins with a link straight to the Reconnect flow.

Does this change what agents can do? No.

A reasonable worry: "if the token is scoped, will my agents lose abilities?" In Macha's case, no. The full Zendesk toolset is unchanged on OAuth — agents can still read tickets and resolved custom fields, analyze image attachments with AI vision, post public replies and internal notes, update statuses and tags, run autonomously on new-ticket and new-message triggers, and sync your Help Center as a live knowledge source. The difference is that those abilities now ride on a credential Zendesk can reason about, expire, and refresh — rather than a permanent skeleton key.

Watch-outs and the honest caveats

OAuth is the right default, but it's worth being clear-eyed:

• OAuth needs an admin to authorize it. The connect flow requires someone who can grant the access in Zendesk. An API token could be minted by anyone who had one; OAuth deliberately routes through an authorizing admin. That's a feature, but it does mean you may need to loop in whoever owns your Zendesk.
• There's still a one-time reconnect to do for existing API-key connections. It's a couple of clicks and it preserves everything, but it isn't automatic — you have to click Reconnect.
• Scopes are bounded, not zero. OAuth limits access; it doesn't eliminate it. Macha's agents can still take real actions on tickets (that's the whole point), so you should still treat agent permissions, triggers, and tool activation with the same care you'd apply to any teammate who can reply to customers.
• The token-removal dates are Zendesk's, and Zendesk has shifted timelines before. Treat July 28, 2026 (auto-deactivation) and October 27, 2026 (no new tokens) as planning anchors, not gospel — but plan as if they're real, because the April 30, 2027 hard stop is irreversible.

When would you not rush this? Realistically only if you have a brand-new Macha account with no Zendesk connection yet — in which case you'll get OAuth by default anyway and there's nothing to migrate.

How to do it (the 60-second version)

1. New to Macha? Start a free trial) and connect Zendesk. You'll go straight through OAuth; nothing to configure.
2. Already connected via API key? Open the Zendesk connector, hit Reconnect, approve in Zendesk, and run Test connection. Same connector ID, agents untouched.
3. Verify health. Confirm the connector shows a verified/connected status, then spot-check one agent.

That's it. You move off a deprecated credential, you tighten the security of how Macha touches your helpdesk, and your agents don't skip a beat.

FAQ

Is OAuth required now, or can I still use an API key? New Zendesk connections in Macha default to OAuth. The connector still technically supports API-key auth ("OAuth / API Key"), but given Zendesk's own removal timeline for Support API tokens, OAuth is the path we recommend for every new and existing connection.

Will reconnecting with OAuth break my agents or triggers? No. Reconnect re-authenticates in place — same connector ID, no tool stripping, and existing credential fields like webhook IDs and signing secrets are preserved. Your agents and autonomous triggers keep running.

Do I lose any Zendesk capabilities by switching to OAuth? No. The full toolset — reading tickets and custom fields, image analysis, public replies, internal notes, status/tag updates, autonomous triggers, and Help Center sync — works identically on OAuth.

What happens when the OAuth token expires? Macha refreshes it automatically — proactively before expiry and as a fallback if a call returns 401 — with per-subdomain locking so concurrent refreshes don't conflict. You won't notice it happening.

What's Zendesk's deadline for API tokens? Per Zendesk's announcement, it rolls out in three phases: unused Support API tokens begin auto-deactivating on July 28, 2026; new API tokens can no longer be created (UI or API) from October 27, 2026; and API tokens stop working as an auth method entirely on April 30, 2027. This affects Support API tokens only. (source)

Why does Macha need a "global OAuth client" specifically? Zendesk requires third-party apps and integrations offered to multiple customers to authenticate via a global OAuth client, rather than using each customer's API token or personal OAuth client. Zendesk's approval of Macha's global OAuth client is what makes the OAuth-by-default flow possible. (source)

Want the full picture of what Macha's agents do once they're connected to Zendesk? See Macha on Zendesk, the Zendesk integration details, and more release notes on the blog.