# Authentication

Every documented API key call authenticates with a personal **API key**. There is no application-level credential and no anonymous access for these endpoints.

## Use a key

```bash
curl https://api.sair.foundation/api/public/v1/me \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

Set `$SAIR_API_KEY` to your key. Keys are accepted only via the `Authorization` header. Query string, cookie, and form-field credentials are rejected.

Key format: `sair_<id>_<secret>`, e.g. `sair_a1b2c3d4_zR9...`.

## Scopes

`<domain>.<action>` — two segments, lowercase, kebab-case domain.

| Scope                        | Grants                                                                                                                              |
| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `competition.read`           | Competition metadata, your participation status, leaderboards, your submissions, and stored text bodies.                            |
| `competition.write`          | Create competition submissions (resubmit to revise).                                                                                |
| `playground.read`            | Models and problem sets; your cheatsheets and solver templates; your runs, results, and usage.                                      |
| `playground.write`           | Create / modify your cheatsheets and solver templates; submit and cancel runs.                                                      |
| `contributor-network.read`   | Browse shared items per competition, read benchmark results, walk the lineage graph, read comments.                                 |
| `contributor-network.write`  | Publish or withdraw items, favorite items, post or delete comments. Does **not** grant read.                                        |

Rules:

- `.write` does **not** imply `.read` — request both if you need both.
- `playground.*` is not subdivided by submission kind.
- Scopes are the **upper bound** of what a key can attempt. Every request is re-checked against your account state (enrollment, team role, email verification, deadlines, resource ownership). A `competition.write` key can't submit to a competition you didn't enroll in; a `playground.write` key can't edit a cheatsheet you don't own.