API tokens and the REST API
Integrations and scripts use the desk's REST API with an API token; AI assistants use the MCP server with a token or by connecting through OAuth. A token has scopes that say what it may do, and it never sees more than the person who made it.
The endpoints a token can use are described at /api/docs on your desk, and as OpenAPI 3.1 at
/api/v1/openapi.json for tools that generate clients.
Creating a token
- Go to Settings → API tokens and choose New token.
- Fill in the fields below.
- Copy the token (
sdt_…) into the integration's secret store.
| Field | What to enter |
|---|---|
| Name | What uses it, so you recognise it later. |
| What it may do | One or more scopes (below). Give each integration only what it needs. |
| Limit to a unit | Optional: the unit and everything below it. |
| Expires | In 30, 90 or 365 days, on a date, or never. You get an email a week before it runs out. |
[!IMPORTANT] The token is shown once; the desk only keeps a hash. If it's lost, revoke it and make a new one.
Using it
curl -H "Authorization: Bearer sdt_…" https://support.example.com/api/v1/cases
GET /api/v1/token answers which token this is, whose, and what it may do.
Scopes
| Scope | Allows |
|---|---|
cases:read | Cases with their conversation, attachments, saved views, labels, units, canned replies. |
cases:write | Create cases, add internal notes, change status, priority, labels, assignee and unit; merge; accept or reject held requests. |
cases:reply | Replies to the requester (they get them by email). |
contacts:read | Contacts, accounts and agreements (with Read agreements). |
contacts:write | Edit contacts; create, send, record and withdraw agreements (with Create agreements). Creating and editing accounts also needs the owner to be an admin. |
reports:read | The numbers under Reports. |
admin | Admin pages through the API (rules, service levels, forms, portals, brands, webhooks, the audit log …). Only Administrators can give it, and it can't be limited to a unit. Each page also needs its permission from the token's owner. |
Plugins that are on add their own scopes, like dev:read, dev:write and dev:admin for Software
Development; they are offered only while the plugin is on.
[!NOTE] Some things are never available to tokens, whatever their scopes: signing in and account settings, Users, Teams and Roles (people, passwords, two-factor, who holds what), Installation, and API tokens themselves. Those need a person in a browser.
What a token can see
A token acts as the person who made it, narrowed:
- It never sees more than its owner: their units, and restricted access (cases only staff in certain countries may handle) apply as in the app. A unit limit narrows it further.
- When the owner is disabled, their tokens stop working. When an admin becomes an agent, their tokens lose the admin routes.
- Things outside what it can see answer
404, as if they didn't exist.
Limits and errors
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_token | Unknown, revoked or expired token. |
| 403 | missing_scope | The token doesn't have the scope this endpoint needs. |
| 403 | not_for_tokens | The endpoint is only for people in the app. |
| 403 | admin_only | The endpoint needs the owner to be an admin. |
| 429 | rate_limited | More than 300 requests a minute with this token; Retry-After says when to try again. |
Errors have the shape { "error": { "code": "…", "message": "…", "details": … } }.
Audit and oversight
- Every write made with a token is in the audit log as
api.write(method, route, parameters), and any other entry made during that request says via token <name>. - Each token shows when and from which address it was last used.
- Admins see every token under Settings → All API tokens, with its owner, and can revoke any of them.