# Authentication

> **Setting up Authentik?** See [authentik-setup.md](authentik-setup.md)
> for the step-by-step provider + application + property-mapping walkthrough
> and the matching anchorage.yaml snippet.

## Actors

- **Browser users** — authenticate once via Authentik (OIDC, Authorization Code + PKCE). anchorage validates Authentik's ID token against its JWKS, upserts the user, issues a short-lived session cookie.
- **Programmatic clients** (kubo's `ipfs pin remote`, CI pipelines, scripts) — present `Authorization: Bearer <jwt>` where the JWT was minted by anchorage itself.

## Token lifecycle

1. Signed-in user calls `POST /v1/tokens` with a label + scopes.
2. anchorage signs a JWT: `{sub, org, role, scopes, jti, iat, exp}`. The `jti` is a TypeID (`tok_...`). Only the *metadata* (label, scopes, expires_at) is persisted; the signed string is returned to the user **once**.
3. Client presents the JWT. Middleware validates signature + expiry + denylist (`token_denylist` keyed by `jti`).
4. Revocation writes the `jti` to `token_denylist` with its natural expiry; the row is pruned hourly.

## Why JWT + denylist rather than opaque DB tokens

- Denylist is *only* consulted for revoked tokens — a warm `token/deny` ristretto cache means the hot path is zero DB reads.
- Claims travel with the request — RLS can set `anchorage.org_id` per-transaction from the JWT without another lookup.
- Short TTLs (default 24h) plus revocation cover the usual "compromised token" threat model without requiring per-request DB hits.

## Sysadmin bootstrap

`bootstrap.sysadmins: [admin@example.com, ...]` in config. First Authentik login for any listed email promotes the user to `is_sysadmin=true`. The config is only consulted on first login; later changes need the admin CLI.