TRUSCA API (2.2.0)

Public — no authentication required, but limited per PASSWORD_RESET_RATE_LIMIT (5/min/IP by default).

Body shape: {"email": "<address>"}. Always returns 204 + empty body (CWE-204). When the address matches a registered user we additionally enqueue an email via Celery. When the per-email cooldown is active we set Retry-After to the configured cooldown and STILL return 204.

Public — no authentication required, but limited to 5 attempts/minute/IP.

On success: 200 + access_token in the body, refresh as HttpOnly cookie. On bad credentials: 401 problem+json.

Revoke the refresh cookie. Idempotent — always returns 204 even if the cookie is absent or already revoked.

Authenticated. UserPublic + the caller's team memberships.

The frontend reads memberships to resolve a team_id for project creation / write scoping. Ordered oldest-first so memberships[0] is a stable default team.

Public. The pending token from POST /auth/login is the credential, and it is worth nothing on its own.

On success: 200 + access_token, refresh as an HttpOnly cookie. This is the first point at which a session exists.

Public — no authentication required (explicit exception to CLAUDE.md core rule #12: the consumer is the anonymous /login page, which must decide which OAuth sign-in buttons to render BEFORE any credential exists).

Always lists every supported provider with a bare configured boolean. configured is True only when both the client id AND client secret are set — the same condition under which /{provider}/authorize actually works (M-15: a half-configured or unconfigured provider previously surfaced as a rendered button that 503'd on click).

Security: the response carries booleans only — never client ids, secrets, or any other configuration detail.

Public — no authentication required.

302 → provider's authorize URL with a signed state. Returns:

• 503 + oauth_provider_disabled Problem Details when the provider's client id/secret is not configured.
• 404 Problem Details when the provider name is unknown (FastAPI's Literal[] gate normally catches this; the explicit branch survives future enum widening).
• 403 demo_read_only Problem Details when the deployment runs in read-only live-demo mode (OAuth sign-in is a write; see :func:_demo_read_only_blocked).
• 429 when an IP exceeds OAUTH_AUTHORIZE_RATE_LIMIT. Looser than the login limit on purpose: there is no credential to guess here, and an office behind one NAT address signs in together. The limit is a backstop; what actually bounds the cost of a cold discovery cache is the provider's own failure cache.

Public — the provider's redirect lands here after consent.

Success path: 302 → redirect_after (or configured default) with the refresh-token HttpOnly cookie attached.

Failure path: 302 → configured failure URL with ?error=<reason>. The provider's own ?error=access_denied (user clicked "Cancel") falls through here too — we forward a normalised error=oauth_denied.

Read-only demo: if DEMO_READ_ONLY is enabled we 403 BEFORE any token exchange or DB write (see :func:_demo_read_only_blocked), so the callback can never create/link a User or Team in the demo.

Public — the refresh cookie is the credential.

Successful rotation: 200 + new access_token + new refresh cookie. Reuse detected (cookie already rotated): 401, entire chain revoked.

Public, no authentication required.

Limited to REGISTRATION_RATE_LIMIT (5/min/IP by default): the bcrypt password hash is CPU-bound, so an uncapped public endpoint could occupy the worker's event loop with unauthenticated requests.

Returns the new user (without password). 422 for validation errors, 409 if the email is already registered, and 404 when the deployment maintains its roster itself (AUTH_SELF_REGISTRATION=false), which is the same answer an outsider gets for any route that is not there.

Public — the reset token is the credential.

Limited to PASSWORD_RESET_CONFIRM_RATE_LIMIT (5/min/IP by default, same as login): the token is guessable the same way a password is, and the verify path costs a bcrypt call per live candidate, so this endpoint needs no less protection than login (F1, concurrency-scaling-plan-2026-08-22.md).

On success: 204 + every refresh token for the user is revoked. On bad / expired / used token: 422 problem+json.

Cheap PURE-LIVENESS probe used by docker-compose / k8s liveness checks.

PUBLIC / unauthenticated (CLAUDE.md rule #12 explicit exception). This proves only that the uvicorn process is accepting requests — it does NOT touch the database and says nothing about schema state. For "is the schema migrated and safe to serve traffic / start workers", use GET /health/ready (api/v1/health.py).

v2.1 Track B (B5): also surfaces demo_read_only so the SPA can render the read-only banner and disable write actions without needing a separate build. The flag is resolved at request time (CLAUDE.md rule #11), so the same image behaves correctly whether DEMO_READ_ONLY is set or not.

Also surfaces demo_sandbox_scans — only true when the read-only demo has the opt-in sandbox carve-out enabled (both DEMO_READ_ONLY and DEMO_ALLOW_SANDBOX_SCANS). The SPA uses it to re-enable the bounded scan / SBOM-ingest affordances on the Demo Sandbox project while keeping every other write disabled.

Return 200 when the DB schema matches the Alembic HEAD, else 503.

PUBLIC: no auth dependency by design (probe endpoint — see module docstring and CLAUDE.md core rule #12). The check is read-only (a single SELECT on alembic_version plus an in-image read of the script tree).

The redis field is observational only (issue #399): it never changes the status code, so a Redis outage does not pull the backend out of an orchestrator's rotation for a dependency the request path already fails open through. See core.readiness for the reasoning.

Return what this deployment is, and which notices it can show.

Return one notice document as text/plain.

Verbatim: a license text that has been reflowed, truncated or markdown-rendered is no longer the notice it is standing in for.