# Authentication

All endpoints require API key authentication via bearer token.

## Header

```
Authorization: Bearer <api_key>
```

## Scopes

Keys are issued with explicit scopes (for example: `free:ask`, `groups:read`,
`groups:write`, `recruit:read`, `recruit:write`, `studies:read`,
`studies:write`, `thesis:read`, `thesis:write`, `org:entitlements:read`,
`org:audit:read`,
`zeitgeist:read`, `zeitgeist:write`, `billing:read`, `billing:write`).
Requests without required scopes receive `403 Forbidden`.

## Thesis Lab And Recruitment Scopes

Wave 1 Thesis Lab endpoints use the newer recruitment and thesis scopes:

- `recruit:read`: preview research-group criteria.
- `recruit:write`: create research groups from descriptions and ask existing
  research groups through the quota-aware golden path.
- `thesis:write`: compose a thesis and launch initial recruitment.
- `org:entitlements:read`: read full organization entitlement/quota/legal state.
- `org:audit:read`: read redacted organization audit history. `thesis:admin`
  is accepted for this route only during the configured Scope B grace window.

Compatibility aliases remain during migration:

- `groups:read` implies `recruit:read`.
- `groups:write` implies `recruit:write`.
- `studies:read` and `studies:write` remain accepted on legacy study/group
  surfaces where documented.
- `thesis:admin` implies full entitlement discovery and temporarily allows
  audit-history reads until `THESIS_LAB_ORG_AUDIT_READ_GRACE_END_DATE`.

The public entitlement endpoint,
`GET /v1/organization/entitlements/public`, accepts any read-capable or
write-capable organization key listed in its OpenAPI contract. The full
entitlement endpoint requires `org:entitlements:read` or its admin implication.

## Acting User

Server-to-server clients may pass `X-Acting-User-Id` where the route supports
delegated user attribution. The acting user must belong to the same
organization as the API key. Cross-organization acting-user attempts are denied
and recorded for audit.

## Security Tips

- Store keys in a secret manager or environment variables.
- Rotate keys regularly and revoke unused keys.
- Do not embed keys in client-side apps.

## Admin API Keys

Admin endpoints (`/api/admin/*`) require admin keys with `admin:access` plus
any endpoint-specific admin scopes (ex: `admin:read`, `admin:write`).

- Admin keys are for server-side callers only (Edge functions, MCP server,
  Claude Code).
- Use an admin key prefix such as `rk_admin_live_` or `rk_admin_test_`.
- Optionally send `X-Admin-Client` for caller attribution and `X-Request-ID`
  for request tracing.