# Authentication: Sites in the Woods API

## What's public
The status pages, https://sitesinthewoods.com/llms.txt, the API docs (https://sitesinthewoods.com/api/docs) and the OpenAPI document (https://sitesinthewoods.com/openapi.json) need nothing. The data routes under https://sitesinthewoods.com/api/ need a key.

## Getting a key
Keys are for a team's agents and scripts. Sign up at https://sitesinthewoods.com/login (an emailed code, no password), and an admin creates a key on the dashboard's API keys page, choosing what it can do; it's shown once. A key sees only its own team's sites.

## Using a key
Send it on every request: `Authorization: Bearer sm_…` (any capitalisation of Bearer), or `X-API-Key: sm_…`.
A Viewer key reads (GET and HEAD). On teams with 10 sites or more, a Member key can also dismiss incidents, ask for a check again and start or end maintenance windows, and an Admin key can also pause and resume sites: the POST routes below. A key never does more than its creator can now. It never expires; it stops working when it's revoked. To rotate, create a new key, switch to it, then revoke the old one.

## Errors
- `unauthorized` (401): No key, or an unknown or revoked one.
- `forbidden` (403): A write by a key whose role or team can't make it (writes need a Member or Admin key and 10 sites), a POST to a route that only reads, a write without a key, or a form post from another site.
- `not_found` (404): An unknown site slug or API path.
- `method_not_allowed` (405): Anything but GET or HEAD on a page.
- `conflict` (409): A write this incident can't take (one that can't be checked again, say).
- `validation_error` (400): A parameter isn't valid; `issues` says which.
- `request_too_large` (413): A request body over 64 KB.
- `rate_limited` (429): More requests this minute than the key's team's sites allow (comes with Retry-After): 60 on the free site, 300 from 2 sites, 1,000 from 25.
- `auth_unavailable` (503): The key or sign-in couldn't be checked right now (comes with Retry-After). Your key or session is probably fine: retry.

A 401 carries `WWW-Authenticate: Bearer`. A 503 means the key (or, in the dashboard, the sign-in) couldn't be checked; retry after the `Retry-After` seconds, your key is probably fine.

## Limits
Requests a minute per key, by the team's sites: 60 on the free site, 300 from 2 sites, 1,000 from 25 (then 429 with Retry-After); writes are also capped at 10 in 10 seconds per key. Every keyed answer carries RateLimit-Policy and RateLimit (IETF draft 11) with what's left. The data changes once a minute, so poll at most once a minute.
