# Tokens and scopes

> Create API tokens in Settings → API, choose the right scopes and send the token in the Authorization header.

URL: https://docs.proteside.com/en/docs/api/authentication

Every API call (except the OpenAPI document) requires a token. The token belongs to the **organization**, not to a
user or a store: it's valid for every store in the organization and keeps working if the person who created it
leaves the team.

## Create a token
Only the **organization owner** can create and revoke tokens. Other roles see the message "Only the organization
owner can manage tokens." instead of the list.

### Open the tokens screen
In the store switcher, choose a store from the organization that will use the token. Then open
**Settings → API**. The token is created for the selected store's organization.

### Click New token
Click **New token** in the top-right corner.

### Give it a name
Fill in **Name** with something that identifies the integration, for example "production CI" or "SIEM". The name
accepts up to 80 characters and appears in the list and in the audit log.

### Check the scopes
Under **Scopes**, check only what the integration needs. The **read-only**, **all** and **none** shortcuts help you
get started. You must check at least one. Scopes can't be changed later: to change them, create another token.

### Choose the validity
Under **Validity**, choose **No expiry**, **30 days**, **90 days** or **365 days**. After that period, the token
starts responding `401 Token expired`.

### Copy the token
Click **Create token**. In the **Copy your token now** window, click **Copy** and store the token in a secrets vault
before clicking **Done**.

> **The token is shown only once**
>
> Proteside stores only a hash of the token. If you close the window without copying it, there's no way to recover
> it: revoke it and create another one.

*Image: The list shows each token's prefix, scopes, last use and status (Active, Expired or Revoked).*

> **Store owner isn't the same as organization owner**
>
> The screen shows the **New token** button to anyone who owns the selected store, but creating a token requires
> being the **organization** owner. If you see the error "Only the organization owner can manage tokens." when you
> click **Create token**, ask the organization owner to create the token.

## Use the token
The token has the format `ps_live_` + 24 characters + `_` + 32 characters (65 in total). Send it in the
`Authorization` header of every request:

```bash
curl -s "https://app.proteside.com/api/v1/stores" \
  -H "Authorization: Bearer ps_live_YOUR_TOKEN"
```

The first 32 characters (`ps_live_` + 24) are the **prefix**: it's what appears in the list's **Prefix** column and
in the audit log entries for actions made through the API (`api:ps_live_YOUR_PREFIX`).

When the token fails, the API responds `401` with the `WWW-Authenticate: Bearer realm="proteside-api"` header and one
of these messages:

| `message`                           | Cause                                                            |
| ----------------------------------- | ---------------------------------------------------------------- |
| `Missing or malformed bearer token` | Missing header, no `Bearer`, or token not in the expected format |
| `Invalid token`                     | Token doesn't exist or was revoked                               |
| `Token expired`                     | Validity period has ended                                        |

The **Last used** column is updated at most once per minute per token.

## Scopes
Each endpoint requires **exactly one** scope. There's no hierarchy: `stores:write` doesn't include `stores:read`, so
an integration that creates and then reads stores needs both. Without the scope, the response is
`403 insufficient_scope`.

| Scope              | What it grants                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stores:read`      | `GET /stores`, `GET /stores/{id}`, `GET /stores/{id}/status`, `GET /stores/{id}/pages`                                                            |
| `stores:write`     | `POST /stores`, `PATCH /stores/{id}`, `DELETE /stores/{id}` (suspends), `POST /stores/{id}/rotate-key`                                            |
| `pages:write`      | `POST /stores/{id}/pages`                                                                                                                         |
| `scripts:read`     | `GET /scripts` and `GET /rules`                                                                                                                   |
| `scripts:review`   | `POST /scripts/{id}/authorize`, `POST /scripts/{id}/block`                                                                                        |
| `rules:write`      | `POST /rules`, `PATCH /rules/{id}`, `DELETE /rules/{id}`, `DELETE /rules?id=`                                                                     |
| `policies:read`    | `GET /policies`, `POST /policies/{id}/simulate`                                                                                                   |
| `policies:write`   | `POST /policies`, `PATCH /policies/{id}`, `DELETE /policies/{id}`, `POST /policies/{id}/apply`                                                    |
| `alerts:read`      | `GET /alerts`, `GET /alerts/{id}`                                                                                                                 |
| `alerts:write`     | `PATCH /alerts/{id}` (resolve and reopen)                                                                                                         |
| `reports:read`     | `GET /reports/pci`, `GET /reports/pci/snapshots`, `GET /reports/pci/snapshots/{id}`, `GET /reports/pci/schedule`                                  |
| `reports:generate` | `POST /reports/pci/schedule`, `DELETE /reports/pci/schedule`; also required, together with `reports:read`, for `GET /reports/pci?regenerate=true` |
| `webhooks:manage`  | All `/webhooks` endpoints, including reading and testing                                                                                          |
| `orgs:manage`      | `GET /organizations`, `POST /organizations` and using `org_id` to act on a child organization ([Partners](https://docs.proteside.com/en/docs/api/partners))                        |
| `usage:read`       | `GET /organizations/{id}/usage`                                                                                                                   |

The **read-only** shortcut checks `stores:read`, `scripts:read`, `policies:read`, `alerts:read`, `reports:read` and
`usage:read`.

> **Listing rules requires scripts:read**
>
> The OpenAPI spec describes `stores:read` as the scope for reading rules, but `GET /rules` requires `scripts:read`.
> If your integration lists rules, include `scripts:read` in the token.

> **A read that generates data**
>
> `GET /reports/pci` without `period_start` and `period_end` generates a new report on every call, even with a
> read-only token. See [Recipes](https://docs.proteside.com/en/docs/api/recipes#baixar-o-relat%C3%B3rio-pci-dss-em-pdf) to download reports without
> generating copies.

## Revoke a token
In **Settings → API**, click **Revoke** on the token's row and confirm. The effect is immediate: the next call with
that token gets `401 Invalid token`. The token stays in the list with the **Revoked** status, for the record.

There's no API endpoint to create, list or revoke tokens: this is done only in the dashboard.

## Best practices
* **One token per integration.** That way you can revoke one without taking down the others, and the audit log shows
  which system made each change.
* **Least privilege.** An alert collector for your SIEM only needs `alerts:read`. A pipeline that only downloads
  reports only needs `reports:read`.
* **Keep it in a secrets vault** (AWS Secrets Manager, GCP Secret Manager, Vault, protected CI variables). Never put
  the token in source code, on the front end or in logs.
* **Rotate with overlap.** Create the new token, update the integration, confirm in the **Last used** column that the
  old one is no longer being used, and only then revoke the old one. Prefer a 90- or 365-day validity to force
  rotation.
* **Revoke at the slightest sign of a leak.** The token gives access to every store in the organization.

## Next steps
- [Conventions](https://docs.proteside.com/en/docs/api/conventions): Pagination, errors, rate limits and idempotency.
- [Tokens in the dashboard](https://docs.proteside.com/en/docs/guide/settings/api-tokens): The Settings → API screen in detail.
