API tokens

1. Select the team the integration works for, then open Settings → API Tokens.
2. Create a token and tick only the abilities the integration needs.
3. Copy the token immediately; it is shown once. Store it in a secret manager. Revoke it from the same screen if it is exposed.
4. Send Authorization: Bearer YOUR_TOKEN and Accept: application/json with every request.

Abilities

| Ability | Allows | |---------|--------| | sites:read | List and read sites, uptime, performance, status pages, /me, /stats and /reports | | sites:write | Create, update, delete, pause, resume and snooze sites; post status page updates | | checks:read | List a site's checks and read check history | | checks:write | Create, update and delete checks | | incidents:read | List and read incidents and performance incidents | | reports:read | Export SLA reports and incident CSVs |

A token without an ability receives 403 for routes that need it. Team viewers are read-only through the API as well: :write abilities are refused for them.

Team binding

A token is bound to the team that was selected when it was created, even if you later switch teams in the browser. If you leave the team, the token stops working. Older tokens without a team binding return 403 and must be replaced.

Tokens are managed in the browser only. The /api/v1/tokens endpoints refuse requests authenticated with a token.

Errors

| Status | Meaning | |--------|---------| | 401 | Missing or invalid token | | 402 | The team's trial has expired or its subscription is inactive | | 403 | Missing ability, viewer role, or token without a valid team binding | | 422 | Validation failed; the body lists the errors | | 429 | More than 60 requests per minute |

Never use a poller credential as a customer token.