# API tokens

A team API token gives a script access to the [public API](/developers/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.

1. In the dashboard, go to **Team → API tokens**.
2. Select **Create token**.
3. Type a name that tells you where the token is used, for example `Terraform` or `CI deploy`.
4. Select when the token expires: **30 days**, **90 days**, **1 year** or **Never**.
5. Select the abilities. **Read only** selects all read abilities. **Full access** selects all abilities.
6. Select **Create token**.
7. Copy the token. Spectate shows it only once.

:::caution
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](/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.