Authentication

Every API request is authenticated with an API token. A token acts as the staff member who owns it: it can see and change exactly what that person can in the agent workspace, limited further by the token’s scope.

Create a token

1. Open Admin Center, Integrations, API tokens.
2. Choose New token, give it a name that says what uses it (for example “Billing sync”), and pick a scope.
3. Copy the token. It starts with desk_ and is shown only once.

Scope	Allows
read	GET requests only
write	Every method: GET, POST, PUT, PATCH, DELETE

Create a separate token for each integration, owned by a dedicated integration user where you can. Revoking it then affects only that integration.

Send the token

GET /api/tickets HTTP/1.1
Host: yourcompany.chaosdesk.io
Authorization: Bearer desk_xxxxxxxxxxxxxxxxxxxx
Accept: application/json

Responses are JSON (application/json) or JSON-LD (application/ld+json) depending on the Accept header. Partial updates use PATCH with Content-Type: application/merge-patch+json.

Errors

Status	Meaning
401	Missing, invalid, expired or revoked token
402	The feature is not part of your plan (plan_required)
403	The token owner is not allowed to do this, or a read token tried to write
422	Validation failed; the body lists the fields
429	Rate limit reached, see rate limits

Errors use RFC 9457 problem details (application/problem+json).

Zendesk-compatible API

The Zendesk-compatible API accepts the same tokens with the Zendesk authentication styles: {email}/token:{token} Basic auth, a bearer token, or OAuth client credentials.