Zendesk OAuth vs API Tokens in 2026: Why Macha Now Connects with OAuth by Default

Since Macha's April 9 release, new Zendesk connections authenticate with OAuth by default instead of an API token, and that matters because Zendesk stops all Support API tokens from working on April 30, 2027, with new token creation blocked from October 27, 2026. Zendesk approved Macha's global OAuth client, so new connections hand your agents a scoped, expiring, automatically refreshed token instead of a permanent all-access credential.

If you connected Macha to Zendesk early on, you probably pasted in an email address, a subdomain and an API token. It worked, but it gave your AI agents the equivalent of a master key to the account. Zendesk is now phasing out API tokens entirely for the Ticketing, Help Center and Voice APIs, so the change is less optional than it sounds.

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.

What is the difference between a Zendesk OAuth token and an API token?

Both let an outside system call the Zendesk API on your behalf. They are not equally safe. Zendesk says so in its removal announcement: "Permanent, all-or-nothing API tokens are being replaced with OAuth to give you safer, short-lived, and precisely-scoped access." Zendesk's API tokens vs OAuth access tokens dev doc spells out the mechanics: an API token isn't tied to a specific user and is limited only by the role of the email address it's paired with, whereas an OAuth access token belongs to a specific Zendesk user and is constrained by scopes.

The third-party 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.

The lifetimes in the table come from Zendesk's required-expiration announcement: since February 2, 2026, global OAuth clients must use the refresh token flow. Access tokens live 5 minutes to 48 hours (default 30 minutes) and refresh tokens 7 to 90 days (default 30 days).

How does the Zendesk OAuth flow work?

If you've only ever pasted an API token, the OAuth flow can feel like a black box. It's a standard authorization-code grant with four moving parts, and those parts are 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 response_type=code.
2. Consent. Zendesk authenticates the admin with their Zendesk login (Macha never sees it) and shows a consent screen listing what access is being granted. The admin approves or declines. This is the step that matters most: a human with authority grants the access, instead of a token being minted and emailed around.
3. Authorization code for tokens. On approval, Zendesk redirects back to Macha with a short-lived, single-use 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.
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, with no human and no re-consent.

What do OAuth scopes limit?

The scope parameter in step 1 is what makes OAuth precise. 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 if the authorizing admin is a full account owner. A leaked OAuth token can't act 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 may send codes to, and the scopes it may request). Individual customers never register or manage a client; they just click "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; you only authorize.

What 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, you're sent through Zendesk's OAuth flow (steps 1 to 4 above) instead of being asked for an API token. You log into Zendesk, approve the access 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, which is 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). Refresh is locked per subdomain, so two concurrent requests can't trample each other's tokens. Your agents keep running while the rotation happens underneath them.

For 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.

When do Zendesk API tokens stop working?

Zendesk announced in 2026 that it is removing API tokens as an authentication method for the Support API (Zendesk help). The change covers the Ticketing, Help Center and Voice APIs; tokens for Messaging, Chat and other products are not part of it. The rollout has three phases:

• July 28, 2026 (Phase 1, now in effect): unused tokens auto-deactivate. A token unused for 30+ days gets deactivated, and one that stays deactivated for another 60 days is deleted permanently. Accounts created on or after July 28, 2026 can't create or use API tokens at all.
• October 27, 2026 (Phase 2): nobody can 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): all remaining API tokens stop working, reactivation becomes impossible, and the token-management pages disappear from Admin Center.

The practical upshot for Macha customers: if your Zendesk connection still uses an API key, it's on a clock. Phase 1 is already live, so a token on a quiet account can deactivate today. Moving to OAuth now means you migrate on your schedule instead of finding a dead connection on a Monday morning.

How do I move an existing API-key connection to OAuth?

You don't have to tear anything down. OAuth connectors in Macha have a Reconnect button in the connector modal. Reconnecting re-authenticates in place: same connector ID, so your agents, tools and triggers stay wired up. There's no tool stripping and no agent breakage; you 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 existing credential fields, such as webhook IDs and signing secrets, instead of replacing the whole record. 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 and clobber each other, knocking a connection offline. Compare-before-write logic now makes concurrent refreshes safe.
• You can verify before trusting it. After connecting or reconnecting, use Test connection to confirm Macha can 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 OAuth change what Macha's agents can do?

No. A scoped token sounds like fewer abilities, but 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.

What are the caveats of switching to OAuth?

OAuth is the right default, but be clear-eyed about it:

• OAuth needs an admin to authorize it. The connect flow requires someone who can grant the access in Zendesk. That's deliberate, but it may mean looping in whoever owns your Zendesk.
• Existing API-key connections need a one-time reconnect. It's a couple of clicks and it preserves everything, but it isn't automatic.
• Scopes are bounded, not zero. OAuth limits access; it doesn't remove it. Macha's agents still take real actions on tickets, so treat agent permissions, triggers and tool activation with the same care you'd give any teammate who can reply to customers.
• The dates are Zendesk's. Zendesk has shifted timelines before, so treat October 27, 2026 as a planning anchor. Plan as if the April 30, 2027 stop is real, because it is irreversible.

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

How do I connect Zendesk to Macha with OAuth?

1. New to Macha? Start a free trial and connect Zendesk. You go straight through OAuth; nothing to configure.
2. Already connected via API key? Open the Zendesk connector, click 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.

You move off a credential Zendesk is retiring, you tighten how Macha touches your help desk, and your agents keep running.

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 with Zendesk removing 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 and 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. Zendesk caps global-client access tokens at 48 hours, so refresh is routine.

What's Zendesk's deadline for API tokens? Per Zendesk's announcement, it rolls out in three phases: unused Support API tokens began auto-deactivating on July 28, 2026; new API tokens can't be created (UI or API) from October 27, 2026; and API tokens stop working entirely on April 30, 2027. It covers the Ticketing, Help Center and Voice APIs 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.