To get a Zendesk API token, an admin first enables API access in Admin Center → Apps and integrations → APIs → API configuration (accept the terms, then turn on Allow API token access), then generates a token under APIs → API tokens → Add API token. Use the token with Basic auth: base64-encode {email_address}/token:{api_token} and send it in the Authorization header.
The rest of this page covers where the credential goes, a working code sample, and the errors you'll hit if token access isn't enabled or the format is wrong.
Prerequisites
Administrator access to your Zendesk account's Admin Center - only admins can turn on API token access and generate tokens (source: Zendesk Help, Managing API token access to the Zendesk API).
A verified user (email address) on the account - API tokens are used alongside a verified user's email, not on their own.
A decision on whether an API token (simple, account-wide Basic auth) or an OAuth access token (scoped to an OAuth client, supports CORS) fits your integration (source: Zendesk Developer Docs, Security and authentication)
Step-by-step: creating a Zendesk API token
- In Admin Center, click Apps and integrations in the sidebar, then go to APIs → API configuration.
- Accept the Zendesk Terms of Service and Application Developer and API Agreement, then check Allow API token access and click Save (Zendesk Help, Turning on and off API access).
- Still under Apps and integrations, go to APIs → API tokens.
- Click Add API token, optionally enter a description, then click Save.
- Copy the token immediately — once you close this dialog, the full token is never shown again; only a truncated version is visible afterward (Zendesk Help, Managing API token access to the Zendesk API).
- Store the token alongside the email address of a verified user — both are required to authenticate.
Where the credential goes
Zendesk API tokens use Basic authentication, combined with a verified user's email address. Build the credential string as:
{email_address}/token:{api_token}Base64-encode that string and send it in the Authorization header:
Authorization: Basic <base64-encoded {email}/token:{api_token}>With curl, you can skip the manual encoding by passing -u:
curl https://yoursubdomain.zendesk.com/api/v2/users/me.json \
-u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv(Zendesk Developer Docs, Security and authentication)
Connector-specific gotcha: API token access is off by default at the account level. If you generate a token under APIs → API tokens before enabling Allow API token access in API configuration, every request authenticated with that token returns 401 Unauthorized - The token itself is valid, but the account isn't accepting token-based auth yet. If your brand-new token doesn't work, check the API configuration toggle first, not the token.
A few other things to know:
- Lifetime: API tokens don't expire on their own. They remain valid until an admin deactivates and deletes them. You can have up to 256 active tokens (existing accounts that already exceed this have a cap of 2,048).
- Scope: an API token isn't tied to a single user - it's account-wide. Any verified user's email can be paired with any active token to authenticate, and the resulting request has that user's permissions. Treat tokens like shared admin passwords.
- Revocation: deactivate the token from APIs → API tokens (this immediately breaks any requests using it), then delete it once you've confirmed nothing else depends on it. A token must be deactivated before it can be deleted.
If you need OAuth instead (scoped, per-app access)
If you're distributing an integration to multiple Zendesk accounts, or want CORS-friendly browser requests and tokens scoped to a specific OAuth client, use an OAuth access token instead. Create an OAuth client in Admin Center, run the authorization flow, and send the resulting token as:
Authorization: Bearer <access_token>OAuth access tokens can be up to 184 characters and are scoped to the Zendesk instance whose OAuth client issued them (Zendesk Developer Docs, Security and authentication).
Minimal working example
This calls /api/v2/users/me.json, which returns the authenticated user's profile — a good smoke test for a new token.
curl:
curl "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/me.json" \
-u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"Node.js:
const credentials = Buffer.from(
`${process.env.ZENDESK_EMAIL}/token:${process.env.ZENDESK_API_TOKEN}`
).toString("base64");
const res = await fetch(
`https://${process.env.ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/users/me.json`,
{
headers: {
Authorization: `Basic ${credentials}`,
},
}
);
console.log(await res.json());Store ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, and ZENDESK_API_TOKEN as environment variables — never hard-code the token or commit it to source control.
Common errors and fixes
Why am I getting 401 Unauthorized with a valid token?
The most common cause is that Allow API token access isn't enabled in Admin Center → Apps and integrations → APIs → API configuration. Enable it, save, and retry. Also double-check the credential format — it's {email}/token:{api_token}, including the literal /token, not just the email and token separated by a colon (Zendesk Help, Turning on and off API access).
Why am I getting 403 Forbidden?
The token is valid and account-wide, but the user whose email you paired it with doesn't have permission for that endpoint — for example, a non-admin agent calling an admin-only endpoint. Pair the token with a user (or admin) that has the right role for the resource you're calling.
Why am I getting 429 Too Many Requests?
You've exceeded your plan's API rate limit (200–2,500 requests per minute depending on plan, or lower for specific endpoints). The response includes a Retry-After header telling you how many seconds to wait, and X-Rate-Limit / X-Rate-Limit-Remaining headers show your limit and remaining quota for the current minute (Zendesk Developer Docs, Rate limits).
The faster way
Enabling token access, generating a token, and getting the Basic auth encoding right works fine for one Zendesk account. It gets more involved once you're connecting Zendesk alongside other ticketing tools — each with its own auth scheme, object model, and rate-limit shape. Knit's unified Ticketing API normalizes Zendesk alongside connectors like Freshdesk and Intercom behind one schema, handles token storage, and manages rate-limit backoff for you. See the Zendesk Ticketing API overview for what's available, or book a demo to see it against your own account. You can also sign up free and connect a sandbox Zendesk account.
FAQ
Where do I generate a Zendesk API token?
In Admin Center, go to Apps and integrations → APIs → API tokens and click Add API token. Before this works, an admin must first enable Allow API token access under APIs → API configuration. Copy the token immediately after creating it - Zendesk only shows the full value once.
Why does my Zendesk API request return 401 even though my token is correct?
Almost always because Allow API token access hasn't been turned on in API configuration, or because the Authorization header isn't formatted as {email}/token:{api_token} (base64-encoded for the header, or passed via -u in curl). Both the toggle and the format need to be correct.
Is a Zendesk API token tied to one user?
No. An API token is account-wide - it's an auto-generated password that can be combined with any verified user's email address. The permissions on a given request come from whichever user's email you paired with the token, not from the token itself. Because of this, Zendesk recommends treating tokens like shared admin passwords and deleting any you're not using.
Should I use an API token or OAuth for my Zendesk integration?
API tokens are simplest for a single account and internal tools. Use OAuth access tokens if you're building something distributed to multiple Zendesk accounts (Zendesk's developer terms require global OAuth tokens for that case), or if you need CORS-friendly browser requests and per-client scoping. Knit's Zendesk connector handles the OAuth flow for you if you connect via Knit.
What are Zendesk's API rate limits?
They depend on your plan: roughly 200 requests/minute on Team, 400 on Growth/Professional, 700 on Enterprise, and up to 2,500 on Enterprise Plus or with the High Volume API add-on. Some endpoints have their own tighter limits - for example, updating the same ticket is capped at 30 times per 10 minutes per agent. Knit manages this backoff automatically across the Zendesk connections it handles.
