API tokens
A team API token gives a script access to the public API for one team. The token belongs to the team, not to the member who created it. It continues to work when that member leaves the team.
Create a token
Owners and managers can create tokens.
- In the dashboard, go to Team → API tokens.
- Select Create token.
- Type a name that tells you where the token is used, for example
TerraformorCI deploy. - Select when the token expires: 30 days, 90 days, 1 year or Never.
- Select the abilities. Read only selects all read abilities. Full access selects all abilities.
- Select Create token.
- Copy the token. Spectate shows it only once.
Keep the token secret. Anyone with the token can do everything that its abilities allow. Do not put a token in client-side code or in a public repository.
Abilities
A token can only do what its abilities allow. There is no wildcard ability, so a token never gets new abilities later. You cannot change the abilities of a token after you create it. Create a new token instead.
You can only give abilities that your own role has. Each endpoint in the API reference shows the ability that it needs.
| Ability | What the token can do |
|---|---|
monitors:read | Read monitors, their checks, uptime and certificates. |
monitors:write | Create and change monitors, and pause or resume them. |
monitors:delete | Delete monitors. |
hosts:read | Read hosts, their metrics and metric conditions. |
hosts:write | Change hosts, install tokens and metric conditions. |
hosts:delete | Delete hosts. |
domains:read | Read domains and their registration and DNS state. |
domains:write | Add and change domains. |
domains:delete | Delete domains. |
projects:read | Read projects. |
projects:write | Create and change projects. |
projects:delete | Delete projects. |
alerting:read | Read alerts, channels, escalation paths, alert sources and on-call schedules. |
alerting:write | Create and change channels, escalation paths, alert sources and on-call schedules. |
alerting:delete | Delete channels, escalation paths, alert sources, on-call schedules and resolved alerts. |
alerts:acknowledge | Acknowledge alerts. This stops their escalation. |
alerts:resolve | Resolve alerts by hand. |
incidents:read | Read incidents, their updates, timeline and postmortem. |
incidents:write | Declare, update, acknowledge and resolve incidents. |
incidents:delete | Delete incidents. |
status-pages:read | Read status pages, components, status page incidents, maintenances and subscribers. |
status-pages:write | Create and change status pages, components, status page incidents and maintenances. |
status-pages:delete | Delete status pages, components, status page incidents, maintenances and subscribers. |
members:read | Read team members and pending invites. |
members:write | Invite members, change their roles and remove them. |
team:update | Change the name and settings of the team. |
billing:read | Read the subscription, notification credits and plan usage. |
A token cannot manage API tokens, open support tickets, change billing or delete the team.
Token format
Tokens start with spct_, followed by 46 letters and digits. The last 6 characters are a checksum. Secret scanners can use the prefix and the checksum to find leaked tokens. Spectate keeps only a hash of each token, so a lost token cannot be recovered.
Regenerate or revoke a token
In Team → API tokens, each token has two actions:
- Regenerate gives the token a new secret. The name, abilities and expiry stay the same. The old secret stops working immediately.
- Revoke stops the token permanently. Revoked and expired tokens stop working immediately.
A team can have 50 active tokens at most.
Changes made with a token
Spectate shows changes made with a token under the token's name, for example API token "Terraform". You see this name in incident timelines, in Slack messages and in the activity log.