Every API request sends a team API token in the `Authorization` header:

```http
GET /api/v1/monitors HTTP/1.1
Host: monitor.agilepixel.io
Authorization: Bearer 3|example-sanctum-token
Accept: application/json
```

Heartbeat pings and badges are the exceptions: they need no token.

## Create a token
1. Sign in as an Owner or Admin of the team, and switch to that team.
2. Open **Settings, API tokens** and name the token after what will use it, such as "Deploy pipeline" or "Claude agent".
3. Copy the token straight away. It is shown once; AgileMonitor stores only a hash of it.

A token belongs to the team that was current when it was made, and every request it makes acts on that team. The `X-Team-Id` header can't move it to another team.

## What a token may do
A token acts with its creator's role in the team, checked on every request:

| Role | Read | Create, update, pause and delete | Secrets |
|---|---|---|---|
| Owner | Yes | Yes | Shown |
| Admin | Yes | Yes | Shown |
| Viewer | Yes | No: 403 | Masked as `********` |

Secrets are a monitor's request header values, contact webhook paths and Telegram bot tokens.

If the creator leaves the team, the token stops working with a 403.

## Lifetime and replacing a token
Tokens don't expire. To replace one, for example when someone who had it leaves:

1. Create a new token.
2. Switch your client or agent to it.
3. Revoke the old token in **Settings, API tokens**. It stops working at once.

## 401 or 403
| Status | Means | Do |
|---|---|---|
| `401` | There is no token, or it is invalid or revoked. The response has `WWW-Authenticate: Bearer` | Check the header is `Authorization: Bearer <token>` and the token hasn't been revoked |
| `403` | The token is valid but may not do this: a Viewer tried to change something, the token isn't pinned to a team, or its creator has left the team | Use a token made by an Owner or Admin of the right team |

A record that belongs to another team is a `404`, the same as one that doesn't exist.