# QAuth documentation, full text

> QAuth is an open-source (Apache 2.0), self-hosted OAuth 2.1 and OpenID Connect authorization server for apps, services and AI agents. Agents act for a person through RFC 8693 token exchange with capped scope modes, step-up before dangerous operations and a per-agent audit trail; MCP servers get the MCP authorization profile (revision 2026-07-28), with @qauth-labs/resource-guard on the resource-server side; tokens can carry a hybrid ML-DSA-65 + Ed25519 signature behind a default-off switch. QAuth is ready for production; it stays below 1.0 only because features planned for 1.0 are not finished.

# QAuth

URL: https://docs.qauth.dev/

QAuth is an open-source, self-hostable OAuth 2.1 / OIDC authorization server whose near-term focus is authorization for MCP servers and AI agents.

<CardGrid>
  <LinkCard
    title="Integrating an app or MCP server"
    description="Add QAuth-issued tokens to your application or MCP server."
    href="/integrate/"
  />
  <LinkCard
    title="Self-hosting QAuth"
    description="Run and operate your own QAuth instance."
    href="/operate/"
  />
  <LinkCard
    title="Contributing to QAuth"
    description="Set up a development environment and work on QAuth itself."
    href="/extend/"
  />
  <LinkCard
    title="Using the developer portal"
    description="Manage clients and applications through the QAuth dashboard."
    href="/portal/"
  />
</CardGrid>

---

# Integrate

URL: https://docs.qauth.dev/integrate/

This lane is for developers adding QAuth-issued tokens to an application or MCP server.

---

# MCP Quickstart

URL: https://docs.qauth.dev/integrate/mcp-quickstart/

This guide takes you from nothing to a **working MCP authorization handshake** on
your machine:

1. Run **QAuth** — the OAuth 2.1 authorization server (AS).
2. Run a **guarded MCP resource server** — the bundled `memory-mcp` example,
   protected by [`@qauth-labs/resource-guard`](https://github.com/qauth-labs/qauth/blob/main/libs/sdk/resource-guard/README.md).
3. Obtain a valid, **audience-bound** access token and call the protected resource.

By the end you will have reproduced the flow from
[ADR-007](/reference/records/adr/007-mcp-first-positioning/): an MCP client, given only a server
URL, discovers the authorization server, registers, runs `authorization_code` +
PKCE, and calls the resource with a token QAuth minted and `resource-guard` validated.

```
  ┌──────────────┐        ┌───────────────────────┐        ┌─────────────────────┐
  │  MCP client  │        │  MCP resource server  │        │  QAuth  (AS)        │
  │ (Claude Code,│        │  memory-mcp +         │        │  :3000              │
  │  curl, …)    │        │  resource-guard :8088 │        │                     │
  └──────┬───────┘        └───────────┬───────────┘        └──────────┬──────────┘
         │  GET /mcp/memory (no token)│                               │
         │ ──────────────────────────▶│                               │
         │  401 WWW-Authenticate:     │                               │
         │  Bearer resource_metadata= │                               │
         │ ◀──────────────────────────│                               │
         │  GET /.well-known/oauth-protected-resource                 │
         │ ──────────────────────────▶│                               │
         │  { authorization_servers: ["http://localhost:3000"], … }   │
         │ ◀──────────────────────────│                               │
         │  discover AS, register, authorization_code + PKCE          │
         │ ───────────────────────────────────────────────────────-─▶│
         │  access_token (aud = http://localhost:8088, scope mcp:read)│
         │ ◀───────────────────────────────────────────────────────-─│
         │  GET /mcp/memory   Authorization: Bearer <token>           │
         │ ──────────────────────────▶│  (resource-guard checks sig,  │
         │  200 ✅                     │   iss, aud, scope)            │
         │ ◀──────────────────────────│                               │
```

> **Scope of the bundled example.** `memory-mcp` is a minimal Fastify server that
> demonstrates the **authorization** half — the 401 challenge, Protected Resource
> Metadata, and token validation. It exposes plain HTTP routes (`/mcp/memory`)
> rather than the full MCP JSON-RPC transport, so you verify it with `curl`. To
> drive it from a real MCP client, wrap your own MCP server with `resource-guard` the
> same way (see [Step 3](#step-3--connect-an-mcp-client)); the OAuth handshake is
> identical.

---

## Prerequisites

- **Docker** 23.0+ and **Docker Compose** 2.0+ (BuildKit on by default)
- **OpenSSL** (to generate the JWT signing key)
- **Node.js 20+** with `pnpm` and `tsx` (to run the example resource server)
- `curl` and `jq` for the walkthrough

---

## Step 1 — Run QAuth (the authorization server)

QAuth signs tokens with **EdDSA (Ed25519)**. Generate a key pair and point the
stack at it.

```bash
git clone https://github.com/qauth-labs/qauth.git
cd qauth

# 1. Generate the EdDSA signing key pair
openssl genpkey -algorithm Ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

# 2. Create your .env from the example
cp .env.docker.example .env
```

Edit `.env` and set the keys (include the `BEGIN/END` lines, wrapped in double
quotes) and the issuer:

```dotenv
DB_PASSWORD=change_me

JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
...contents of private.pem...
-----END PRIVATE KEY-----"

JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
...contents of public.pem...
-----END PUBLIC KEY-----"

JWT_ISSUER=http://localhost:3000

# Let dynamically-registered MCP clients request MCP scopes.
# The default allows only OIDC-core scopes (openid profile email offline_access),
# so an MCP client's `mcp:read`/`mcp:write` request would otherwise be denied.
DEFAULT_DYNAMIC_REGISTRATION_SCOPES=openid profile email offline_access mcp:read mcp:write
```

Start the stack (auth-server + PostgreSQL 18 + Redis 7 + migrations) and verify:

```bash
docker compose up -d
curl -s http://localhost:3000/ready | jq
```

```json
{
  "status": "ok",
  "roles": ["web", "api", "admin", "signer", "delivery"],
  "checks": {
    "database": { "status": "ok" },
    "redis": { "status": "ok" },
    "kek": { "status": "ok" },
    "outbox": { "status": "ok" }
  }
}
```

Confirm the discovery document advertises the endpoints an MCP client needs:

```bash
curl -s http://localhost:3000/.well-known/oauth-authorization-server | jq
```

```jsonc
{
  "issuer": "http://localhost:3000",
  "authorization_endpoint": "http://localhost:3000/oauth/authorize",
  "token_endpoint": "http://localhost:3000/oauth/token",
  "registration_endpoint": "http://localhost:3000/oauth/register",
  "jwks_uri": "http://localhost:3000/.well-known/jwks.json",
  "code_challenge_methods_supported": ["S256"],
  "resource_indicators_supported": true,
  "authorization_response_iss_parameter_supported": true, // RFC 9207 `iss` always emitted
  "client_id_metadata_document_supported": true, // CIMD on by default
}
```

> Interactive API docs (Swagger UI) are served at `http://localhost:3000/docs`.
> See the [Docker guide](/operate/docker/) for development mode, CIMD settings, and
> production considerations.

---

## Step 2 — Run a guarded MCP resource server

The repo ships a runnable example — a tiny in-memory store protected by
`resource-guard` in local-JWT validation mode (it verifies tokens against QAuth's
JWKS, no per-request call to the AS).

```bash
cd libs/sdk/resource-guard

QAUTH_ISSUER=http://localhost:3000 \
MCP_RESOURCE=http://localhost:8088 \
npx tsx examples/memory-mcp/server.ts
```

`MCP_RESOURCE` is this server's canonical URL — the `aud` value every accepted
token must carry (RFC 8707). In a separate shell, confirm the two unauthenticated
behaviours an MCP client relies on:

```bash
# Protected Resource Metadata (RFC 9728) — points clients at the AS:
curl -s http://localhost:8088/.well-known/oauth-protected-resource | jq
# → { "resource": "http://localhost:8088",
#     "authorization_servers": ["http://localhost:3000"], … }

# A protected call with no token → 401 + the Bearer challenge:
curl -i http://localhost:8088/mcp/memory
# → HTTP/1.1 401 Unauthorized
#   WWW-Authenticate: Bearer scope="mcp:read", resource_metadata="http://localhost:8088/.well-known/oauth-protected-resource"
```

This is the trigger that starts the whole handshake: a 401 with a pointer to the
metadata document and the scopes the operation needs, so a client can authorize
in one round instead of guessing.

---

## Step 3 — Connect an MCP client

### Option A — A real MCP client (e.g. Claude Code)

Wrap your **actual** MCP server with `resource-guard` exactly as the example does
(register the plugin, guard routes with `app.requireBearer` /
`app.requireScopes(...)`), then add it to your MCP client as an HTTP server:

```bash
# Exact syntax varies by client/version — check `claude mcp add --help`.
claude mcp add --transport http memory http://localhost:8088/mcp
```

On first use the client will:

1. call the server, get the **401** + `WWW-Authenticate` challenge,
2. fetch **Protected Resource Metadata** and discover QAuth,
3. **obtain a `client_id`** — via Client ID Metadata Documents (CIMD), or via
   Dynamic Client Registration if it does not support CIMD
   (see [below](#client-registration-cimd-vs-dcr)),
4. run **`authorization_code` + PKCE**, opening a browser for **login + consent**
   at QAuth (you'll register/sign in and approve the `mcp:read` / `mcp:write`
   scopes),
5. retry the call with the issued token — `resource-guard` validates it and returns `200`.

Because the client passes the resource URL as the RFC 8707 `resource` parameter,
the token's `aud` is bound to `http://localhost:8088` and is useless at any other
resource server.

A native client whose callback scheme has no period, such as the Cursor desktop
app (`cursor://anysphere.cursor-mcp/oauth/callback`), needs that scheme listed:
set `REDIRECT_URI_CUSTOM_SCHEMES=cursor` in `.env`. It is empty by default, and
PKCE is what protects the code at any custom scheme; see
[Redirect URI schemes for native apps](/operate/docker/#redirect-uri-schemes-for-native-apps).

### Option B — Verify the handshake with curl (no browser)

To prove the token half end-to-end without an interactive client, mint a
**`client_credentials`** (machine) token. This needs a client whose `scopes` and
`audience` are set explicitly, which the seed script provisions.

```bash
# The seed script targets an existing realm. The auth-server creates the
# default realm ("master", from DEFAULT_REALM_NAME) when it boots, so the stack
# from Step 1 already has it.
# Provision a machine client bound to the example's resource URL:
cat > /tmp/mcp-demo-clients.json <<'JSON'
{
  "realm": "master",
  "clients": [
    {
      "client_id": "memory-mcp-demo",
      "name": "memory-mcp demo (client_credentials)",
      "grant_types": ["client_credentials"],
      "scopes": ["mcp:read", "mcp:write"],
      "audience": ["http://localhost:8088"],
      "token_endpoint_auth_method": "client_secret_basic"
    }
  ]
}
JSON

# Seed it (prints the generated client_secret once — capture it):
DATABASE_URL="postgresql://qauth:${DB_PASSWORD}@localhost:5432/qauth" \
  pnpm nx run infra-db:db:seed-oauth-clients -- --manifest=/tmp/mcp-demo-clients.json
```

Exchange the credentials for an audience-bound token, then call the resource:

```bash
CLIENT_ID=memory-mcp-demo
CLIENT_SECRET=<paste the secret printed above>

ACCESS_TOKEN=$(curl -s -X POST http://localhost:3000/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'scope=mcp:read' \
  -d 'resource=http://localhost:8088' | jq -r .access_token)

# Call the protected resource — resource-guard verifies signature, issuer, aud, scope:
curl -s http://localhost:8088/mcp/memory \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq
# → { "subject": "memory-mcp-demo", "client": "memory-mcp-demo", "items": {} }  ✅
```

A token carrying only `mcp:read` against the write route returns a **step-up**
challenge — exactly what drives incremental consent in a real client:

```bash
curl -i -X PUT http://localhost:8088/mcp/memory/greeting \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' -d '{"value":"hi"}'
# → HTTP/1.1 403 Forbidden
#   WWW-Authenticate: Bearer error="insufficient_scope", scope="mcp:read mcp:write",
#                     resource_metadata="http://localhost:8088/.well-known/oauth-protected-resource"
```

(Request `scope=mcp:read mcp:write` at the token endpoint to get a token that
satisfies both routes.)

---

## Client registration: CIMD vs DCR

QAuth supports two ways for an MCP client to obtain a `client_id`. Both are
advertised in discovery, but they are not co-equal: MCP Authorization
2026-07-28 says authorization servers and clients **SHOULD** support CIMD, and
**deprecates** RFC 7591 Dynamic Client Registration — retained only for
backwards compatibility with parties that do not support CIMD. QAuth keeps DCR
working (it is what makes the local walkthrough above practical), but prefer
CIMD for anything you deploy.

| Mechanism                                                                          | When QAuth uses it                                                | Best for                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CIMD** — Client ID Metadata Documents (MCP 2026-07-28, **preferred**)            | `client_id` is an **HTTPS URL** resolving to a metadata document  | Production clients with a stable, public metadata URL. A row IS persisted, but idempotently — keyed by the (validated) URL, so re-resolving updates one row instead of creating new ones; there is no record to spam. It is not manageable from the developer portal, by design ([ADR-012](/reference/records/adr/012-dynamic-client-ownership/)): edit the metadata document instead. |
| **DCR** — Dynamic Client Registration (RFC 7591, **deprecated** by MCP 2026-07-28) | `POST /oauth/register`, **open mode** (no `initial_access_token`) | Local development and clients without a public URL. Scopes are **capped to the realm allowlist** (`DEFAULT_DYNAMIC_REGISTRATION_SCOPES`) — this is why Step 1 adds `mcp:read mcp:write`.                                                                                                                                                                                               |

- **CIMD** is on by default: `CIMD_ENABLED=true` seeds it on for each new
  realm, and from then on the realm's own `registration.cimd` policy decides
  ([Changing a realm's CIMD policy](/operate/docker/#changing-a-realms-cimd-policy)).
  It requires the client's
  `client_id` URL to be fetchable over HTTPS; the AS validates it (URL ==
  `client_id`, redirect-URI checks, SSRF guards, size/TTL limits). A document
  may declare portless loopback redirects such as `http://127.0.0.1/callback`
  (Claude Code does); the client's ephemeral port is accepted at authorization
  time ([Redirect URI matching](/integrate/oauth-flow/#redirect-uri-matching)).
  Its `redirect_uris` get the check DCR applies, and like DCR QAuth refuses the
  whole document if one of them fails it (for example an `http://` URI on a
  host that is not loopback, or one with a fragment): the client does not
  resolve, so every request for it gets `invalid_client`. A CIMD client starts
  with no scopes; the operator grants them in the seed manifest's
  `cimd_clients` section
  ([Granting scopes to a CIMD client](/operate/docker/#granting-scopes-to-a-cimd-client)).
  A document may declare `client_credentials` too, but that grant issues the
  client no token until its entry lists, in `client_credentials_scopes`, the
  scopes it may get without a user.
  For purely local testing over `http://localhost`, CIMD is impractical — use DCR.
  MCP 2026-07-28 still cites `draft-ietf-oauth-client-id-metadata-document-00`;
  the IETF draft has since reached **-02** (6 July 2026), and QAuth's
  implementation already satisfies its added hardening (HTTPS-only fetches with
  no redirect following, HTTP 200 required, and simple string comparison of the
  document's `client_id` against the requested one).
- **DCR** open mode is rate-limited per IP (30 requests per 60-second window by
  default — `REGISTER_CLIENT_RATE_LIMIT` / `REGISTER_CLIENT_RATE_WINDOW`).
  Tighten or gate it for any internet-facing deployment. See
  [ADR-007 §1](/reference/records/adr/007-mcp-first-positioning/) and the
  [Docker guide CIMD section](/operate/docker/#client-id-metadata-documents-cimd).

---

## How tokens stay scoped to one resource

The no-passthrough guarantee rests on **audience binding** (RFC 8707):

- The client sends `resource=<MCP server URL>` on authorize/token requests.
- QAuth mints the access token with `aud` set to that resource and refuses to
  widen it on refresh.
- `resource-guard` rejects any token whose `aud` does not include its own `resource`,
  and never forwards the inbound token upstream.

A token minted for resource A therefore cannot be replayed against resource B,
even if both trust the same QAuth instance.

`resource-guard` also refuses a sender-constrained token, one bound to a key by
`cnf`, such as the DPoP-bound tokens QAuth issues with `DPOP_ENABLED=true`. It
answers `401 invalid_token`, because this version verifies no DPoP proof, and it
does not accept the `DPoP` authorization scheme. A client that calls it uses an
unbound token: it sends no `DPoP` proof to the token endpoint. The tokens of a
client marked `dpop_bound_access_tokens`, a token exchanged from a DPoP-bound
subject token, and an access token issued for a `cnf`-bound ID-JAG are always
bound, so they cannot be used with `resource-guard` until it verifies DPoP
proofs.

---

## Troubleshooting

| Symptom                           | Likely cause / fix                                                                                                                                                                                               |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` even with a token           | Token `aud` ≠ the server's `MCP_RESOURCE`. Ensure the `resource` you requested matches `MCP_RESOURCE` exactly.                                                                                                   |
| `invalid_scope` at `/oauth/token` | The client's `scopes` (machine client) or the realm allowlist (DCR client) doesn't include the requested scope. Re-check Step 1's `DEFAULT_DYNAMIC_REGISTRATION_SCOPES` or the seeded client's `scopes`.         |
| `unsupported scheme: cursor:`     | The client calls back on a scheme without a period. List it in `REDIRECT_URI_CUSTOM_SCHEMES` (here `cursor`); see [Redirect URI schemes for native apps](/operate/docker/#redirect-uri-schemes-for-native-apps). |
| Seed script: realm not found      | The auth-server has not booted against this database yet, or the manifest's `realm` is not `DEFAULT_REALM_NAME`. Start the stack (Step 1) and check its log for the `default realm ready` line.                  |
| `resource-guard` can't fetch JWKS | `QAUTH_ISSUER` must be reachable from the resource server and serve `/.well-known/jwks.json`.                                                                                                                    |
| Port already in use               | Override `PORT` for the example, or remap `3000`/`5432`/`6379` in `docker-compose.yml`.                                                                                                                          |

---

## Next steps

- [OAuth 2.1 Flow](/integrate/oauth-flow/) — the `authorization_code` + PKCE flow in
  detail, with copy-paste `curl` for every step (build your own client).
- [Hosted UI](/integrate/hosted-ui/) — the login, consent, and resume screens an
  end user actually sees during that flow.
- [Agent Authorization](/integrate/agent-authorization/) — when an **AI agent** acts on
  behalf of a user: the `is_agent` client type, RFC 8693 token-exchange
  delegation, agent scope modes, and step-up before dangerous operations.
- [`@qauth-labs/resource-guard` README](https://github.com/qauth-labs/qauth/blob/main/libs/sdk/resource-guard/README.md) —
  full configuration, `introspection` mode, and the framework-agnostic core.
- [ADR-007: MCP-First Positioning](/reference/records/adr/007-mcp-first-positioning/) — why this
  is QAuth's near-term product identity.
- [Docker guide](/operate/docker/) — development mode, CIMD configuration, production.

---

# OAuth 2.1 Flow

URL: https://docs.qauth.dev/integrate/oauth-flow/

This page documents QAuth's OAuth 2.1 / OIDC endpoints with copy-paste `curl`
for every step, so you can implement a client by hand. If your goal is to wire
QAuth to an **MCP server**, start with the [MCP Quickstart](/integrate/mcp-quickstart/) —
this page is the lower-level reference it builds on.

**Conventions used below**

- Base URL / issuer: `http://localhost:3000` (your `JWT_ISSUER`).
- Tokens are **EdDSA (Ed25519)** signed JWTs; verify them against
  `GET /.well-known/jwks.json`.
- PKCE is **required** and only `S256` is supported.
- Request bodies to `/oauth/token` and `/oauth/introspect` are
  `application/x-www-form-urlencoded` (RFC 6749 §3.2, RFC 7662 §2.1).

Standards: RFC 6749 (OAuth 2.0) · OAuth 2.1 draft · RFC 7636 (PKCE) · RFC 8707
(Resource Indicators) · RFC 7662 (Introspection) · RFC 8414 (AS Metadata) ·
OIDC Core / Discovery 1.0 · RFC 9700 (OAuth 2.0 Security BCP).

---

## Endpoints at a glance

| Endpoint                                  | Method | Purpose                                      |
| ----------------------------------------- | ------ | -------------------------------------------- |
| `/.well-known/oauth-authorization-server` | GET    | AS metadata (RFC 8414)                       |
| `/.well-known/openid-configuration`       | GET    | OIDC discovery (superset)                    |
| `/.well-known/jwks.json`                  | GET    | Public signing keys (RFC 7517)               |
| `/oauth/authorize`                        | GET    | Start `authorization_code` + PKCE (browser)  |
| `/oauth/token`                            | POST   | Exchange code / refresh / client credentials |
| `/oauth/introspect`                       | POST   | Token introspection (RFC 7662)               |
| `/oauth/userinfo`                         | GET    | OIDC UserInfo (Bearer)                       |
| `/oauth/register`                         | POST   | Dynamic Client Registration (RFC 7591, open) |
| `/oauth/revoke`                           | POST   | Token revocation (RFC 7009)                  |
| `/oauth/end-session`                      | GET    | RP-initiated logout (browser)                |

Discover these programmatically instead of hard-coding paths:

```bash
curl -s http://localhost:3000/.well-known/oauth-authorization-server | jq
```

---

## Grant types

| Grant                                             | Subject (`sub`) | Refresh token?                           | Use case                                                |
| ------------------------------------------------- | --------------- | ---------------------------------------- | ------------------------------------------------------- |
| `authorization_code` (+ PKCE)                     | the end user    | `refresh_token` grant + stored consent ¹ | Apps acting **on behalf of a user**                     |
| `refresh_token`                                   | the end user    | yes (rotated)                            | Renew an access token without re-prompting              |
| `client_credentials`                              | the `client_id` | no (RFC 6749 §4.4.3)                     | **Machine-to-machine**, no user                         |
| `urn:ietf:params:oauth:grant-type:token-exchange` | the end user    | no                                       | **Agent delegation** on behalf of a user (RFC 8693)     |
| `urn:ietf:params:oauth:grant-type:jwt-bearer`     | the end user    | no                                       | **ID-JAG** — enterprise-managed authorization (ADR-011) |

¹ Only to a client whose `grant_types` list `refresh_token`, and only under
a stored consent that covers the grant (see the
[token response](#3-exchange-the-code-for-tokens)).

`response_type` is `code` only. There is no implicit or password grant
(removed in OAuth 2.1).

The `jwt-bearer` grant is **off by default** (`ID_JAG_ENABLED=false`) and is
advertised in `grant_types_supported` only while it is on **and**
`ID_JAG_TRUSTED_ISSUERS` is not empty. With the flag off the token endpoint
answers `unsupported_grant_type`, and with an empty allowlist it rejects every
assertion, so advertising the grant would be a false capability claim. See [ID-JAG](#id-jag--enterprise-managed-authorization-adr-011).

---

## Authorization Code + PKCE (user context)

### 0. Prerequisites — a client

You need a registered client with the `authorization_code` grant, a registered
`redirect_uri`, and the scopes you want in its allowlist. A **public** client
(SPA / native / CLI) uses `token_endpoint_auth_method: none` and authenticates
purely with PKCE — no secret. Register one with
[Dynamic Client Registration](#dynamic-client-registration-rfc-7591):

```bash
curl -s -X POST http://localhost:3000/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "My App",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "redirect_uris": ["http://localhost:5173/callback"],
    "token_endpoint_auth_method": "none"
  }' | jq
# → { "client_id": "…", "token_endpoint_auth_method": "none", … }
```

> **Scopes are deny-by-default.** The authorize endpoint only grants scopes that
> are in the client's allowlist. DCR-registered clients are capped to the realm
> allowlist, which `DEFAULT_DYNAMIC_REGISTRATION_SCOPES` seeds when the realm is
> created; set that env var before the first boot to include any non-OIDC scopes
> (e.g. `mcp:read`) you intend to request. An existing realm keeps its own list.

### 1. Generate a PKCE verifier and challenge (RFC 7636)

```bash
# code_verifier: 43–128 chars from [A-Za-z0-9._~-]
code_verifier=$(openssl rand -base64 96 | tr -d '\n=+/' | cut -c1-64)

# code_challenge = BASE64URL(SHA256(code_verifier))
code_challenge=$(printf '%s' "$code_verifier" \
  | openssl dgst -binary -sha256 \
  | openssl base64 | tr '+/' '-_' | tr -d '=\n')

echo "verifier=$code_verifier"
echo "challenge=$code_challenge"
```

Keep `code_verifier` secret and in memory; you'll send it at the token step.

### 2. Redirect the user to `/oauth/authorize`

Open this URL **in a browser** (the user authenticates and consents at QAuth):

```
http://localhost:3000/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=http://localhost:5173/callback
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &scope=openid%20profile%20email
  &state=RANDOM_OPAQUE_VALUE
  &resource=http://localhost:8088
```

| Parameter               | Required    | Notes                                                                     |
| ----------------------- | ----------- | ------------------------------------------------------------------------- |
| `response_type`         | yes         | Must be `code`.                                                           |
| `client_id`             | yes         | Your client. At most 2048 printable ASCII characters.                     |
| `redirect_uri`          | yes         | Must match a registered URI — see below.                                  |
| `code_challenge`        | yes         | From step 1.                                                              |
| `code_challenge_method` | yes         | Must be `S256`.                                                           |
| `scope`                 | no          | Space-separated; filtered to the client's allowlist.                      |
| `state`                 | recommended | Opaque CSRF value; echoed back verbatim.                                  |
| `nonce`                 | OIDC        | Bound into the ID token when issued.                                      |
| `resource`              | no          | RFC 8707 target(s); binds the token `aud`. Repeat for multiple, up to 10. |
| `login_hint`            | no          | At most 254 bytes in UTF-8; pre-fills an interaction's sign-in.           |
| `prompt`                | no          | `none`, `login`, `consent`, or `create` to register. See below.           |
| `qauth_upstream`        | no          | An upstream provider's type; starts the sign-in there. See below.         |
| `qauth_link`            | no          | An upstream provider's type; links an account of it. See below.           |

`redirect_uri` and each `resource` are absolute URIs of at most 2048
characters, written in ASCII as RFC 3986 requires: an internationalised host in
its `xn--` form, any other non-ASCII character percent-encoded. A raw Unicode
character or a space is refused with `400`.

#### Routing to an upstream provider

`qauth_upstream=<type>` names one of the realm's upstream identity providers,
such as `oidc_corp` for a generic OpenID Connect provider, a hidden one
included. When the request needs a sign-in, the browser goes straight to that
provider instead of the first sign-in step; after the provider's callback the
request goes on as any sign-in does, to the consent or the code. A value that
names no provider the realm has on is ignored, as the parameter is when no
sign-in is needed (a live session that satisfies the request, or
`prompt=none`). At most 64 characters; QAuth-defined, so other authorization
servers ignore it.

#### Linking an upstream account

`qauth_link=<type>` links an account of one of the realm's upstream identity
providers to the person's QAuth account (#670), as the account console's
"Link an account" does. The browser goes to that provider first, then the
person signs in to their QAuth account again, under its MFA policy, whatever
session the browser already has: a session never links an account on its own
(NIST SP 800-63C-4 §5.4). That sign-in takes the account's own factors, or
another of the realm's providers whose identity the account already holds,
never the provider being linked (#1080). The identity joins the account
that sign-in proved, and the request goes on to the consent or the code as
after any sign-in. An identity another account already holds is refused on a
QAuth page, as is a second identity of the same provider; nothing reaches your
`redirect_uri` then.

The parameter is honoured only for a client the operator flagged first-party
(ADR-017 Decision 2), while the Interaction API is on (`INTERACTION_UI_ENABLED`),
and only for a provider the realm has on, hidden or not; otherwise it is
ignored. It takes precedence over `qauth_upstream`. At most 64 characters;
QAuth-defined. The account API lists the linked accounts and unlinks one
([`/account/v1-rc.0/linked-accounts`](/integrate/api-reference/#get-accountv1-rc0linked-accounts)).

#### Registration: `prompt=create`

`prompt=create` ([OpenID Connect Prompt Create 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html))
sends the person to register a new password account instead of signing in.
Discovery lists `create` in `prompt_values_supported` only while the realm
allows sign-up. The request is refused, by a redirect to your `redirect_uri`
with `state` and `iss`, when:

| Cause                                                           | `error`               |
| --------------------------------------------------------------- | --------------------- |
| `scope` does not hold `openid`                                  | `invalid_request`     |
| the realm does not allow sign-up, or the Interaction API is off | `invalid_request`     |
| your client's `hosted_flows` do not name `register`             | `unauthorized_client` |
| the request carries `max_age`: a registration signs nobody in   | `invalid_request`     |

A client that registered itself gets these errors on a QAuth page instead of a
redirect, as it gets every error before a sign-in. Which clients may register,
and how the realm turns sign-up on, is the operator's choice:
[Clients that may start a registration](/operate/docker/#clients-that-may-start-a-registration-hosted_flows).

The registration asks for the address first, then for an 8-digit code mailed
to it, then for a new password that meets the realm's password policy. The
screens are the same whether or not an account already holds the address:
only the mail differs, and an address that has an account gets help to sign in
to it instead. The account is created once the code and the password pass. The
consent screen follows as for a sign-in, and the client gets its code.

A registration is not a sign-in: QAuth starts no browser session, and the ID
token carries no `auth_time` and no `amr`. A request for a dangerous scope asks
the person to sign in first. A browser that is already signed in can still
register a new account, and its session stays as it was. `qauth_upstream` and
`qauth_link` are ignored with `prompt=create`.

#### Password reset

With the Interaction API on (`INTERACTION_UI_ENABLED`), the password step of a
sign-in offers a reset beside the password, to every client the realm serves.
It asks for an 8-digit code mailed to the address, then for a new password that
meets the realm's password policy. The screens are the same for every address:
only an account with a password and a verified address gets the code. A
disabled account gets no mail and no change, and neither does an account whose
address was never verified, until such an account is replaced at the first
proof of its mailbox
([#641](https://github.com/qauth-labs/qauth/issues/641)). An account that also
holds a passkey or another
authenticator must prove it before the new password; until those steps are
served on these pages, such a reset ends as an expired interaction and changes
nothing.

A reset ends everything the old password opened: every refresh token of the
user is revoked, every authorization code not yet exchanged is invalidated,
every browser session and every sign-in in progress that began before it is
ended, and the owner is mailed that the password changed. A session that began
within a second after the reset is ended too: that margin covers the clocks of
two server nodes.
Like a registration, a reset is not a sign-in: QAuth starts no browser
session, and the ID token carries no `auth_time` and no `amr`. A request that
asks for a fresh sign-in, with `prompt=login` or `max_age`, offers no reset.

#### Redirect URI matching

`redirect_uri` is compared with the client's registered set (or, for a
[CIMD](/integrate/mcp-quickstart/) client, the document's `redirect_uris`) by
**exact string** — no wildcards, no prefix matching, no normalisation
(RFC 9700 §2.1). There is one exception, required by RFC 8252 §7.3 for native
apps: a **loopback** redirect may carry **any port**.

- Loopback means the `http` scheme and a host of `127.0.0.0/8`, `[::1]` or
  `localhost`. A native / CLI client can register `http://127.0.0.1/callback`
  (no port) and call back on whatever port the OS gave its listener, e.g.
  `redirect_uri=http://127.0.0.1:53817/callback`.
- Only the port may differ. Scheme, host, path and query must still match
  byte for byte, and the host literals are not interchangeable
  (`localhost` ≠ `127.0.0.1` ≠ `[::1]`) — register each one you use.
- `localhost` is accepted because real clients (Claude Code among them) use
  it, but RFC 8252 §8.3 recommends the IP literal: prefer `127.0.0.1` or
  `[::1]` for clients you write.
- `https` and custom-scheme redirects, reverse-domain or listed in
  `REDIRECT_URI_CUSTOM_SCHEMES`, always need an exact match, port included.
- QAuth redirects to the port you **requested** and binds the code to that
  exact URI, so the token request must repeat it verbatim — port included
  (RFC 6749 §4.1.3).
- PKCE (mandatory for every client) is what keeps another listener on the
  same host from redeeming an intercepted code (RFC 8252 §8.1).

QAuth flow: if there's no active session it shows the **login** page; then a
**consent** screen for the requested scopes, naming each requested `resource`
as the audience (skipped if a prior consent already covers those scopes for
every requested `resource`). See [Hosted UI](/integrate/hosted-ui/) for what
those screens look like and the pending-authorization mechanics behind the
login bounce. On approval it redirects:

```
http://localhost:5173/callback?code=AUTH_CODE&state=RANDOM_OPAQUE_VALUE
```

Verify `state` matches what you sent before proceeding.

### 3. Exchange the code for tokens

```bash
curl -s -X POST http://localhost:3000/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=http://localhost:5173/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d code_verifier=$code_verifier \
  -d resource=http://localhost:8088 | jq
```

```json
{
  "access_token": "eyJ…",
  "refresh_token": "a1b2…(64 hex)",
  "id_token": "eyJ…", // present because the request above granted `openid`
  "expires_in": 900,
  "token_type": "Bearer",
  "scope": "openid profile email"
}
```

`id_token` is present **only** when the granted scope includes `openid` on the
`authorization_code` path (OIDC Core §3.1.3.3) — as in this example. Drop `openid`
from `scope` and the member is absent entirely.

Notes:

- **Confidential** clients additionally authenticate, either with HTTP Basic
  (`-u "CLIENT_ID:CLIENT_SECRET"`, `client_secret_basic`) or by adding
  `-d client_secret=…` (`client_secret_post`). Public clients send neither.
- The authorization code is single-use and short-lived; the same
  `redirect_uri` (exactly as sent to `/oauth/authorize`, loopback port
  included) and a PKCE-matching `code_verifier` are mandatory. A missing
  `redirect_uri` is `invalid_grant`, like a different one, with the
  `error_description` `redirect_uri is required for this code`: QAuth keeps
  RFC 6749's rule for codes from a browser redirect, although OAuth 2.1 drops
  the parameter. The code is not spent, so send the request again with it.
- **Redeem a code once.** A second redemption is refused with `invalid_grant`
  and, when it is otherwise a valid request (your client, the same
  `redirect_uri`, the right `code_verifier`, DPoP key and `resource`), revokes
  every token the first one led to (OAuth 2.1 §4.1.3): the refresh tokens of
  its family, and every access token issued from the code or in that family,
  which userinfo, introspection and token exchange then refuse. QAuth cannot
  tell a retry from an attacker who copied the code. So do not retry a token
  request that may have reached the server; send the user through
  `/oauth/authorize` again instead. A code is recognised as spent until the
  hourly purge deletes it, some time after its five-minute lifetime.
- `resource` here must be a **subset** of the resource set bound at authorize
  time, or you get `invalid_target`. Omit it to inherit the code's binding.
- **`refresh_token` is present only when your client's `grant_types` list
  `refresh_token` and the user has a stored consent** for your client that
  covers the granted scopes at every `resource` the token is bound to — the
  row they can review and revoke under `/consents`. A client registered for
  `authorization_code` alone gets no refresh token, however its consent was
  given: the `refresh_token` grant would refuse it with `unauthorized_client`.
  A consent remembered for one resource server does not cover another. If they
  untick **Remember this decision** on the consent screen, the approval is
  one-time: the member is absent, and you send them through `/oauth/authorize`
  again once the access token expires. Requesting `offline_access` does not
  change this either way: the grant and the consent decide.
- **`id_token` is issued only for this grant** (`authorization_code`), and
  only when the granted scope includes `openid`. It is a separate,
  **client-audienced** EdDSA JWT (`aud` = your `client_id`, not the resource
  `aud` the access token carries) asserting the sign-in event — see
  [ID token claims](#id-token-claims-oidc) below. `client_credentials` has no
  end user and never carries one; `refresh_token` does **not** reissue one
  either (see [Refresh Token](#refresh-token-rotation)).

### ID token claims (OIDC)

Beyond the standard `iss` / `sub` / `aud` / `exp` / `iat`, `id_token` carries
(all via `signIdToken`, `libs/server/jwt/src/lib/jwt-service.ts:176-226`):

| Claim            | Present when                                                                                                                                                                      |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nonce`          | The authorize request sent one (OIDC Core §3.1.3.6) — echoed back unmodified.                                                                                                     |
| `auth_time`      | A sign-in backs the code: the session's real authentication time, epoch seconds. Not after a registration or a reset.                                                             |
| `amr`            | A sign-in backs the code and stored its methods: RFC 8176 values, `["pwd"]` for a password. Not after a registration or a reset, nor for a session from before QAuth stored them. |
| `sid`            | A browser session backs the code: its session id, the value the session cookie names.                                                                                             |
| `name`           | The granted scope includes `profile` **and** the user has a `firstName` and/or `lastName` set.                                                                                    |
| `email`          | The granted scope includes `email` **and** a verified email attribute exists.                                                                                                     |
| `email_verified` | Same condition as `email`; always `true` when present.                                                                                                                            |

`sid` names the browser session the user signed in with on the auth server,
and is what back-channel logout will name when that session ends (ADR-019
Decisions 3 and 4). A code from the headless Bearer hand-off of
`/oauth/authorize` has no browser session, so its ID token has no `sid`. A
sign-out spends the codes minted under the session that are not yet redeemed.
The access token, the introspection response and the refresh token never
carry `sid`, and discovery does not advertise it yet.

`email`/`email_verified` share the same trust-ordered resolution the access
token and [UserInfo](#userinfo-oidc) use, so all three never disagree within
one issuance. `name` follows the rule UserInfo applies (OIDC Core §5.4), so a
client that asks only for `openid` gets no `name` from either.

The **access token** follows the same `email` rule on every grant
(`authorization_code`, `refresh_token`, token exchange, `jwt-bearer`): it
carries `email`/`email_verified` only when its own `scope` includes `email`
and a verified address exists. A resource server that needs the address has
the client request `email`, which puts it on the consent screen. A refresh or
an exchange that narrows `email` out of the scope drops the claims, and
`client_credentials` and the first-party `/auth/login` token never carry them.

The access token of the code flow also carries the ID token's `auth_time` and
`amr`, and every refresh of its family keeps them as they were (RFC 9068
§2.2.1): they say when and how the user signed in, not when the token was
issued, so a resource server can require a recent sign-in or a given method.
Discovery lists both in `claims_supported`. The tokens of the other grants
carry neither.

### 4. Call a protected resource

```bash
curl -s http://localhost:8088/mcp/memory \
  -H "Authorization: Bearer ACCESS_TOKEN" | jq
```

A resource server (e.g. one using [`resource-guard`](https://github.com/qauth-labs/qauth/blob/main/libs/sdk/resource-guard/README.md))
verifies the signature against the JWKS and checks `iss`, `exp`, `aud`, and scope.
`resource-guard` refuses a DPoP-bound token (one carrying `cnf`), because it
verifies no DPoP proof yet.

### Caching the JWKS

Every token names the key that signed it in `kid` (a hybrid token names its
ML-DSA-65 key in `pqc_kid` too). A realm's JWKS lists every key that signs or
may still verify: its active keys, a next key before it starts signing, and a
retired key until its retention ends. A relying party or resource server that
verifies tokens locally follows three rules:

- **Cache the JWKS for at most 5 minutes.** `/.well-known/jwks.json` answers
  `Cache-Control: public, max-age=300`.
- **Fetch it again when a token names a `kid` the cached set lacks, at most
  once a minute.** A token whose `kid` is still unknown after that fetch is
  refused, not retried.
- **Drop every key the JWKS no longer lists.** A key leaves the JWKS when its
  retention ends, or when it is retired as compromised; a token it signed must
  stop verifying then. A compromised key is not gone everywhere at once: QAuth's
  own servers stop using it within their 60-second key refresh, and your JWKS
  cache adds its own lifetime before your verifier stops.

Pick the key by `kid` and `alg` together, never by `kid` alone: the JWKS of a
realm with hybrid signing holds an `OKP` and an `AKP` key, and retired keys sit
beside active ones. `resource-guard` follows these rules with its default
`jwksCacheTtlMs` of 5 minutes, which is also the least time between two
fetches.

A rotation through QAuth's key store then changes nothing for users or relying
parties: the new key is in the JWKS before it signs, and the old one stays in it, and keeps verifying at
QAuth's own endpoints, until its retention ends ([Keys](/operate/keys/)). That
holds only once rotation through the key store ships (#542 and #544). Until
then a signing key is replaced through its variable, which is not a rotation:
the new key is published only as it starts signing, and the old key leaves the
JWKS at once, so the tokens it signed stop verifying
([Replacing a signing key](/operate/keys/#replacing-a-signing-key)).

---

## Refresh Token (rotation)

Renew an access token without re-prompting the user. QAuth **rotates** the
refresh token on every use and detects replay (RFC 9700 §2.2.2): reusing a
already-rotated token revokes the entire token family, and the access tokens
issued in it. That holds for as long
as the family has a live token: the hourly `purge-expired` job deletes a family
only once its newest token has expired, rotated tokens included.

```bash
curl -s -X POST http://localhost:3000/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=refresh_token \
  -d refresh_token=CURRENT_REFRESH_TOKEN \
  -d client_id=YOUR_CLIENT_ID | jq
```

- Only a client whose `grant_types` list `refresh_token` may refresh; any
  other gets `unauthorized_client`, and the code exchange gives it no
  refresh token in the first place.
- The response contains a **new** `refresh_token` — store it and discard the old.
- Each new refresh token is good for the realm's refresh token lifetime
  (`tokens.refreshTokenLifespanSeconds`, a week by default) from the refresh.
  When the realm sets `sso_max_lifespan`, the family also ends that long after
  it starts. A family starts at the code exchange or at `POST /auth/login`. A
  family started by a code exchange also ends no later than the user's browser
  session that the authorization ran in. No token of the family expires later,
  and a refresh at or after that point fails with `invalid_grant` and revokes
  the whole family. Send the user through `/oauth/authorize` again. A silent
  `prompt=none` authorization just before the session ends gives a family that
  ends with the session.
- A **browser-based client** gets no more time on a refresh, whatever the realm
  sets (RFC 10017 §6.3.2.3, OAuth 2.1 §9.3.2): for a public client with an
  `https` redirect URI, each new refresh token expires when the one it replaces
  does, so the whole family ends when its first token expires, a week after the
  code exchange by default. A refresh then fails with `invalid_grant`; send the
  user through `/oauth/authorize` again, silently with `prompt=none` while the
  browser session lasts. Confidential clients and native apps, whose every
  redirect URI is a loopback (`http://127.0.0.1/…`) or private-use scheme
  (`com.example.app:/…`) one, keep the expiry that slides with each refresh. A
  native app that calls back on a claimed `https` URI is treated as
  browser-based, since the server cannot tell that URI from a web page's.
- `scope` may be passed to **down-scope** only; requesting a scope not in the
  original set returns `invalid_scope`. Omit it to keep the original scopes.
- The refreshed scopes must still be allowed for the client. If a scope was
  removed from the client (or above its `max_agent_mode`) since the grant, the
  refresh fails with `invalid_scope` and the refresh token is left unspent:
  send a narrower `scope` to continue.
- `resource` may **narrow** the audience but never widen it beyond the set bound
  to the refresh token.
- Confidential clients authenticate as in step 3; public clients send only
  `client_id` (ownership is enforced by refresh-token binding).
- **No `id_token` is issued on refresh**, even when the original grant
  included `openid` — only the `authorization_code` grant mints one. If your
  client needs a fresh ID token, re-run the authorization flow.

---

## Client Credentials (machine-to-machine)

No user, no browser. The token's `sub` is the `client_id` and no refresh token
is issued.

```bash
curl -s -X POST http://localhost:3000/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d scope=mcp:read \
  -d resource=http://localhost:8088 | jq
```

- The client must have the `client_credentials` grant and the requested scopes
  in its `scopes` allowlist. **At least one scope is required** (a scopeless
  machine token is rejected per RFC 9700).
- A client that also signs users in can have its `client_credentials` grant
  narrowed by the operator to the scopes it needs as itself
  (`client_credentials_scopes` in the seed manifest): a scope outside that list
  is refused with `invalid_scope` even though the client holds it, so the
  scopes its users grant it never reach a token that names no user. A client
  without the list may request any scope of `scopes`, except a CIMD client,
  whose document chose the grant: it gets no `client_credentials` token until
  the operator lists the scopes in its `cimd_clients` entry
  ([Tokens a CIMD client gets as itself](/operate/docker/#tokens-a-cimd-client-gets-as-itself)).
  See [SSF transmitter](/operate/ssf-transmitter/#register-a-receiver).
- `resource` must fall within the client's configured `audience` (or defaults to
  the `client_id`); it sets the token `aud`.
- An audience in the reserved `urn:qauth:aud:` namespace, such as the developer
  API's `urn:qauth:aud:developer:v1-rc.0`, is issued only to a client whose
  `audience` lists it, on every grant; any other client gets `invalid_target`.
  See [API conventions](/reference/api-conventions/#issuing-a-family-audience).
- Provision such clients with the seed script (it lets you set `scopes` and
  `audience` explicitly) — see the
  [MCP Quickstart, Option B](/integrate/mcp-quickstart/#option-b--verify-the-handshake-with-curl-no-browser).

---

## Token Exchange — agent on-behalf-of delegation (RFC 8693)

> ADR-007 §2 / agent-native authorization. On-behalf-of delegation is an MCP
> auth **extension** ([ext-auth](https://github.com/modelcontextprotocol/ext-auth)),
> not core MCP — QAuth provides it as a value-add. This section is the wire-level
> reference; for the end-to-end agent story (registering an agent, scope modes,
> step-up, and audit) see the [Agent Authorization guide](/integrate/agent-authorization/).

An **agent** client exchanges a user's access token (`subject_token`) for a
delegated access token whose `sub` is the user and whose `act` (actor) claim
identifies the agent. Chained delegation nests `act` (RFC 8693 §4.1).

```bash
curl -s -X POST http://localhost:3000/oauth/token \
  -u "AGENT_CLIENT_ID:AGENT_CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token=USERS_ACCESS_TOKEN \
  -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d 'scope=read:docs' | jq
```

Response (`issued_token_type` is required by RFC 8693 §2.2.1):

```jsonc
{
  "access_token": "eyJ…", // sub = user, act = { "sub": "AGENT_CLIENT_ID" }
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "read:docs",
}
```

Rules and guarantees:

- **Agent-only, default-deny.** Only clients classified as agents
  (`is_agent: true`) **and** granted the token-exchange grant type may use it.
  Because `is_agent` is self-asserted, the server never trusts it alone.
- **Confidential clients only.** The token-exchange grant requires confidential
  client authentication (`client_secret_basic` / `client_secret_post`); a public
  agent (`token_endpoint_auth_method=none`) is rejected with `invalid_client`.
- **Subject token must be bound to the agent.** The `subject_token` must be a
  QAuth-issued **access token** (verified EdDSA signature + `exp`, matching
  issuer, and an `access`-use marker — ID tokens and other JWTs are rejected
  with `invalid_request`) **and** its `aud` must contain the requesting agent's
  `client_id` — i.e. the token was minted for this agent. Together with the
  confidential-client requirement, this prevents an attacker from minting a
  delegated token from any captured user token plus a known agent `client_id`.
  The subject user must also exist and be enabled.
- **Down-scoping only.** `scope` must be a subset of the subject token's scope
  (else `invalid_scope`); omit it to inherit the full set. `resource` /
  `audience` must fall within the subject token's `aud` (else `invalid_target`).
  Scope and audience are preserved or narrowed — **never widened**.
- **Lifetime never exceeds the subject token.** The delegated token's
  `expires_in` is clamped to `min(configured_lifespan, subject_token_remaining)`,
  so delegation can never outlast the authority it derives from.
- **Token types.** Only
  `urn:ietf:params:oauth:token-type:access_token` is supported for
  `subject_token_type` / `actor_token_type` / `requested_token_type`; anything
  else returns `invalid_request`. An optional `actor_token` (the acting party)
  requires `actor_token_type` when present.
- **Bounded delegation depth.** Chained re-exchanges are capped (the nested
  `act` chain may not exceed 4 actors); deeper requests get `invalid_request`.
- **No refresh token** is issued — a delegated token is short-lived; the agent
  re-exchanges as needed.
- Every exchange (success and failure) is recorded as an event
  (`token.issued`, `token.request_failed`), including the acting agent, its
  delegation chain and the delegation depth.

---

## Client authentication with `private_key_jwt` (RFC 7523 §2.2)

A confidential client can authenticate at the token endpoint by presenting a
short-lived JWT it signed, instead of a shared secret. QAuth advertises
`private_key_jwt` in `token_endpoint_auth_methods_supported` unconditionally.

The practical motivation is CIMD: a client identified by an HTTPS URL was never
issued a secret, so assertion-based authentication is the only confidential
method available to it.

```bash
curl -s -X POST http://localhost:3000/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=eyJ… | jq
```

| Parameter               | Required | Notes                                                                                         |
| ----------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `client_assertion_type` | yes      | Exactly `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.                             |
| `client_assertion`      | yes      | The signed JWT. Its `sub` names the client.                                                   |
| `client_id`             | no       | MAY be omitted when an assertion is present (RFC 7521 §4.2) — the assertion's `sub` names it. |

Rules that are load-bearing rather than incidental:

- **The public key comes from registration, never from the assertion.** Keys are
  read from the client's registered `jwks` (inline) or `jwks_uri` (by reference).
  Key material carried _by_ the assertion — `jwk`, `jku`, `x5u` headers — is
  rejected outright; honouring it would let anyone sign their own credential and
  supply the key to check it against.
- **Public keys only.** A key set holding any private member (`d`, the RSA
  primes and CRT values `p`, `q`, `dp`, `dq`, `qi` and `oth`, an ML-DSA `priv`
  or a symmetric `k`) is refused whole, and so is a key without the public
  members its type needs (EC `crv`, `x` and `y`; OKP `crv` and `x`; RSA `n` and
  `e`). The assertion is refused with `invalid_client`. A key whose private
  members were published is exposed: replace it with a new key, not a trimmed
  copy of the old one.
- **Asymmetric algorithms only.** `alg` is intersected with the same list
  discovery advertises, which contains no `none` and no `HS*`. An HS256
  assertion verified against a public JWK is the classic algorithm-confusion
  attack, where the "signature" is an HMAC over a key the attacker can also read.
- **The registered method must match exactly.** A client provisioned for
  `client_secret_*` cannot authenticate by assertion, and a `private_key_jwt`
  client cannot fall back to its secret.
- **`aud` is the issuer, and only the issuer.** Name the `issuer` from the discovery
  document as the sole audience, as a string or a one-element array. The token
  endpoint URL is refused with `invalid_client`, and so is an `aud` array that
  holds anything next to the issuer (`draft-ietf-oauth-rfc7523bis` §4). Many client
  libraries default to the token endpoint URL, so set the audience explicitly.
- **One method per request.** Presenting more than one authentication method is
  rejected with `invalid_client` (RFC 6749 §2.3) — never "try each until one
  passes".

> ⚠️ **`private_key_jwt` cannot be self-registered.** `POST /oauth/register`
> accepts only `none`, `client_secret_basic` and `client_secret_post`, and the
> `jwks` / `jwks_uri` fields are stripped from a registration request. This is
> deliberate: a client must not be able to self-register the keys that
> authenticate it, nor hand the server a URL to dereference, through an
> unauthenticated endpoint. It is provisioned by an operator — the
> `seed-oauth-clients` manifest or admin — exactly like `max_agent_mode`.

---

## ID-JAG — enterprise-managed authorization (ADR-011)

An **Identity Assertion JWT Authorization Grant** is the credential at the centre
of MCP Enterprise-Managed Authorization. QAuth implements both sides.

**Off by default.** `ID_JAG_ENABLED=false`, and `ID_JAG_TRUSTED_ISSUERS` defaults
to empty — an empty allowlist rejects every assertion. Nothing in an assertion
ever nominates its own trust: verification keys come only from an OIDC discovery
run against an already-allowlisted issuer.

### Consuming an ID-JAG (QAuth as the resource authorization server)

A client presents an ID-JAG minted by a trusted enterprise IdP under the
`jwt-bearer` grant and receives an access token audience-restricted to the MCP
server named by the assertion's `resource` claim. That `resource` must be among
the client's ID-JAG targets, which an operator sets with `id_jag_targets` in the
seed manifest; an empty list denies, and the client's `audience` does not count.
See [Provisioning a client for ID-JAG](/operate/docker/#provisioning-a-client-for-id-jag).

```bash
curl -s -X POST http://localhost:3000/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  -d assertion=eyJ… | jq
```

**An assertion bound to a DPoP key.** The IdP may bind the ID-JAG to the
client's DPoP key with a `cnf` claim, `{"cnf": {"jkt": "<thumbprint>"}}`
(`-04` §9.8.1). QAuth then redeems it only with a `DPoP` proof under that key,
which needs `DPOP_ENABLED=true`, and the access token it issues is bound to the
same key (`cnf.jkt` in the token, `token_type: DPoP`). Without a proof the
answer is `invalid_grant` with the description "proof of possession is required
for this assertion"; the assertion is not spent, so send it again with a proof.
A proof under another key, a server with DPoP off, and a `cnf` that names any
confirmation method but `jkt` are refused with the bare `invalid_grant`. The
grant type stays `jwt-bearer`: `-06` names
`urn:ietf:params:oauth:grant-type:jwt-dpop` for a bound ID-JAG, and QAuth
follows `-04`, the revision the EMA extension names. An assertion without `cnf`
works as before: a proof binds the token to its key, and without one the token
is a Bearer token.

**Rotating the IdP's signing key.** QAuth caches the issuer's discovery document
and JWKS for `ID_JAG_JWKS_CACHE_TTL`. An assertion whose `kid` is not in the
cached set makes QAuth fetch both again, but at most once per issuer per
`ID_JAG_JWKS_REFRESH_COOLDOWN` (30 seconds by default); inside that window the
assertion is refused. Publish a new key in the JWKS at least one cooldown before
the IdP signs with it, and no assertion under it is refused while the IdP stays
reachable. This needs a `kid` in every assertion: without one, the JWKS must hold
exactly one key, so an IdP that signs without `kid` cannot publish two at once.
While the IdP cannot be reached, QAuth tries it again only every
`ID_JAG_JWKS_NEGATIVE_CACHE_TTL` (30 seconds by default); keys it has already
cached keep working, and a key it has not seen waits for that window too.

### An ID-JAG is not an access token

It is a single-use, short-lived, audience-restricted authorization **grant**,
presented to one authorization server exactly once and exchanged. Three
properties enforce that:

- the protected header `typ` is `oauth-id-jag+jwt`, distinct from `at+jwt`
  (access token) and `JWT` (ID token), so no token signed for another purpose can
  be substituted — and vice versa;
- `aud` is a **single** authorization-server issuer identifier. A multi-valued
  `aud` is rejected: an assertion authorizing two servers is one that either of
  them can redeem;
- `jti` is consumed exactly once, inside a window bounded by
  `ID_JAG_MAX_ASSERTION_LIFETIME`.

**No re-submission.** The draft (`-04` §4.4.3) lets a client re-submit the same
ID-JAG for a new access token while the assertion is unexpired. QAuth refuses the
second presentation with `invalid_grant`. When the access token expires, ask the IdP
for a fresh ID-JAG. With the default lifetimes nothing changes in practice: an
assertion lives at most 5 minutes and the access token it buys at least 15, so the
assertion expires first.

The grant is confidential-client only, and the client must additionally be
registered for it — which, like `private_key_jwt`, only an operator can do.

**An assertion carrying `authorization_details` (RFC 9396) is refused, not
ignored.** QAuth does not implement rich authorization requests on this path, and
silently dropping a constraint the enterprise IdP applied would hand the client
more authority than was authorized — a downgrade. Unrecognised members that are
_not_ authorization constraints are still tolerated, so a later spec revision
does not break existing deployments.

Every rejection returns a bare `invalid_grant` (RFC 6749 §5.2). The specific
reason is recorded as the event's `reason` code and in the server log, and never sent
on the wire: a caller learning which
check failed would learn whether an issuer is allowlisted, whether a `jti` was
already burned, and whether a `kid` exists — all oracles. The one exception is a
DPoP-bound assertion sent without a proof, which says a proof is required: only
the authenticated client the assertion names gets that far, after every other
check passed.

### Minting an ID-JAG (QAuth as the enterprise IdP)

An RFC 8693 token exchange requesting
`requested_token_type=urn:ietf:params:oauth:token-type:id-jag` returns an
assertion targeted at a **third-party** resource authorization server.

The agent client is provisioned by the operator, and its registration bounds
what it can mint:

- `audience` (exactly one value, the target authorization server's issuer) and
  `resource` (exactly one value, the MCP server) must both appear in the
  client's ID-JAG targets (`id_jag_targets` in the seed manifest). An empty list
  denies. The client's `audience`, which bounds the tokens QAuth issues, does not
  count.
- The assertion's `scope` is the subject token's scope, or the narrower `scope`
  the request names, and every value must also appear in the client's
  registered `scopes`. A value outside that list is refused with
  `invalid_scope`, not dropped: send `scope` to ask for less. A client
  registered with no `scopes` cannot mint a scoped assertion. This is the same
  check `client_credentials` applies ([ADR-011](/reference/records/adr/011-enterprise-managed-authorization/) §3, amended
  2026-10-19).

Minted assertions are signed with EdDSA — the same key that signs access tokens —
so a foreign authorization server verifies them from the JWKS it already fetches
from `GET /.well-known/jwks.json`. This is deliberately **not** the hybrid
(ADR-005) signer: the detached ML-DSA component is delivered through
introspection, and a foreign server has no introspection relationship with QAuth,
so a hybrid ID-JAG would be unverifiable at exactly the party that must verify it.

---

## RP-Initiated Logout

`GET` or `POST /oauth/end-session` signs the browser out of QAuth at an app's
request, then sends it back to the app (OpenID Connect RP-Initiated Logout 1.0).
Discovery lists it as `end_session_endpoint`. The app sends the browser there
with a link, a redirect or a form post. It is not an API call. The session
cookie is `SameSite=Lax`, so a browser leaves it out of a form post from
another site; such a POST is answered `303` to the same endpoint as a `GET`
with the same parameters, which carries the cookie. A large `id_token_hint`
then travels in the URL, so prefer `GET`.

```text
https://auth.example.com/oauth/end-session
  ?id_token_hint=ID_TOKEN
  &client_id=CLIENT_ID
  &post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Fsigned-out
  &state=af0ifjsldkj
```

| Parameter                   | Notes                                                                                                                                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id_token_hint`             | An ID token QAuth issued to the app. Its signature, issuer and `typ` must verify; an expired one is accepted (§2). One that does not verify counts as absent.                          |
| `client_id`                 | The app. With `id_token_hint`, it must be the hint's audience, or the request is refused.                                                                                              |
| `post_logout_redirect_uri`  | Where the browser goes afterwards. It must be one of the app's registered `post_logout_redirect_uris`, matched exactly. Any other value gets an information page and never a redirect. |
| `state`                     | Added to `post_logout_redirect_uri` when the browser goes back.                                                                                                                        |
| `ui_locales`, `logout_hint` | Accepted and not read.                                                                                                                                                                 |

What happens:

- **The hint names the signed-in account.** The browser's session ends at
  once: QAuth revokes it, clears the session cookie and goes back to the
  registered URI with `state`, or shows "You are signed out". The hint's
  `sid` must be this session's: a hint from another session of the account,
  or one without `sid` (an ID token minted before ID tokens carried it), is
  suspect (§2) and gets the confirmation step. So does a hint of an app that
  was deleted, disabled or suspended since.
- **Any other signed-in browser** gets a confirmation step: sign out, sign out
  of all accounts, or stay signed in. Nothing ends until the person answers.
  So a request without a valid hint, such as a cross-site image tag, ends
  nothing. The browser then goes back to the registered URI with `state`,
  whatever the person chose, or to the sign-out status page
  (`/oauth/end-session/status`), which says whether the browser is still
  signed in.
- **A browser that is not signed in** goes back to the registered URI, or sees
  "You are signed out".
- **An app the operator did not set up** (open dynamic registration, a CIMD
  document, the developer API) chose its own return URIs, so QAuth does not
  send the browser there before it has shown a page of its own (RFC 9700
  §4.11.2, as for the authorization endpoint's errors). When the session ends
  at once, or there is none, "You are signed out" names the host of the return
  URI and links to it, with `state`. After the confirmation step the browser
  goes back as for any app.
- **A refused request** (a `client_id` that is not the hint's audience, a
  return URI with no client named, a URI the client did not register, or a
  disabled client) gets a `400` information page. Nothing ends and the browser
  is not redirected.

The route ends the browser session only. It revokes no refresh token: an app
that signs out revokes its own refresh token at [`/oauth/revoke`](#token-revocation-rfc-7009)
first, then sends the browser here. Each outcome is recorded as
`user.signed_out`, which names the ended session (`sid`), or as
`user.sign_out_failed` with the reason. QAuth sends no front-channel logout;
it tells apps by [back-channel logout](#back-channel-logout).

Register return URIs as `post_logout_redirect_uris`: in the
[registration request](#dynamic-client-registration-rfc-7591), in a CIMD
document, or in the seed manifest. They follow the same scheme rules as
`redirect_uris`. A client that registered none is never redirected. A CIMD
document whose list breaks a rule registers none, and its client still
resolves.

### Back-channel logout

When a browser session ends, QAuth POSTs a logout token to every app the
session signed in to that registered a `backchannel_logout_uri`
([OpenID Connect Back-Channel Logout 1.0](https://openid.net/specs/openid-connect-backchannel-1_0.html)).
Whatever ended the session sends it: this endpoint, `POST /auth/logout`, a
password reset, an admin, a retired key, the browser's session limit, or the
session lapsing. Discovery says so with `backchannel_logout_supported` and
`backchannel_logout_session_supported`.

```http
POST /backchannel HTTP/1.1
Host: app.example
Content-Type: application/x-www-form-urlencoded

logout_token=eyJhbGciOiJFZERTQSIsInR5cCI6ImxvZ291dCtqd3QiLCJraWQiOiIuLi4ifQ...
```

The token is a JWT with `typ: logout+jwt`, signed with the key and the
algorithm of your ID tokens (§2.4), which the realm's `jwks_uri` publishes:
verify it as you verify an ID token, and tell the two apart by `typ` and by
`events`. Its claims are `iss`, `aud` (your `client_id`), `iat`, `exp` (two
minutes later), `jti`, `events` with the member
`http://schemas.openid.net/event/backchannel-logout` and an empty object,
`sub` (the user, as in your ID tokens) and `sid` (the session, as in your ID
tokens). It never carries `nonce`. Validate it as §2.6 says, then end your
own session for that `sid`, or every session of that `sub`, and answer `200`
or `204`.

- **One token per app and session.** Each attempt signs a new token with a
  fresh `iat` and `exp`; a retry keeps the `jti`, so an app that keeps the
  `jti` values it has seen can tell a retry it already acted on.
- **Retries.** A `5xx`, `408` or `429` answer, a timeout or a network failure
  is retried on the server's delivery schedule. Any other answer, such as a
  `400`, is final, as §2.5 asks.
- **Sign-out never waits.** The session ends first; the token is queued in the
  same database transaction and sent afterwards, so an app that is down never
  holds anyone signed in, and a server that stops loses no token.
- **`backchannel_logout_session_required: true`** asks for `sid` in every
  token. QAuth always sends it.

Register the URI as `backchannel_logout_uri` in the
[registration request](#dynamic-client-registration-rfc-7591), in a CIMD
document, or in the seed manifest. It must be an absolute `https` URL with a
host, no user name or password and no fragment. A URI you register yourself
must resolve only to public addresses: a private, loopback or link-local
address is refused at registration, even for a development client, and
checked again before every token. Only the operator, through the seed
manifest, may set a URI the deployment's egress allowlist opens. A CIMD
document whose URI breaks a rule registers none, and its client still
resolves.

---

## Token Revocation (RFC 7009)

`POST /oauth/revoke` invalidates an access or refresh token. Requires
**confidential** client authentication — `client_secret_basic` (header) or
`client_secret_post` (body); the route rejects a request using neither.

```bash
curl -s -X POST http://localhost:3000/oauth/revoke \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d token=REFRESH_TOKEN \
  -d token_type_hint=refresh_token -i
# → HTTP/1.1 200 OK  (empty body)
```

| Field             | Required | Notes                                                                                                         |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `token`           | Yes      | The access or refresh token to revoke.                                                                        |
| `token_type_hint` | No       | `access_token` or `refresh_token`. **Advisory only** (§2.1) — the server determines the real type regardless. |
| `client_id`       | No       | Only when authenticating via `client_secret_post`.                                                            |
| `client_secret`   | No       | Only when authenticating via `client_secret_post`.                                                            |

**It always returns `200` with an empty body on success** — including when the
token was already expired, already revoked, or simply never existed (RFC 7009
§2.2). That is deliberate: a distinguishable response would let a caller probe
which tokens are valid. The **only** non-200 outcome is `invalid_client` (§2.2.1)
when client authentication fails.

Revoking a refresh token also revokes its whole rotation family, so a stolen
descendant cannot be replayed.

### What revocation reaches

Every way of ending a grant stops new tokens being minted from it:

| Revocation                                                         | Ends                                                                                                                                  |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `/oauth/revoke` with a refresh token                               | That token's whole rotation family                                                                                                    |
| A replayed refresh token, or a replayed authorization code         | The whole rotation family, and every access token issued in it or from the code (denylisted by `jti` until it would have expired)     |
| `/oauth/revoke` with an access token                               | That access token (denylisted by `jti` until it would have expired)                                                                   |
| Consent revocation (`DELETE /consents/{id}`, `/api/consents`)      | The user's refresh tokens and unredeemed authorization codes for that client                                                          |
| `POST /auth/logout`                                                | The user's hosted browser sessions, refresh tokens and unredeemed authorization codes at every client, and the access token presented |
| `/oauth/end-session` ([RP-initiated logout](#rp-initiated-logout)) | One browser session and its unredeemed authorization codes; no refresh token                                                          |

**Otherwise, access tokens already issued under the grant are not reached.**
They are stateless JWTs and stay valid until `exp` wherever they are accepted: at resource servers that verify
them locally, at introspection, at `/oauth/userinfo`, and as a token-exchange
`subject_token`. Only an access token revoked by value, at `/oauth/revoke` or
as the token presented to `/auth/logout`, or by a replay of the grant it came
from, is refused before then, and only where the denylist is consulted:
introspection, userinfo, token exchange and QAuth's own bearer-protected
routes, not a resource server that verifies the JWT locally. A replay revokes
the access tokens QAuth recorded when it issued them, in Redis; one issued
while Redis could not record it, or a replay while Redis is unavailable, leaves
the token valid until it expires, and the server logs it. A short
access-token lifetime is what bounds this window: the realm's
`tokens.accessTokenLifespanSeconds` (900 s by default) for a staging or
production client, its `tokens.developmentAccessTokenLifespanSeconds` (8 hours
by default) for a development client, each at most a day, and at most its
`tokens.adminAccessTokenLifespanSeconds` (600 s by default, at most 900 s) for a
token whose audience is the admin API, which is also bound to a DPoP key
([API conventions](/reference/api-conventions/#the-dpop-check-of-the-admin-listener)). A delegated token from token
exchange, and an ID-JAG minted from one, never outlive the subject token they
were derived from.

---

## Token Introspection (RFC 7662)

Resource servers can validate opaque or near-real-time-revocable tokens by
asking the AS. Requires **confidential** client authentication.

```bash
curl -s -X POST http://localhost:3000/oauth/introspect \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d token=ACCESS_TOKEN | jq
```

```json
{
  "active": true,
  "sub": "…",
  "client_id": "…",
  "scope": "openid profile email",
  "aud": "http://localhost:8088",
  "iss": "http://localhost:3000",
  "exp": 1750000000,
  "iat": 1749999100,
  "token_type": "Bearer"
}
```

An inactive, expired, unknown, or wrong-audience token, or a user's token once
that user is disabled, returns `{ "active": false }` with no other fields. For most resource servers, **local
JWT verification against the JWKS is preferred** (no per-request round-trip);
use introspection when you need immediate revocation.

> When `HYBRID_SIGNING_ENABLED=true` (default off — see the
> [Status page](/reference/status/)), a successful response also carries
> `pqc_signature` and `pqc_alg`: the token's detached ML-DSA-65 signature and
> algorithm, delivered here because the bearer JWT itself has no room for a
> second signature. Omitted whenever the flag is off or the signature record
> isn't found; neither case affects the `active` decision.

---

## UserInfo (OIDC)

Return the authenticated end user's claims for a user-context access token:

```bash
curl -s http://localhost:3000/oauth/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN" | jq
# → { "sub": "…", "email": "…", "email_verified": true }
```

> `email`/`email_verified` require the `email` scope AND a **verified** email
> attribute (ADR-002 trust order). With no verified email on record, **both
> claims are omitted entirely** — treat `email` as optional. When present,
> `email_verified` is always `true`.

UserInfo accepts an access token only when it is addressed to UserInfo. Its
`aud` must contain either:

- the token's own `client_id`. A grant that named no `resource`, for a client
  without an operator-configured `audience`, gets exactly that, so the token
  from an ordinary OIDC code flow works; or
- the UserInfo URL that discovery publishes as `userinfo_endpoint`
  (`http://localhost:3000/oauth/userinfo` here).

A token whose `aud` names only other resource servers is refused with `401`
and `WWW-Authenticate: Bearer error="invalid_token"`. The token from the code
flow above, bound by `resource=http://localhost:8088`, is such a token: it is
for that MCP server, and that server must not be able to read the user's
claims with it. A client that binds its grant to a resource server can read
the user's identity from the [ID token](#id-token-claims-oidc) instead, or list
the UserInfo URL as another `resource` at `/oauth/authorize`. The second gives
a token both audiences accept, so the resource server can then call UserInfo
with it too.

---

## Dynamic Client Registration (RFC 7591)

`POST /oauth/register` is **open** (no `initial_access_token`) and rate-limited.
See the example in [step 0](#0-prerequisites--a-client). Key fields:

| Field                        | Notes                                                                   |
| ---------------------------- | ----------------------------------------------------------------------- |
| `redirect_uris`              | Required for `authorization_code`. Schemes: see below.                  |
| `post_logout_redirect_uris`  | Optional. Where [RP-initiated logout](#rp-initiated-logout) may return. |
| `backchannel_logout_uri`     | Optional. Where [back-channel logout](#back-channel-logout) POSTs.      |
| `grant_types`                | Subset of `authorization_code`, `refresh_token`, `client_credentials`.  |
| `token_endpoint_auth_method` | `none` (public/PKCE), `client_secret_basic`, or `client_secret_post`.   |
| `scope`                      | Space-separated; **capped to the realm allowlist**. No `qauth:` scope.  |

Each redirect URI must be `https`, `http` to a loopback host (`127.0.0.1`,
`[::1]` or `localhost`), or an RFC 8252 §7.1 private-use scheme for a native
app: a reverse domain name you control, such as `com.example.app:/callback`. A
scheme without a period (`myapp:`) is accepted only when the server's operator
lists it in `REDIRECT_URI_CUSTOM_SCHEMES`, as for the Cursor desktop app's
`cursor:`. Any other scheme, `javascript:`, `data:` and `file:` included, is
refused with `invalid_redirect_uri`, and a URI with a fragment is refused too. The same rule applies to `POST /api/clients` and to a
CIMD document, and `/oauth/authorize` refuses any other scheme still stored on a
client.

Those two lists are exhaustive for self-registration, and the omissions are
deliberate rather than incomplete. `private_key_jwt`, the `jwks` / `jwks_uri`
fields, and the `jwt-bearer` (ID-JAG) grant are all **operator-provisioned
only** — a client must not be able to grant itself a capability whose trust
boundary an operator owns. Zod strips these keys, so a registration request
carrying them is silently ignored rather than honoured; do not rely on that
silence as the enforcement mechanism.

A scope the realm allowlist does not list is dropped, and the client is
registered with the rest (RFC 7591 §2 lets the server narrow the request). The
`qauth:` scope namespace, in any case, is QAuth's own: the admin API's scopes
(`qauth:admin:read`, `qauth:admin:write`, `qauth:admin:security`) live in it,
and only an operator provisions their clients. A realm's allowlist cannot hold
such a scope, so registration always drops one; a client that echoes a
resource's `scopes_supported` still registers. A CIMD document's `scope` is
never stored, so one there is ignored. Other servers' scopes that look
administrative, such as `admin:org`, are ordinary scopes. The three admin
scopes and what they allow are on the
[admin permissions](/reference/admin-permissions/) page.

QAuth's API audiences, the `urn:qauth:aud:` namespace in any case, follow the
same rule: self-registration never obtains one. Registration ignores one in an
`audience` or `resource` member and registers the client with the rest, as it
ignores every other value there, and a CIMD document that names one resolves
with that value ignored. Only a client an operator set up receives such an
audience (see
[API conventions](/reference/api-conventions/#issuing-a-family-audience)).

For MCP clients, **CIMD** (an HTTPS-URL `client_id`) is the recommended
alternative to DCR — see the [MCP Quickstart](/integrate/mcp-quickstart/#client-registration-cimd-vs-dcr).

---

## Errors

QAuth returns standard OAuth error codes (RFC 6749 §5.2):

> **Where they arrive.** In a JSON error body these codes come from
> `apps/auth-server/src/app/plugins/error-handler.ts`, which is registered ahead
> of both route sweeps so that every route resolves it. On the OAuth protocol
> endpoints the body holds only `error`, the bare registered code, and
> `error_description`, the human-readable detail, where there is any to give.
> Every other route answers an RFC 9457 problem document instead; see the
> [error model](/integrate/api-reference/#error-model).
>
> `/oauth/authorize` is different by design. Once `client_id` and `redirect_uri`
> validate it returns `invalid_scope`, `access_denied`, `login_required` and
> `consent_required` as redirect query parameters built in the route itself.
> The errors RFC 6749 §4.1.2.1 forbids redirecting — a `client_id` that names
> no client, and a `redirect_uri` that is not registered or not permitted for
> the environment — reach the caller in the JSON body instead, as
> `invalid_request`. So is `unauthorized_client` (a disabled client, or one not
> registered for the `authorization_code` grant or the `code` response type):
> it is checked before any user interaction, and is never redirected.
>
> **Clients no operator provisioned.** RFC 9700 §4.11.2 lets an
> authorization server redirect automatically only to a redirect URI it trusts.
> QAuth trusts the redirect URIs of a client an operator provisioned: the
> system client and the clients of the `db:seed-oauth-clients` manifest
> (`oauth_clients.provisioned_by_operator`). Every other client registered its
> own redirect URI: one created through `POST /oauth/register`, one resolved
> from a Client ID Metadata Document, and one a developer account created
> through `POST /api/clients`. For such a client an error that would leave the
> issuer before any QAuth page is shown (for example `login_required` for an
> unauthenticated `prompt=none`) is rendered on an issuer page, with HTTP 400
> and a link that carries the full error response to the redirect URI, instead
> of a 302. An owner who changes the redirect URIs of an operator-provisioned
> client through `PATCH /api/clients/{id}` removes that trust.

| Code                      | Meaning                                                                                                                                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `invalid_request`         | Missing/malformed parameter.                                                                                                                                                                                             |
| `invalid_client`          | Client authentication failed or client unknown.                                                                                                                                                                          |
| `invalid_grant`           | Bad, expired or already-redeemed code, wrong or missing `redirect_uri`, bad PKCE verifier, or invalid/replayed refresh token.                                                                                            |
| `unauthorized_client`     | Client not allowed to use this grant.                                                                                                                                                                                    |
| `invalid_scope`           | Requested scope outside the allowlist (or empty for `client_credentials`).                                                                                                                                               |
| `invalid_target`          | RFC 8707 `resource` outside the grant's bound audience, or a QAuth API audience (`urn:qauth:aud:`) the client's `audience` does not list.                                                                                |
| `unsupported_grant_type`  | A `grant_type` the token endpoint does not serve; a missing one is `invalid_request`.                                                                                                                                    |
| `invalid_client_metadata` | Dynamic registration: a metadata value is not valid or not allowed (RFC 7591 §3.2.2).                                                                                                                                    |
| `invalid_redirect_uri`    | Dynamic registration: a redirect URI is not valid or not allowed (RFC 7591 §3.2.2).                                                                                                                                      |
| `access_denied`           | Dynamic registration with a developer token: the developer already has as many clients as the realm allows (HTTP `403`). RFC 7591 defines no error for this refusal; QAuth answers RFC 6749's `access_denied`.           |
| `invalid_token`           | Userinfo, and dynamic registration with a developer token that is not valid: the access token is missing, not valid, or names no active user (RFC 6750 §3.1). A request without one gets a challenge with no error code. |
| `invalid_dpop_proof`      | With DPoP on, the DPoP proof is missing or not valid (RFC 9449).                                                                                                                                                         |
| `temporarily_unavailable` | HTTP `503` with `Retry-After` when the server is too busy to check the client secret now, or `429` when the rate limit refuses the request; retry after the delay.                                                       |
| `server_error`            | HTTP `5xx`: the server failed. The answer says nothing more; its `X-Request-Id` finds the log line.                                                                                                                      |

---

## See also

- [MCP Quickstart](/integrate/mcp-quickstart/) — end-to-end QAuth → MCP handshake.
- [Hosted UI](/integrate/hosted-ui/) — the login, consent, and resume screens.
- [Agent Authorization](/integrate/agent-authorization/) — the agent-native layer
  (`is_agent`, scope modes, step-up, per-agent audit) built on these grants.
- [`@qauth-labs/resource-guard`](https://github.com/qauth-labs/qauth/blob/main/libs/sdk/resource-guard/README.md) —
  resource-server SDK that validates these tokens.
- [ADR-006: OAuth grants and audience](/reference/records/adr/006-oauth-grants-and-audience/).

---

# Hosted UI

URL: https://docs.qauth.dev/integrate/hosted-ui/

`authorization_code` + PKCE ([OAuth 2.1 Flow, step 2](/integrate/oauth-flow/#2-redirect-the-user-to-oauthauthorize))
sends the browser to QAuth itself for a stretch. Three server-rendered pages
handle that stretch — `/ui/login`, `/ui/consent`, and `/ui/resume/{handle}` — and
every integrator meets all three, even one that never renders its own login UI.

## `/ui/login`

`GET /ui/login?return_to=<path>` renders an email/password
form. `return_to` must be a relative, same-origin path — `isSafeReturnTo`
(`apps/auth-server/src/app/helpers/return-to.ts:50`) rejects absolute URLs,
`//host` protocol-relative values, and the `/\host` backslash variant a
browser also resolves as protocol-relative, falling back to `/` on anything
that fails. The page carries a signed, double-submit login-CSRF token in both
a hidden form field and a cookie.

`POST /ui/login` verifies the CSRF pair, then the credentials. On success it
mints a **fresh** session id (session-fixation defence — a pre-login session
id is never reused), sets it as `__Host-qauth_session`, and redirects to
`return_to`. On failure it re-renders the form, and the two failure modes
handle the CSRF token differently: a `403` (CSRF pair missing or mismatched,
`apps/auth-server/src/app/routes/ui/login.ts:312`) mints and sets a **fresh**
token so a legitimate retry can succeed; a `401` (bad credentials,
`apps/auth-server/src/app/routes/ui/login.ts:347`) **reuses** the existing
cookie's token unchanged, since that cookie is still valid — only the
credentials were wrong. An account whose address is not verified yet gets that
same `401` page while the realm requires verified accounts
(`accounts.requireVerifiedAccount`, the default), so the page cannot be used to tell a just-registered free address from a registered
one; its message mentions confirming the address for that reason.

The session is stored in Postgres, with Redis as a cache in front of it, in
the realm of the host the browser signed in on: the cookie names no session at
another realm's host. The cookie lasts until the session's absolute end:
`SESSION_COOKIE_TTL` from sign-in, or the realm's `sso_max_lifespan` when it
sets one, and is not extended by use. The session behind it can end sooner,
when the realm sets `sso_idle_timeout`.
[`POST /auth/logout`](/integrate/api-reference/#post-authlogout) ends every
hosted session of the user, so the next `/oauth/authorize` shows this page
again.

## `/ui/consent`

`GET /ui/consent` takes the same query parameters as
[`/oauth/authorize`](/integrate/api-reference/#oauth-21) and renders the scope
consent screen. It requires a valid `__Host-qauth_session` cookie; without one
it redirects to `/ui/login` (via the pending-authorization mechanism below,
not a raw inline redirect). `POST /ui/consent` submits the decision
(`allow` / `deny`, CSRF-protected) and, on `allow`, issues the authorization
code and redirects to the client's `redirect_uri` exactly as a first visit
would. The **Remember this decision** checkbox (ticked by default) stores the
consent, which lets later requests for the same scopes skip the screen and lists
the client under `/consents`. Unticked, the approval is one-time: nothing is
stored, and `/oauth/token` returns no `refresh_token` for that code.

The screen names the client by what the server verified about it, never by the
name the client gives itself
([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)
Decision 6):

- A client whose `client_id` is a Client ID Metadata Document URL is shown by
  that URL's host, in its ASCII (`xn--`) form, with the registrable domain in
  bold. A host under a shared-hosting suffix (the private section of the Public
  Suffix List) is flagged. The host is all the screen shows, and all the server
  verified: with the default `accept-any-https` trust policy, a document
  anyone can publish on a host that serves anyone's files appears under that
  host. A deployment that accepts third-party agents should give each realm
  the `allowlist` trust policy
  ([CIMD](/operate/docker/#what-the-consent-screen-shows-for-a-cimd-client)).
- A client the operator provisioned is shown by the domain the operator set on
  it: `verified_domain` in the `db:seed-oauth-clients` manifest, or
  `db:set-client-verified-domain` for a client that exists already.
- Any other client, a dynamically registered or developer-portal one included,
  is shown as an unverified app, with the host that receives the code.

A redirect to a loopback address is shown as "this device", with a warning. The
name the client declared comes after all of this, labelled as declared, cut to
64 characters and stripped of control and bidirectional characters. No logo or
link the client supplied is shown.

Since the screen always says where the code goes, registration refuses a
redirect URI it could not show: a host that is not a DNS name of valid labels
(an underscore, an empty label), an IPv6 address other than loopback, or a
private-use scheme longer than 64 characters.

### An AI agent client

For an agent client (one with `is_agent`, see
[Agent Authorization](/integrate/agent-authorization/#1-agent-client-type-is_agent)),
the screen adds two lines after the "Signed in as" line. They are QAuth's own
text, never anything the client declared:

- **"This app is an AI agent."** The name the client declared stays in its
  own line, labelled as declared.
- **How long the agent may keep working.** In a realm without
  `sso_max_lifespan`: "It may keep working until you revoke it." In a realm
  that sets one: "It may keep working until you revoke it, or until &lt;the
  limit&gt; after you signed in, whichever comes first." The limit is written
  as an exact duration that names every unit it holds: `3600` is "1 hour",
  `5400` "1 hour and 30 minutes".

The second line is the end of the agent's refresh-token family. Without a
limit each refresh moves the family's end forward, until the user revokes the
consent under `/consents`, except for a browser-based agent (a public client
with an `https` redirect URI), whose family ends when its first refresh token
expires. With one, the family ends no later than its start
plus the limit and the end of the browser session behind the code, and that
session ends the limit after the sign-in
([Refresh Token](/integrate/oauth-flow/#refresh-token-rotation)). Three things
the line leaves to this page:

- **The family needs a stored consent.** The code exchange issues a refresh
  token only under one: the approval with **Remember this decision** ticked,
  or a consent the user remembered on an earlier visit, which unticking the
  box later does not remove (revoke it under `/consents`). With neither, no
  refresh token is issued and the agent stops when its access token expires.
- **An access token outlives both ends.** Revoking the consent and the
  family's end stop refreshes; an access token already issued works until it
  expires, after the realm's access token lifetime
  (`tokens.accessTokenLifespanSeconds`, 15 minutes by default) or, for a
  `development` client, its `tokens.developmentAccessTokenLifespanSeconds`.
- **The limit is the one the page read.** The page states the realm's limit
  as it is when the page renders. A limit the operator changes later applies
  to the family as the Refresh Token section describes, not as the page said.
  A browser session keeps the end it was given at sign-in, so after a realm
  raises `sso_max_lifespan`, a family started from a session signed in before
  the change ends at the earlier of its start plus the new limit and that
  session's own end, which the old limit set.

A stored consent never skips the screen for an agent client (ADR-015
Decision 11): every authorization request from an agent shows it, and
`prompt=none` from an agent answers `consent_required` with no code.

The decision is taken for the page the user saw. A client whose `is_agent`
changes between the page and the decision (a Client ID Metadata Document can
change it) gets nothing from that decision: the browser goes back to
`/oauth/authorize`, which shows the page the client needs now.

### A first-party client

An operator can mark a client as first party: the seed manifest's
`first_party_profile` ([Docker](/operate/docker/)), which no registration path
can set
([ADR-017](/reference/records/adr/017-first-party-login/) Decisions 2
and 9). For such a client the operator's decision stands in for the user's
consent, an administrative consent:

- `/oauth/authorize` issues a code without this screen when none of the
  requested scopes is dangerous (`write:*`, `agent:admin`, `agent:exec`) and
  the request does not carry `prompt=consent`. Under `prompt=none` it issues
  the code too, for a `web_redirect` client.
- The waiver stores nothing for the user. Unless the user once remembered a
  consent for the client on this screen, the client is not listed under
  `/consents`, and `/oauth/token` returns no `refresh_token` for such a code,
  as for an approval with **Remember this decision** unticked. A remembered
  consent that covers the code's scopes, at each resource indicator the code
  is bound to, still yields one.
- Every such code is recorded as a
  [`consent.administrative`](/reference/events/#consentadministrative-v1-rc0)
  event: the profile it rests on, the scopes and resource indicators it
  covered, and the endpoint.
- A dangerous scope or `prompt=consent` shows this screen, as for any client,
  even when a stored consent covers the request. Under `prompt=none` such a
  request answers `login_required` when a fresh sign-in is due (a dangerous
  scope on a sign-in more than two minutes old), else `consent_required`.
- A client whose profile is `native_backend`, the backend of a native app, has
  every request treated as `prompt=login`, whatever the request says: a
  browser that already holds a session meets the login page unless its sign-in
  is less than two minutes old, and `prompt=none` answers `login_required`
  however recent the sign-in. A `POST /ui/consent` for such a client asks for
  the same fresh sign-in. So a native app's browser leg completes only on a
  sign-in of the last two minutes, the window `prompt=login` gives every
  client, never on an older session. Its own `prompt=consent` still shows this
  screen.

A client whose profile does not hold, because its row breaks one of the
profile's rules or its policy does not parse, is treated as a client without
one.

## Upstream providers on the login page

When the login page was opened for an authorization request, it lists the
realm's upstream identity providers, each as a plain link that works without
JavaScript: "Sign in with <name>", in the realm's order, a hidden provider left
out (#639). `GET /ui/upstream/{type}?return_to=<the same return_to>` sends the
browser back to that authorization request with
[`qauth_upstream=<type>`](/integrate/oauth-flow/#routing-to-an-upstream-provider),
reading a parked request (`/ui/resume/{handle}`) without spending it. The
authorization endpoint starts an interaction for the request and sends the
browser to `GET /ui/upstream/{type}/start?interaction=<id>`, which starts the
provider and answers a waiting page: it goes on to the provider at once, with a
link for a browser that does not follow the refresh and a way back.

The provider sends the browser back to `/upstream/{type}/callback` on the realm
host. Only the browser that started may complete the sign-in, once; the account
is found by the provider's subject under its issuer, never by email, and a new
one is created only when the realm allows sign-up (`ALLOW_SIGN_UP`). On success
the browser goes back to the authorization request under its new session. A
cancel or an error at the provider brings the browser back to the ceremony
page, whose step read makes the `upstream` step current with the error
`provider_declined` or `provider_error` and names the provider, beside the
other ways in (#1081); the server-rendered pages show a page with a way back to
the first step instead. Every other failure shows one error page with the
request's trace id. Nothing of either reaches the client.

The provider proves the account as a password does, and the sign-in then asks
for what the account still owes (ADR-017 Decision 4): an account that holds a
passkey gives it after the provider, since a passkey outranks an upstream
sign-in, and a recovery code may stand in for it; the realm's MFA policy
applies; and where the realm requires verified accounts
(`REQUIRE_VERIFIED_ACCOUNT`), an account the provider's verified switch left
unverified has its address verified with an emailed code. The Interaction
API's ceremony page (`INTERACTION_UI_ENABLED`) shows each of these steps, the
passkey while passkey sign-in is on (`WEBAUTHN_ENABLED`). With the Interaction
API off, the server-rendered pages show none, so an account that needs one is
refused there. With the provider's verified switch off, these pages create no
account at all, and neither does the ceremony page for a provider that gives
no email: such an account could never sign in.

### Linking an upstream account to an existing one

With the Interaction API on, an identity no account holds does not create an
account at once (#670). The interaction asks first, at its `upstream_link`
step, which `GET /ui/upstream-link/{interactionId}` shows as a page: "I
already have an account", or "Create a new account" when the realm allows
sign-up. The page names the provider and nothing else: no address, no account
and no hint, and QAuth never looks an account up by an email address.

"I already have an account" goes on to a sign-in to that account in the same
interaction, under its MFA policy: the password or the passkey, then the
second factor the account or the realm asks for. No password reset is offered
during it. The realm's other upstream providers are, beside its first step,
never the one being linked (#1080), so an account made through one provider
links a second by signing in with the first. Such a provider proves the
account only through an identity the account already holds: one no account
holds signs in to nothing and creates nothing, whatever address the provider
gives, and a passkey the account holds is still asked for after it. Once that
sign-in completes, the identity joins the account it proved, the security log
records the link, and the owner gets an email notice at the address of the
account's password (an account with no password, such as one made through a
provider, has the security log alone); the authorization
request goes on as after any sign-in. An identity another account holds, or
took meanwhile, or an account that already has an identity of that provider,
is refused, and nothing reaches the client: the ceremony page shows the
`upstream_link` step again with the reason as its `error` (`already_linked`,
`provider_linked`, `account_unavailable`), where the sign-in had finished the
interaction as the first step of the request's next one (#1081). The step
takes no answer; its cancel ends the request with `access_denied`, or goes back
to the account page for a link started there.

A signed-in account links a provider through an authorization request with
[`qauth_link=<type>`](/integrate/oauth-flow/#linking-an-upstream-account): the
provider first, then the same fresh sign-in. The pages of the Interaction API
off (`INTERACTION_UI_ENABLED`) offer no link, and create the account at once as
before.

## Creating an account from the sign-in

With the Interaction API on (`INTERACTION_UI_ENABLED`), the ceremony page's
sign-in offers "Create an account" beside its first step (#1079), so a person
who opens a sign-in without an account need not go back to the client for a
[`prompt=create`](/integrate/oauth-flow/#registration-promptcreate) request.
It is offered while the realm allows sign-up (`accounts.allowSignUp`), the
client's operator-set `hosted_flows` name `register`, and the authorization
request carries no `max_age` and no `prompt=login`: the rules of
`prompt=create`, but for the `openid` scope, which only `prompt=create` needs.
It is offered before anyone is named and reads no account, so it is the same
for every person.

Picking it turns the sign-in into the registration `prompt=create` starts, in
the same interaction and for the same authorization request: the bot challenge
first where the realm or the client requires one, then the address, its mailed
code and a new password. The registration ends as one `prompt=create` started:
in a code for that request, with no `amr` and no `auth_time`, and no browser
session. Until the address is given, the registration's address step offers
"I have an account", which leads back to the sign-in's first step; a
registration `prompt=create` started offers it too.

The rules are read again on every answer: once the realm or the client stops
allowing sign-up, picking "Create an account" is refused, and the sign-in
stays where it was. A sign-in to
[link an upstream account](#linking-an-upstream-account-to-an-existing-one)
never offers it, nor does the account page's sign-in. `/ui/login`, the page
the Interaction API off serves, offers neither.

## `/ui/resume/{handle}`

`GET /ui/resume/{handle}` is where a login round-trip lands after a
successful sign-in. It exchanges a single-use handle for the pending
`/oauth/authorize` URL and redirects there — see below for what the handle
is and why it exists. Resuming re-validates `client_id`, `redirect_uri`,
scope, PKCE, and step-up **from scratch**, exactly as on a first visit
(`apps/auth-server/src/app/routes/ui/resume.ts:124`); a resumed handle grants
nothing a fresh authorize request would not.

---

## The recovery-code pages

A recovery code stands in for a lost second factor after the password (#649;
ADR-017 Decision 8). Redemption, and showing a new set, happen only on the
hosted pages: the sign-in engine never offers either step to the first-party
login endpoint, which answers `redirect_to_web` instead. Two server-rendered
pages serve them for an interaction of the Interaction API, until the
design-system screens of #650 replace them:

- `GET /ui/recovery-code/{interactionId}`: "Use a recovery code", one field,
  with "That code did not work" after a refused one (the same for a wrong
  code, a used one and one of another set).
- `GET /ui/recovery-codes/{interactionId}`: "Save your recovery codes", the
  ten codes of a new set and a confirmation that they are saved. The codes
  are shown only to the browser whose flow cookie binds the interaction, and
  never to a page another site opened (`403`).

Both forms post to the Interaction API's answer endpoint
(`/interaction/v1-rc.0/{interactionId}/answer`) with the step, its CSRF value
and the answer, and work without JavaScript. An interaction at another step is
sent to its ceremony page (`303`); one that ended gets a page saying so
(`410`). Neither page puts a code in a URL, and both are sent with
`Cache-Control: no-store`.

A code is `xxxx-xxxx-xxxx-xxxx`, typed with any case, spaces and dashes. Each
works once, adds no `amr` value and never meets an MFA policy. Wrong codes are
counted on the account, whatever the transaction or the address: from five,
each attempt waits longer, up to 15 minutes, after a bot challenge. A code
used, a set regenerated and a run of 100 wrong codes (at most once a day) each
mail the account a notice that no realm can switch off.

---

## The passkey pages

A passkey is the strongest factor an account can bind (#651; ADR-017
Decisions 4 and 10). While passkey sign-in is on, the sign-in engine offers
it first: with no `login_hint`, the first step asks for a passkey and offers
the password and the identifier beside it; with one, it asks for the password
and offers the passkey. A login completes only after the account's strongest
bound factor, so after a right password an account that holds a passkey is
asked for it. On these pages `/oauth/authorize` starts a sign-in with no
`login_hint` at that first step, and one with a hint at the identifier step,
which the hint fills in. After a password sign-in, the engine may offer to add
one, unless the realm turned that offer off (its `passkeys.offerAfterSignIn`
policy, on by default; #1083); a passkey added from the account page is
offered either way. Two server-rendered pages run the ceremonies for an
interaction of the Interaction API, until the design-system screens of #652
replace them:

- `GET /ui/passkey/{interactionId}`: "Sign in with a passkey", for the
  `webauthn_get` step, current or offered beside the password. Its options
  name no account. After a refused answer it says "That passkey did not
  work", the same whatever was wrong. "Sign in another way" links back to the
  interaction's ceremony page, for the password or the identifier.
- `GET /ui/passkey-enrolment/{interactionId}`: "Add a passkey", for the
  `webauthn_create` step, with "Not now" beside it. The options carry the
  account's name, so the page is shown only to the browser whose flow cookie
  binds the interaction, and never to a page another site opened (`403`).

Each page runs the browser's ceremony (`navigator.credentials.get()` or
`.create()`, so it needs JavaScript) and posts the credential's JSON as
`webauthn_response` to the Interaction API's answer endpoint with the step and
its CSRF value. The server refuses an assertion whose authenticator did not
verify the user. An interaction at another step is sent to its ceremony page
(`303`); one that ended gets a page saying so (`410`). Both are sent with
`Cache-Control: no-store`.

## The authenticator app's pages

An authenticator app (TOTP: RFC 6238 with SHA-1, six digits and a 30-second
step, one step of tolerance either way) is a second factor an account binds
(#653; ADR-017 Decisions 7 and 8, ADR-020 §3). After the first factor, an
account that holds one is asked for its code; under an MFA policy, an account
with no second factor is asked to set one up before the sign-in completes,
and is sent no code. Password then code gives `amr` `["pwd","otp","mfa"]`.
Two server-rendered pages serve the steps for an interaction of the
Interaction API, until the design-system screens of #654 replace them:

- `GET /ui/totp/{interactionId}`: "Enter the code from your authenticator
  app", for the `totp` step. After a refused answer it says "That code did not
  work", the same for a wrong code, a used one and a late one. When the step
  offers a recovery code in its place, "Use a recovery code instead" opens its
  form.
- `GET /ui/totp-setup/{interactionId}`: "Set up an authenticator app", for the
  `totp_setup` step: the new secret as a QR code of its `otpauth://` URI and
  as text, and the field for the first code. The secret is bound only once
  that code is valid, and that code stands for the sign-in's `totp` step. The
  secret is personal data, so the page is shown only to the browser whose
  flow cookie binds the interaction, and never to a page another site opened
  (`403`). The interaction record does not keep it: each read opens the
  sign-in's sealed copy again. A verified account binds its first
  authenticator app after a fresh sign-in, with no code mailed to its address:
  the account decides, never a channel (ADR-017 Decision 8, amended on
  2026-11-08). An unclaimed account, a password account not yet verified,
  binds none. The first binding issues a set of recovery codes.

Both work without JavaScript and post to the Interaction API's answer endpoint
with the step and its CSRF value. An interaction at another step is sent to
its ceremony page (`303`); one that ended gets a page saying so (`410`). Both
are sent with `Cache-Control: no-store`.

Wrong codes count per account, across transactions, clients and IP
addresses, and no successful password clears them: after the fifth in a row,
each attempt waits longer (up to 15 minutes), and an attempt that comes early
gets `429` without being checked. A wrong code after a right password mails
the account a notice, at most once a day. At 100 in a row, and only while
these pages are on and the account keeps an unused recovery code or another
usable second factor, the authenticator app is turned off and the account is
told. The next sign-in takes a recovery code in its place, then asks to set
up the app again before it completes. No realm can switch these notices off.

## The account pages

`/ui/account` is the signed-in person's own account (#844; ADR-017 Decision 8,
ADR-020 §3): their sign-in methods and their sessions, server-rendered in the
style of the pages above until the design-system account console replaces
them. The pages exist while the hosted pages do (`INTERACTION_UI_ENABLED`); with
the switch off, every path answers `404`. They are reached with the realm's
browser session: a browser with none is sent through a sign-in on the hosted
pages and comes back.

| Page or form                                                                    | What it does                                                                                                                                                   | Replaced by |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `GET /ui/account`                                                               | The overview: the password, the passkeys, the authenticator app, the recovery codes, the linked upstream accounts and the live sessions, each with its actions | #685        |
| `GET` and `POST /ui/account/password`                                           | Change the password, with the current one, under the realm's password policy and breach list                                                                   | #685        |
| `POST /ui/account/passkeys/add`, `…/{passkeyId}/rename`, `…/{passkeyId}/remove` | Add a passkey through the enrolment step of the sign-in, rename one, remove one                                                                                | #686        |
| `POST /ui/account/totp/setup`, `/ui/account/totp/remove`                        | Set up an authenticator app through the set-up step of the sign-in, turn it off                                                                                | #687        |
| `POST /ui/account/recovery-codes/regenerate`, `…/confirm`                       | A new set of recovery codes, shown once; every code of the old set stops working                                                                               | #687        |
| `POST /ui/account/sessions/{sessionId}/end`, `/ui/account/sessions/end-all`     | Sign one session out, or sign out everywhere                                                                                                                   | #688        |
| `POST /ui/account/linked-accounts/link`, `…/{linkedAccountId}/unlink`           | Link an upstream account by signing in to it, unlink one                                                                                                       | —           |
| `POST /ui/account/reauthenticate`                                               | "Confirm it's you": a fresh sign-in, then back to the page                                                                                                     | —           |

Every action is a plain form that works without JavaScript, and every post is
checked in the same order before anything is read or changed: it comes from the
realm's origin (`Sec-Fetch-Site: same-origin`, or the realm's `Origin` when the
browser sends no fetch metadata), it carries the browser session, and it
carries the session's CSRF value. A post that fails the first or the last is
refused with `403` and recorded as `request.csrf_rejected`.

A change asks for the fresh authentication the account API asks of the same
operation (#663): a sign-in from the last five minutes with the account's
strongest bound factor, a passkey, else the authenticator app, else the
password. Removing a passkey or the app also takes a sign-in that used a
recovery code in place of the lost one; renaming a passkey and ending sessions
ask for none. A change refused for want of one answers `403` with "Confirm it's
you", which starts that sign-in and comes back. Adding a passkey, setting up an
app and linking an account are such a sign-in themselves, followed by the
binding step, with its own rules: a verified account binds its first passkey
or app with no mailed code, an unclaimed account binds none, and the first
one issues a recovery code set. A link attaches only the identity the provider proved to
the account the same interaction signed in to; nothing is matched by an email
address.

The pages keep an account usable. A removal that would leave no way to sign
in (an authenticator app is a second factor, never a way in on its own, and a
credential the failure ladder or a passkey rebind turned off counts as none) is
refused with `409`, and so is one that would leave no second factor where the
realm's MFA policy requires one. A new password ends the account's other
sessions and revokes every refresh token; this browser stays signed in. Ending a
session, one or all, tells every relying party it signed in to with a
back-channel logout URI. Each change is recorded as a user event:
`user.password_changed`, `user.credential_added`, `user.credential_removed`,
`user.passkey_renamed`, `user.recovery_codes_regenerated`,
`user.upstream_linked`, `user.upstream_unlinked` and `user.signed_out`. A
changed password, a removed passkey or authenticator app, a new recovery code
set and a linked or unlinked account mail the owner. No page puts a secret or a code in a URL, and every page is
sent with `Cache-Control: no-store`.

## Pending authorization: why the login bounce carries a handle, not a URL

Before qauth-labs/qauth#319, every surface that bounced an unauthenticated
user to `/ui/login` nested the **entire** authorize query string inside
`return_to` — `/ui/login?return_to=%2Foauth%2Fauthorize%3F...`. Once `state`
and `nonce` could legally reach 2048 characters each
(`OAUTH_OPAQUE_PARAM_MAX_LENGTH`,
`apps/auth-server/src/app/constants/security.ts:71`), that `Location` header
could exceed ~10 KB — past a typical reverse proxy's default header-buffer
limit, so the browser got a `414`/`400` instead of the login page, on the
_unauthenticated first-visit path_, and invisibly so in local dev (no proxy
in front).

#319 fixed this by parking the authorize URL server-side instead of nesting
it in the redirect:

- An unauthenticated `GET /oauth/authorize` no longer nests the query. It
  stashes the normalized authorize URL in Redis under a fresh,
  **43-character CSPRNG handle** (`randomBytes(32).toString('base64url')`,
  `apps/auth-server/src/app/helpers/pending-authorization.ts:191`) and
  redirects to `/ui/login?return_to=%2Fui%2Fresume%2F<handle>` — a ~60-byte
  path regardless of how large `state`, `nonce`, or `resource` are. The same
  stash-then-redirect helper
  (`redirectToLoginWithPendingAuthorization`,
  `apps/auth-server/src/app/helpers/pending-authorization.ts:283`) backs all
  five login-bounce call sites: two in
  `apps/auth-server/src/app/routes/oauth/authorize.ts` (lines 334 and 554)
  and three in `apps/auth-server/src/app/routes/ui/consent.ts` (lines 369,
  559, and 763) — #319 closed #316 specifically because an earlier fix had
  patched only one of these sites and missed the rest.

- **Single-use.** `consumePendingAuthorization`
  (`apps/auth-server/src/app/helpers/pending-authorization.ts:235`) deletes
  the Redis record as it reads it, before even validating its contents. A
  login URL saved from browser history or a screen recording therefore
  cannot be replayed — the second `GET /ui/resume/{handle}` for the same
  handle gets the "expired" page, not a second redirect.

- **Expires after 10 minutes.**
  `PENDING_AUTHORIZATION_TTL_MS`
  (`apps/auth-server/src/app/constants/security.ts:101`) bounds the stash to
  10 minutes — long enough to cover an interactive login (reading the page,
  a password manager, typing credentials) but short because this is
  auth-flow state, not user session state. An expired, unknown, or
  already-used handle all render the **same** "this sign-in request has
  expired" page (`expiredPage`,
  `apps/auth-server/src/app/routes/ui/resume.ts:40`) with a plain `400` and
  no redirect — the three cases are made indistinguishable on purpose, so a
  handle can't be probed to learn which ones ever existed.

- **A `state` over 16 KB is rejected outright.**
  `PENDING_AUTHORIZATION_MAX_URL_BYTES`
  (`apps/auth-server/src/app/constants/security.ts:131`) caps the authorize
  URL the stash will accept. This is a backstop behind the per-parameter
  2048-character bounds already enforced at the edge, not the primary
  control — but because the stash is written **before** the caller
  authenticates, an unbounded write there would be a pre-auth memory-pressure
  primitive against the same Redis that holds live browser sessions and
  rate-limit counters. Exceeding it returns `400 invalid_request:
  authorization request is too large`
  (`apps/auth-server/src/app/helpers/pending-authorization.ts:215`)
  rather than either a `500` or a `Location` header no proxy would forward.

### What the stash adds to the pre-authentication path

Redis was already on that path before #319, and not marginally: the
Redis-backed `@fastify/rate-limit` plugin is registered app-wide
(`apps/auth-server/src/app/app.ts:931`) ahead of both route sweeps (lines 294
and 301), against the same `fastify.redis` client
(`apps/auth-server/src/app/plugins/rate-limit.ts:28`); `RATE_LIMIT_ENABLED`
defaults to `true` (`libs/server/config/src/lib/schemas/rate-limit.ts:41-44`);
and the `onRequest` hook it attaches to each of those routes `INCR`s a per-IP
counter on **every** request, authenticated or not (`PEXPIRE` on the first
request of a window, `PTTL` on the rest) — which is why the size cap above talks
about "the same Redis that holds live browser sessions and rate-limit
counters". What the pending-authorization stash adds is narrower and worth
naming precisely: it is
the first **caller-influenced write** an unauthenticated visitor can trigger,
which is the reason `PENDING_AUTHORIZATION_MAX_URL_BYTES` exists at all.

The stash itself degrades rather than fails. If the write cannot complete,
`redirectToLoginWithPendingAuthorization` catches the failure and falls back
to the pre-#319 inline `return_to`
(`apps/auth-server/src/app/helpers/pending-authorization.ts:299`). That
inline fallback is correct for every request small enough to survive a
proxy's header buffer — only the pathological multi-kilobyte `state` that
motivated the stash would still be too large, and for that one case an
oversized redirect is judged better than an opaque `500` at the
authorization endpoint. Symmetrically, a **read** failure in
`consumePendingAuthorization` is treated as a miss and renders the same
"expired" page a genuinely-expired handle would
(`apps/auth-server/src/app/helpers/pending-authorization.ts:245`) — an
unreachable Redis is, from the user's side of `/ui/resume/{handle}`,
indistinguishable from a handle that timed out.

Do not read those fallbacks as "a Redis outage is invisible here", though.
`@fastify/rate-limit`'s `skipOnError` is left at its default of `false`, so
when the store is unreachable the rate-limiter rethrows from its `onRequest`
hook — before the route handler, and therefore before either fallback can
run. The fallbacks cover a stash operation that fails on its own; they do not
cover an instance-wide Redis outage, which fails the request at the
rate-limit hook instead.

### Not an open redirector

The handle is never resolved from anything the client controls at resume
time — it comes back out of Redis and is re-validated
(`normalizeInternalAuthorizeUrl`,
`apps/auth-server/src/app/helpers/pending-authorization.ts:153`) to be
this server's own `/oauth/authorize` path before use, both on the way in and
the way out. The only reachable destination is a fresh visit to
`/oauth/authorize`, which then re-checks `client_id` and `redirect_uri`
exactly as it would on a first request.

---

## See also

- [OAuth 2.1 Flow](/integrate/oauth-flow/) — the `authorization_code` + PKCE
  walkthrough these screens sit inside.
- [API Reference → Hosted UI](/integrate/api-reference/#hosted-ui) — the wire
  contract (methods, parameters, status codes) for these routes.

---

# API Reference

URL: https://docs.qauth.dev/integrate/api-reference/

Hand-written reference for QAuth's HTTP endpoints. The **authoritative, always-current**
contract is the interactive OpenAPI / Swagger UI served at /docs on any running
instance — this page is a stable, linkable companion. The same contract is also
published as a static file: [`openapi.json`](https://docs.qauth.dev/openapi.json).

For step-by-step flows with copy-paste `curl`, see the [OAuth 2.1 Flow](/integrate/oauth-flow/)
guide; for working client code, see [Code Examples](/integrate/code-examples/); for the
login/consent/resume screens an end user sees, see [Hosted UI](/integrate/hosted-ui/).

**Conventions**

- Base URL / issuer: `http://localhost:3000` (your `JWT_ISSUER`).
- First-party auth, client-management, and hosted-UI bodies are **JSON**
  (`application/json`) with **camelCase** fields. OAuth wire endpoints (the OAuth 2.1
  section below) use **`application/x-www-form-urlencoded`** with **snake_case** per the RFCs.
- Access tokens are **EdDSA (Ed25519)** JWTs; verify against
  `GET /.well-known/jwks.json`.
- Path parameters are written in OpenAPI's `{param}` style below (matching
  `openapi.json`), not the `:param` style the Fastify route files use internally.

## Error model

QAuth answers an error in one of two formats (ADR-019 Decision 7). Branch on the machine-readable
member and the HTTP status, never on the wording, which may change.

**Problem documents.** Every route that is not an OAuth protocol endpoint (first-party auth,
client management, consents, the hosted UI, the well-known documents and any path no route serves)
answers with an RFC 9457 problem details document, sent as `application/problem+json`:

```json
{
  "type": "https://docs.qauth.dev/reference/problem-types/#validation-error",
  "title": "Validation error",
  "status": 400,
  "detail": "The request is not valid.",
  "instance": "/auth/login",
  "code": "validation_error",
  "trace_id": "7d1c2e9a-5b8f-4f3e-9c6a-1e2d3f4a5b6c",
  "errors": [{ "pointer": "/email", "message": "Invalid email address" }]
}
```

- `code` is the stable, machine-readable name of the error. The list of codes, with each one's
  `type`, status and title, is on [Problem types](/reference/problem-types/).
- `trace_id` is the id the server logged the request under, the `X-Request-Id` the response also
  carries (the header `REQUEST_ID_HEADER` names), on every answer, the 404 of a path no route
  serves and a request the server could not read included. Quote it when you report a failure.
- `errors` names each field a validation failure rejected: `pointer` is an RFC 6901 JSON Pointer
  into the body or the parameters, and `message` says what is wrong with it. The validator's own
  issue objects also carry the schema path, the rule keyword and a parameter bag, and those
  describe how QAuth is built rather than what it accepts, so they are not returned. At most 20
  entries are returned. An array longer than its limit is one entry for the array as a whole; its
  elements are not checked. A weak password's feedback arrives as entries whose pointer names the
  password field.
- A 5xx carries no `detail`. A 401 or 403 from a route that takes a bearer token also carries a
  `WWW-Authenticate` challenge (RFC 6750 §3): `error="invalid_token"` for a token that was
  presented and refused (`invalid_access_token`, `access_token_expired`), and no error code for a
  request that presented none (`unauthorized`).

**OAuth error bodies.** The OAuth protocol endpoints answer with the body their specification
defines, `application/json` with only `error` and, where there is something to say,
`error_description`: the authorization, token, introspection, revocation, dynamic registration and
userinfo endpoints and the wallet-facing OID4VP endpoints.

```json
{ "error": "invalid_client", "error_description": "CIMD document is not valid JSON" }
```

`error` is the registered code (RFC 6749 §5.2, RFC 7591 §3.2.2, RFC 6750 §3.1); the codes are
listed in [OAuth 2.1 Flow → Errors](/integrate/oauth-flow/#errors). `error_description` is omitted
where describing the failure would be an enumeration oracle: client authentication failures answer
with the bare `invalid_client`. The `Retry-After` and `WWW-Authenticate` headers are sent as before.

| Status | Meaning                                                                                             |
| ------ | --------------------------------------------------------------------------------------------------- |
| `400`  | Malformed request / validation error                                                                |
| `401`  | Missing, malformed, or invalid bearer token / session                                               |
| `403`  | Authenticated but not permitted (e.g. insufficient scope)                                           |
| `404`  | Resource not found                                                                                  |
| `409`  | Conflict (e.g. a resource that must be unique)                                                      |
| `429`  | Rate limited                                                                                        |
| `503`  | Too busy to check a client secret now; `Retry-After` says when to retry (`temporarily_unavailable`) |

---

## System

Unauthenticated operational endpoints.

### `GET /`

Root endpoint. Returns a fixed greeting to verify the server is running.

**`200 OK`**: `{ "message": "Hello API" }`

### `GET /health`

Liveness probe. Answers on any host, checks no dependency, and names the
service roles the process runs.

**`200 OK`**:

```json
{
  "status": "ok",
  "timestamp": "2026-07-27T00:00:00.000Z",
  "roles": ["web", "api", "admin", "signer", "delivery"]
}
```

### `GET /ready`

Readiness probe. Answers on any host and runs the checks the process's roles
need: `database` on every role, `redis` on `web`, `api` and `admin`, `kek` on
`signer` and `outbox` on `delivery`.

**`200 OK`** (every check passed):

```json
{
  "status": "ok",
  "roles": ["api"],
  "checks": { "database": { "status": "ok" }, "redis": { "status": "ok" } }
}
```

**`503 Service Unavailable`**: a problem document with the code
`service_unavailable`, whose `detail` names the failed checks and whose
extension members `roles` and `checks` carry what the `200` answer carries,
each failed check as `{ "status": "fail", "reason": "error" }` or
`"reason": "timeout"`.

Both are rate-limited per client address. The Prometheus metrics are not on
this port: they are served on the internal listener (see
[Observability](/operate/observability/#who-can-read-the-metrics)).

---

## First-party authentication

Email/password endpoints for **end users of your own application**. Third-party
/ MCP clients use the [OAuth endpoints](#oauth-21) instead.

### `POST /auth/register`

Register a password account. The answer is the same for every address, whether
it was free or already has an account, so it reveals neither. What happens next
arrives by email (the `mock` provider delivers nothing):

- A free address gets an unverified account and a verification link.
- An address that already has a verified account gets no new account. Its owner
  gets a notice that someone tried to register it, with no link in it.
- An address whose account is still unverified gets its verification link
  again. The link verifies only with the password chosen when the account was
  first registered (see [`POST /auth/verify`](#post-authverify)).

A mail to an existing account counts toward the same per-address caps as
[`POST /auth/resend-verification`](#post-authresend-verification), and every
registration claims the minimum interval there, so a resend right after a
registration answers `429` for any address. A new account's verification mail is
always sent.

**Request** (`application/json`)

| Field      | Type           | Required | Notes                                        |
| ---------- | -------------- | -------- | -------------------------------------------- |
| `email`    | string (email) | yes      | At most 254 characters (RFC 5321).           |
| `password` | string         | yes      | The realm's password policy applies (below). |
| `realmId`  | string (uuid)  | no       | Must be the realm of the request's host.     |

**`202 Accepted`** (`Cache-Control: no-store`)

```json
{ "message": "Registration received. Check your inbox for an email with the next step." }
```

The body carries no user id: anything that differed between a new account and an
existing one would answer the question this endpoint must not. Show a "check your
inbox" screen, never "account created" or "address taken". While the realm
requires verified accounts (`accounts.requireVerifiedAccount`, the default), the
account can sign in only after
its owner has verified it; until then [`POST /auth/login`](#post-authlogin)
answers it with the same `401` as a wrong password.

The account is created in the realm of the host the request names. A `realmId`
in the body picks no other realm: any value but that realm's id is refused.

The password must meet the realm's password policy (ADR-017 Decision 8): at
least `password.minLength` characters (15 by default), counted after Unicode
NFC normalisation; at most 256 UTF-16 code units as typed; not, as a whole and
ignoring case, a common word or password, the address, its local part or
domain, or the service's or realm's name; and a zxcvbn score of at least
`password.minScore` (2 by default). No mix of character types is required.
Mark the fields for password managers: `autocomplete="username"` on the
address and `autocomplete="new-password"` on the password.

Errors: `400` (validation, a password over 256 UTF-16 code units among it, or
a `realmId` that is not the host's realm), `422` (`weak_password`, whose
`reasons` list why the password was refused: `too_short`, `blocklisted`,
`too_weak`; `errors` carries a message for each, whose pointer names the
password field), `429` (rate limited). None of them depends on
whether the address is registered. Before 2026-10-19 this endpoint answered `201`
with the new user and `409` for a registered address (breaking change, listed in
`CHANGELOG.md`).

### `POST /auth/login`

Authenticate with email/password and receive tokens directly (first-party).

**Request** (`application/json`): `{ "email": "...", "password": "..." }`. The
address is at most 254 characters.

**`200 OK`**

```json
{
  "access_token": "eyJ…",
  "refresh_token": "a1b2…(64 hex)",
  "expires_in": 900,
  "token_type": "Bearer"
}
```

The access token is issued to the system client, its `aud` is the developer
API's audience, `urn:qauth:aud:developer:v1-rc.0` (#524), and its `scope` is
`qauth:developer:read qauth:developer:write` (#933): it reaches the
[Developer API](#developer-api-developer-family-v1-rc0), the deprecated
`/api/clients/` and `/api/consents/`, userinfo and `POST /auth/logout`. A token
minted before #524, whose `aud` was the system client's id, is refused there, so
its developer signs in again (see
[API conventions](/reference/api-conventions/#issuing-a-family-audience)). It
is not a sign-in at `GET /oauth/authorize`, which takes only the browser session.

Errors: `400` (validation), `401` (invalid credentials), `429` (rate limited,
locked out, or inside the account's wait on the
[per-account failure ladder](/operate/observability/#per-account-failure-ladder);
with `Retry-After`), `503` (the failure ladder's store is unavailable; nothing
was checked; `Retry-After: 5`).
The `401` is the same for an unknown address, a wrong password, a disabled
account and, while the realm requires verified accounts
(`accounts.requireVerifiedAccount`, the default), an account whose
address is not verified yet: registering an address and then logging in must not
tell a free address from a registered one.
Renew the access token with the [`refresh_token` grant](/integrate/oauth-flow/#refresh-token-rotation)
at `POST /oauth/token` — there is no separate refresh endpoint.

### `POST /auth/logout`

Sign the user out everywhere. Ends the user's hosted browser sessions (from
`/ui/login` or wallet login, so `/oauth/authorize` shows the login page again),
revokes every refresh token the user holds, at every client, invalidates the
user's unredeemed authorization codes, and denylists the access token the
request was made with. Access tokens already
issued to other clients are not reached: they stay valid until they expire (see
[what revocation reaches](/integrate/oauth-flow/#what-revocation-reaches)).

**Headers**: `Authorization: Bearer <access_token>` (required). Only the access
token from [`POST /auth/login`](#post-authlogin) is accepted, expired or not. A
token issued to any other client or audience is refused.

**`200 OK`**: `{ "success": true, "message": "Successfully logged out" }`

Errors: `401` (missing/invalid bearer, or a token whose user no longer exists).

### `POST /auth/verify`

Confirm an email address with the token from the verification email and the
account's password. The token proves control of the mailbox. The password proves
the person who registered. Both are required, so someone who registered with
another person's address cannot get it verified by that person clicking a link.
This is a POST, so no fetch or prefetch of the emailed link can verify an address
by itself. The emailed link opens [`GET /auth/verify`](#get-authverify), a page
that asks for the password; the developer portal's verification page calls this
route the same way.

**Body**: `{ "token": "<64-char hex string>", "password": "<the account's password>" }`

**`200 OK`**: `{ "message": "...", "email": "dev@example.com" }`

Errors: `400` (malformed token, or an unknown, expired or used token: one
answer for all of them), `401` `INVALID_CREDENTIALS` (wrong password; the token
is not consumed, so the request can be retried), `409` (the address is already
verified), `429` (rate limited, or the account is locked out: wrong passwords
here count toward the same failed-login lockout and per-account failure ladder
as `POST /auth/login`, and the `429` carries `Retry-After`), `503` (the failure
ladder's store is unavailable; the password was not checked; `Retry-After: 5`).

### `GET /auth/verify`

The page the verification email links to: `<issuer>/auth/verify?token=<64-char hex>`,
where `<issuer>` is the issuer of the account's realm. The link verifies only at
a host of that realm. The GET does not look the token up, so at another realm's
host it still renders the form (`200`); submitting it there answers `400`, as for
an unknown token, because `POST /ui/verify` looks the token up in the realm the
request's host names.
A mail client opens the link with GET, so this page is what a person sees. It
holds the token in a hidden field and asks for the account's password; opening
it verifies nothing and reads nothing from the database, so a mail gateway's
link scanner or a browser prefetch cannot verify an address. The form posts to
`POST /ui/verify` (below), which verifies through the same code as
[`POST /auth/verify`](#post-authverify).

**Query**: `token` — the 64-character hex token. A missing or malformed token
gets a `400` page that says the link is incomplete, with no form.

**`200 OK`**: `text/html` page with the form. It sets the signed
`__Host-qauth_login_csrf` cookie the form's double-submit CSRF check needs, the
same cookie as [`/ui/login`](/integrate/hosted-ui/#uilogin).

Every answer carries `Cache-Control: no-store` and `Referrer-Policy: no-referrer`,
and the request log censors the `token` value. A `browser` route: it answers on
the realm's primary host only (`421` on an endpoint host).

**`POST /ui/verify`** (`application/x-www-form-urlencoded`: `token`, `password`,
`csrf_token`) answers a page with the status `POST /auth/verify` answers for the
same outcome:

| Status | Outcome                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------- |
| `200`  | Verified. The account can sign in.                                                             |
| `400`  | Unknown, expired or used token (one page for all), or a malformed body.                        |
| `401`  | Wrong password. The form stays; nothing is consumed.                                           |
| `403`  | CSRF pair missing or mismatched. The form comes back with a fresh token.                       |
| `409`  | The address is already verified.                                                               |
| `429`  | Rate limited, or locked out by the failed-login lockout or the failure ladder (`Retry-After`). |
| `503`  | The failure ladder's store is unavailable; nothing was checked (`Retry-After`).                |

It has the rate limit of `POST /auth/verify`, and wrong passwords count toward
the same failed-login lockout and failure ladder. This page is interim: the email-code step (#638)
and the hosted account verification UI (#644) replace link verification.

### `POST /auth/resend-verification`

Re-send the verification email. Rate-limited per address (min-interval +
per-window caps). [`POST /auth/register`](#post-authregister) counts toward the
same caps.

**Request** (`application/json`): `{ "email": "dev@example.com" }`

**`200 OK`**: `{ "message": "..." }` — returned even for unknown addresses
(no account enumeration). Errors: `400` (not an address, or longer than 254
characters), `429` (too soon / over limit).

### `POST /auth/link/wallet`

Start linking a wallet credential to the **signed-in** account (issue #238,
[ADR-004](/reference/records/adr/004-wallet-agnostic-federation/) /
[ADR-009](/reference/records/adr/009-wallet-account-resolution/) §5). Registered
only when `WALLET_FEDERATION_ENABLED` is on; otherwise the path does not exist
(`404`).

Requires a valid `__Host-qauth_session` cookie **and** an `X-CSRF-Token` header
matching the per-session token returned by `GET /consents/`.

**Request** (`application/json`, optional): `{ "device": "this" }`. Linking is
**same-device only** ([ADR-013](/reference/records/adr/013-same-device-return-leg/),
amended 2026-11-07): the wallet must be on the device the browser runs on.
Render `invocation_uri` as a deep link; the link completes on the browser's
return leg at `GET /ui/wallet-login/return`, never by polling. `this`, an empty
body, or no body at all are the same request. `"device": "other"`, the
cross-device mode this endpoint accepted before, is refused with `400`
`validation_error`, whose `errors` entry points at the `device` member, as is
any other value. The
generated OpenAPI document marks this request body as required — the
generator's default for any declared body schema — but a `POST` with no body at
all is accepted.

**`200 OK`**: `{ "handle": "...", "invocation_uri": "openid4vp://...", "expires_at": 1730000000000 }`
— render `invocation_uri` as a deep link ("Open my wallet"); it is opaque.
Errors: `401` (no session), `400` (`invalid_csrf_token`, or a `device` other
than `this`: `validation_error`), `404` (no usable `VerifierProfile`), `500`.

### `GET /auth/link/wallet/{handle}`

Poll a linking flow, and complete it once the wallet has responded. Requires the
session cookie and the browser-binder cookie minted by the `POST` above; the
session must be the **same user** that started the flow.

**`200 OK`**: `{ "status": "pending" | "linked" | "conflict" | "expired" | "rejected", "message"?: "..." }`

On `linked`, a second `user_credentials` row (`provider_type='wallet'`) now
exists under the same `users.id`, keyed on the identifier the account already
owned — so a later wallet sign-in returns tokens with the identical `sub`. This
poll never completes a link: it answers `pending` after the wallet has
responded, `linked` **once** after the return leg has completed it in the same
browser, and `rejected` if the redirect has not landed within 180 s or landed
in a different browser (#405). A cross-device link flow started before the
2026-11-07 change is answered `rejected`, and nothing is linked.
`conflict` is the one specific outcome (the credential belongs to another
account) and is only reachable under the `issuer-scoped-claim` strategy; every
other failure renders one uniform refusal. See
[Wallet sign-in](/integrate/wallet-login/#account-linking-238).

### `GET /auth/pass`

The page a mailed pass link opens: `<issuer>/auth/pass?pass=<43-char base64url>`,
where `<issuer>` is the issuer of the account's realm. The send-ceiling notice
and the password-disabled notice carry it. The pass is single use, bound to the
address it was mailed to and valid 24 hours. It takes one reset or registration
start on the hosted pages past every per-address send cap; the code that start
mails is still required.

Opening the link does not spend the pass: it starts an interaction in this
browser, with a flow cookie of its own, that holds the pass's hash, and answers
`303` to the interaction's ceremony page, whose path names the interaction id
and nothing else. Only the start the interaction carries spends the pass, so a
mail gateway's link scanner or a browser prefetch spends nothing. A reset starts at the `password_reset` step, a
registration at the `identifier` step. Until the hosted reset and registration
are built, the interaction can be read but not answered.

**Query**: `pass` — the mailed pass. A missing, malformed, unknown, used or
expired pass, or one of another realm, gets one `400` HTML page and no
interaction. Every answer carries `Cache-Control: no-store` and
`Referrer-Policy: no-referrer`, and the request log censors the `pass` value.

---

## OAuth 2.1

Full request/response detail and a worked end-to-end walkthrough live in the
[OAuth 2.1 Flow](/integrate/oauth-flow/) guide. Contract summary:

| Endpoint                                                                           | Method    | Body type    | Purpose                                                                                                                                            |
| ---------------------------------------------------------------------------------- | --------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/oauth/authorize`](/integrate/oauth-flow/#2-redirect-the-user-to-oauthauthorize) | GET, POST | query / form | Start `authorization_code` + PKCE. POST mirrors GET with form-encoded params (OIDC Core §3.1.2.1) — browser-navigated either way, not an API call. |
| [`/oauth/token`](/integrate/oauth-flow/#3-exchange-the-code-for-tokens)            | POST      | form         | `authorization_code` / `refresh_token` / `client_credentials` / `token-exchange` (RFC 8693)                                                        |
| [`/oauth/introspect`](/integrate/oauth-flow/#token-introspection-rfc-7662)         | POST      | form         | Token introspection (RFC 7662) — confidential clients only                                                                                         |
| [`/oauth/userinfo`](/integrate/oauth-flow/#userinfo-oidc)                          | GET, POST | —            | OIDC UserInfo (Bearer header, or POST with a form-encoded `access_token`, RFC 6750 §2.2)                                                           |
| [`/oauth/register`](/integrate/oauth-flow/#dynamic-client-registration-rfc-7591)   | POST      | JSON         | Dynamic Client Registration (RFC 7591, open mode)                                                                                                  |
| `/oauth/revoke`                                                                    | POST      | form         | Token revocation (RFC 7009)                                                                                                                        |
| [`/oauth/end-session`](/integrate/oauth-flow/#rp-initiated-logout)                 | GET, POST | query / form | RP-initiated logout (OpenID Connect RP-Initiated Logout 1.0) — browser-navigated, not an API call                                                  |

Key contract facts:

- `response_type` is `code` only; `code_challenge_method` is `S256` only (PKCE required).
- Tokens carry `iss`, `aud` (RFC 8707 resource binding), `exp`, `iat`, and `scope`.
- `client_credentials` tokens set `sub = client_id` and issue **no** refresh token.
- Scopes are **deny-by-default** (client allowlist; DCR clients capped to the
  realm's allowlist, which `DEFAULT_DYNAMIC_REGISTRATION_SCOPES` seeds). The
  `qauth:` scope namespace is QAuth's own, the admin API's scopes among them: no
  realm allowlist holds one, so dynamic registration drops one, a CIMD
  document's is ignored, and discovery does not list them
  ([admin permissions](/reference/admin-permissions/)).
- The `urn:ietf:params:oauth:grant-type:token-exchange` grant (RFC 8693, ADR-007 §2)
  lets an **agent** client delegate on behalf of a user: `sub` stays the user and
  an `act` claim names the agent (nested for chained delegation). Agent-only and
  default-deny; scope/audience are preserved or narrowed, never widened. See the
  [Token Exchange](/integrate/oauth-flow/#token-exchange--agent-on-behalf-of-delegation-rfc-8693)
  section and the [Agent Authorization guide](/integrate/agent-authorization/).
- DPoP (RFC 9449), when the operator sets `DPOP_ENABLED=true`: a token request
  that carries a `DPoP` proof gets an access token bound to the proof's key
  (`cnf.jkt` in the token, `token_type: "DPoP"` in the response), whatever the
  grant. Send `dpop_jkt` on the authorization request to bind the code to the
  key too. A public client's refresh token is bound to the key and needs a
  proof under it on every refresh; a confidential client's is not. A client the
  operator marked `dpop_bound_access_tokens` in the seed manifest must send a
  proof on every token request, or gets `400 invalid_dpop_proof`. Discovery
  then lists the accepted proof algorithms in `dpop_signing_alg_values_supported`.
  A resource server built on `@qauth-labs/resource-guard` refuses a bound token,
  because the SDK verifies no DPoP proof yet; a client that calls one sends no
  proof, so its tokens stay unbound. Three kinds of token are always bound, so
  they cannot be used at such a resource server until the SDK verifies DPoP
  proofs: the tokens of a client marked `dpop_bound_access_tokens`, a token
  exchanged from a DPoP-bound subject token, and an access token issued for a
  `cnf`-bound ID-JAG.
- Dynamic Client Registration (`POST /oauth/register`) accepts the optional
  QAuth extension field `is_agent` (boolean, default `false`) marking the client
  as an AI agent; it is echoed back in the response. The flag is self-asserted
  and untrusted — see [Agent Authorization](/integrate/agent-authorization/#1-agent-client-type-is_agent).

### Token response (`POST /oauth/token`, `200 OK`)

```json
{
  "access_token": "eyJ…",
  "refresh_token": "a1b2…", // omitted for client_credentials, token-exchange, a client whose grant_types leave out refresh_token, and a code no stored consent covers (its scopes at each resource)
  "id_token": "eyJ…", // authorization_code grant only, when `openid` was granted
  "expires_in": 900,
  "token_type": "Bearer",
  "scope": "openid profile email", // present when scopes granted
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token" // token-exchange only (RFC 8693 §2.2.1)
}
```

`id_token` is a separate, client-audienced (`aud` = your `client_id`) EdDSA JWT
asserting the sign-in event: `sub`, `nonce` (when sent), `auth_time` (when a
sign-in backs the code), `amr` (when that sign-in recorded its methods), `sid`
(the browser session, when one backs the code), `name` (only under the
`profile` scope, and only when set on the user), and `email` /
`email_verified` (only under the `email` scope, same trust-ordered resolution
as the [UserInfo response](#userinfo-response-getpost-oauthuserinfo-200-ok)
below). The ID token and UserInfo release the same profile and email claims
for the same grant. Only the `authorization_code` grant issues one;
`refresh_token` does not reissue it. See
[ID token claims](/integrate/oauth-flow/#id-token-claims-oidc) for the full
list.

### Introspection response (`POST /oauth/introspect`, `200 OK`)

```json
{
  "active": true,
  "sub": "...",
  "client_id": "...",
  "scope": "mcp:read",
  "aud": "http://localhost:8088",
  "iss": "http://localhost:3000",
  "exp": 1750000000,
  "iat": 1749999100,
  "token_type": "Bearer"
}
```

An inactive/expired/unknown/wrong-audience token returns `{ "active": false }`,
and so does a user's token once that user is disabled or deleted. A DPoP-bound
token is reported with `"token_type": "DPoP"` and `"cnf": { "jkt": "…" }`, the
thumbprint of its key (RFC 9449 §6.2): the resource server checks the request's
DPoP proof against it. `@qauth-labs/resource-guard` checks no DPoP proof yet, so
it refuses such a token with `401 invalid_token`.

### UserInfo response (`GET|POST /oauth/userinfo`, `200 OK`)

```json
{ "sub": "...", "email": "dev@example.com", "email_verified": true }
```

`email`/`email_verified` are conditional: released only under the `email`
scope and only when a **verified** email attribute exists (ADR-002 trust
order `wallet > oidc_* > self_reported`). Otherwise both keys are **absent**
(never `null`). When present, `email_verified` is always `true`. The `POST`
form accepts the access token either as a Bearer header or as a form-encoded
`access_token` field (RFC 6750 §2.2). A token whose user has been disabled
since it was issued gets `401`. So does a token that is not addressed to
UserInfo: its `aud` must contain the token's own `client_id` (the default when
the grant named no `resource`) or the `userinfo_endpoint` URL from discovery.
See [UserInfo](/integrate/oauth-flow/#userinfo-oidc).

A DPoP-bound token is accepted only as `Authorization: DPoP <token>` with a
`DPoP` proof for the request whose `ath` is the token's hash (RFC 9449 §7.1).
Sent as a Bearer token, in the header or the form body, it gets `401`
(RFC 9449 §7.2).

### `POST /oauth/revoke`

RFC 7009 token revocation. Confidential client authentication required
(`client_secret_basic` / `client_secret_post`, the same as introspection).

**Request** (form-urlencoded): `token` (required), `token_type_hint`
(`access_token` | `refresh_token`, optional/advisory), plus client credentials
if not sent via HTTP Basic.

**`200 OK`**, empty body — **always**, per RFC 7009 §2.2. A refresh token
revokes its whole rotation family; an access token is denylisted by `jti` for
its remaining lifetime. A token the caller doesn't own, or an unknown/invalid
token, is a silent no-op (not an error), so the endpoint cannot be used to
probe whether a token exists. The only non-`200` outcomes are a client
authentication failure (`invalid_client`) and `503` with `Retry-After` when the
server is too busy to check the client secret (`temporarily_unavailable`; RFC
7009 §2.2.1: the token still exists, retry after the delay).

### `GET|POST /oauth/end-session`

OpenID Connect RP-Initiated Logout 1.0. A browser route: the app sends the
browser here. **Parameters** (query, or form-encoded body): `id_token_hint`,
`client_id`, `post_logout_redirect_uri`, `state`, `ui_locales` and
`logout_hint`, each optional and given at most once.

- A valid `id_token_hint` (expired accepted) that names the account of the
  browser session and, by its `sid`, that session ends it: **`303`** to the
  registered `post_logout_redirect_uri` with `state`, or **`200`** with a
  signed-out page, and the session cookie cleared.
- Any other signed-in browser gets the `logout_confirm` step: **`200`** with a
  form, or **`303`** to the ceremony page when `INTERACTION_UI_ENABLED` is on.
  Nothing ends until the person answers.
- A browser with no session: **`303`** to the registered URI, or **`200`**.
- A client the operator did not set up (open dynamic registration, CIMD, the
  developer API) gets no automatic redirect in either case: **`200`** with the
  signed-out page, which links to the registered URI with `state`.
- **`400`** HTML information page, never a redirect: `client_id` is not the
  hint's audience, a `post_logout_redirect_uri` comes with no client named, or
  the client does not register it exactly, or the client is disabled.
- A `POST` without the session cookie (the cookie is `SameSite=Lax`, so a
  cross-site form post leaves it out): **`303`** to the same endpoint as a
  `GET` with the same parameters.
- **`400`** `validation_error` for a repeated or over-long parameter; **`429`**
  over the authorization endpoint's rate limit.

No refresh token is revoked. `GET /oauth/end-session/status` takes no
parameter and says whether this browser is still signed in.

---

## Discovery

Unauthenticated and cacheable. The discovery documents carry
`Cache-Control: public, max-age=3600`; the JWKS carries `public, max-age=300`,
so an HTTP cache keeps a key set for at most five minutes. A JWKS client
library keeps its own cache: set it to five minutes at most
([Caching the JWKS](/integrate/oauth-flow/#caching-the-jwks)).

| Endpoint                                      | Returns                                                    |
| --------------------------------------------- | ---------------------------------------------------------- |
| `GET /.well-known/oauth-authorization-server` | OAuth 2.0 AS metadata (RFC 8414)                           |
| `GET /.well-known/openid-configuration`       | OIDC Discovery 1.0 (superset of the above)                 |
| `GET /.well-known/jwks.json`                  | JWKS — the realm's published token signing keys (RFC 7517) |

All three are the documents of the realm the request's host names
([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/),
Decision 1):

- `issuer` is the realm's issuer, and every endpoint URL, `jwks_uri` included,
  is built on it.
- The JWKS lists the realm's published keys, each under its own `kid`: its
  active keys, a next key from its publication, before it signs, and a retired
  key while it stays published (after a rotation, until its retention ends).
  No other realm's key is in it.
- `id_token_signing_alg_values_supported` follows the realm's active keys:
  `["RS256","EdDSA"]` when it has an active RS256 key, else `["EdDSA"]`.
- `client_id_metadata_document_supported` follows the realm's CIMD policy
  (`registration.cimd.enabled`,
  [#534](https://github.com/qauth-labs/qauth/issues/534)): a realm that has
  CIMD off omits it.
- The settings that add the other members belong to the deployment, and every
  realm advertises them alike: `DPOP_ENABLED`, and `ID_JAG_ENABLED` once
  `ID_JAG_TRUSTED_ISSUERS` names an issuer.

Every node that serves these documents (a process holding the `api` role, see
[Service roles](/operate/service-roles/)) answers the same bytes for the same
realm, whether or not it holds the signer, given the same settings. After a key
changes, a node may serve its previous key list for up to a minute, its key
refresh interval. A host that names no realm gets `421` for all three, with no
fallback to the default realm.

An endpoint host (`DEFAULT_REALM_ENDPOINT_HOSTS`) gets its realm's documents
unchanged: `issuer` and every URL name the realm's issuer, never the endpoint
host, and no document lists endpoint hosts. RFC 8414 §3.3 and OpenID Connect
Discovery §4.3 ask a client to check that `issuer` is the issuer whose
well-known URL it fetched, which an endpoint host's URL is not. A server-side
caller that reaches QAuth through an endpoint host must therefore configure the
realm's issuer explicitly, check `issuer` and the tokens' `iss` against it, and
use the endpoint host only as the address it connects to. A client library that
takes the expected issuer from the URL it fetched refuses these documents.

Prefer discovering endpoint URLs from these documents over hard-coding paths.
The AS metadata advertises `resource_indicators_supported: true`,
`authorization_response_iss_parameter_supported: true` (RFC 9207 — `/oauth/authorize`
returns `iss` on both success and error redirects, so the flag is not
configurable), and, when the realm's CIMD policy is on,
`client_id_metadata_document_supported: true` (CIMD).

### Passkey association files

Experimental. Two more well-known files tell Apple and Android
platforms which native apps share the realm host's passkeys and passwords. They
are served only while the passkey RP ID is the realm host (`WEBAUTHN_RP_ID`
unset or equal to it), and only for a platform the operator listed apps for;
otherwise the path answers `404`. Both carry `Content-Type: application/json`
and `Cache-Control: public, max-age=3600`.

| Endpoint                                      | Returns                                                                                       |
| --------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `GET /.well-known/apple-app-site-association` | `webcredentials.apps` from `WEBAUTHN_APPLE_APP_IDS`                                           |
| `GET /.well-known/assetlinks.json`            | One `delegate_permission/common.get_login_creds` statement per app in `WEBAUTHN_ANDROID_APPS` |

### Shared Signals Framework transmitter

Experimental, off by default. With `SSF_TRANSMITTER_ENABLED=true`, a realm whose
`ssf_transmitter_enabled` is on is an
[OpenID Shared Signals Framework 1.0](https://openid.net/specs/openid-sharedsignals-framework-1_0-final.html)
transmitter: receivers create a stream and QAuth pushes Security Event Tokens
(RFC 8417) to it (RFC 8935). With the switch off none of these routes exists;
for a realm whose own switch is off they answer the `404` of a route that does
not exist, before the request is validated.
[SSF transmitter](/operate/ssf-transmitter/) covers setting one up.

| Endpoint                               | Purpose                                                                     |
| -------------------------------------- | --------------------------------------------------------------------------- |
| `GET /.well-known/ssf-configuration`   | Transmitter metadata (SSF 1.0 §7). Unauthenticated.                         |
| `GET /ssf/jwks.json`                   | The keys that verify the realm's SETs (its `jwks_uri`). Unauthenticated.    |
| `POST /ssf/stream`                     | Create the receiver's stream: `201`, or `409` when it has one in the realm. |
| `GET /ssf/stream`                      | Read it with `?stream_id=`, or list the receiver's streams without.         |
| `PATCH /ssf/stream`, `PUT /ssf/stream` | Update or replace the receiver-supplied members.                            |
| `DELETE /ssf/stream`                   | Delete it with `?stream_id=`: `204`.                                        |
| `GET /ssf/status`, `POST /ssf/status`  | Read or set `enabled`, `paused` or `disabled`, with `delivery_status`.      |
| `POST /ssf/subjects/add`               | Add an RFC 9493 subject: `200`; `403` for an unrelated user.                |
| `POST /ssf/subjects/remove`            | Remove one: `204`.                                                          |
| `POST /ssf/verify`                     | Ask for a verification event: `204`; `429` within 10 seconds of the last.   |

The SET keys are published only at `/ssf/jwks.json`, never in the realm JWKS at
`/.well-known/jwks.json`, so a resource server that skips the `typ` check cannot
take a SET for an access token. Every stream management route takes the
receiver's own access token (`client_credentials`) carrying the `ssf:stream`
scope, with the realm's issuer in `aud` and no other realm's issuer. The client must still hold `ssf:stream`. A receiver reaches only
its own stream; another `stream_id`, or a stream deleted meanwhile, answers
`404`. The verification interval is per receiver. A paused stream holds its
events without spending attempts and sends them within 30 seconds of being
enabled. In `delivery_status`, an endpoint refused or not reached reads
`destination_unreachable`. Delivery is push only. `default_subjects` is `NONE`:
a stream receives events only about the subjects its receiver added, and its
verification events. `events_supported` lists the CAEP, RISC and QAuth-defined
events QAuth's security events are sent as; [SSF events](/reference/ssf-events/)
gives the mapping. A receiver may add a user only when the user holds an active
consent for the receiver's client or a live refresh token it was issued, or a live
refresh token whose audience names the receiver as a resource server; the subject
ends once that relation has ended and the events about the user have reached the
stream (see [SSF transmitter](/operate/ssf-transmitter/#register-a-receiver)).

Errors are problem documents (see [Error model](#error-model)): SSF 1.0 gives
stream management statuses but defines no error body, so these routes are not
OAuth protocol endpoints. `400` is `validation_error` for a body or query the
schema refuses and `bad_request` for a request the protocol refuses, with the
reason in `detail` (`endpoint_url is refused`, a transmitter-supplied member that
does not match, poll delivery); `401` is `unauthorized` for a request with no
token, with a bare `WWW-Authenticate: Bearer` challenge, and `invalid_access_token`
or `access_token_expired` for a token that was refused, with
`error="invalid_token"` in the challenge; `403` is
`forbidden` with `error="insufficient_scope", scope="ssf:stream"` in the
challenge for a token without the scope, and `forbidden` with a bare challenge
for a user the receiver may not add, an unknown user id included; `404` is `not_found`, for a stream the receiver does not have and, as
for any path no route serves, for a realm that does not run the transmitter;
`409` is `conflict`; and `429` is `too_many_requests` with `Retry-After`.

### Interaction API

`GET /interaction/v1-rc.0/openapi.json` returns the OpenAPI 3.1 document of the Interaction API,
the API sign-in pages use to reach the engine, with `Cache-Control: public, max-age=3600`. It is
the same document the docs site publishes; the [Interaction API](/reference/interaction-api/) page
describes its operations, steps and versioning rules.

| Endpoint                                        | Method | Purpose                                                                                          |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `/interaction/v1-rc.0/{interactionId}`          | GET    | Read the current step and its CSRF value. The interaction id alone is enough; no personal data.  |
| `/interaction/v1-rc.0/{interactionId}/personal` | GET    | Read the current step's personal data. Needs the flow cookie; refused from another origin.       |
| `/interaction/v1-rc.0/{interactionId}/answer`   | POST   | Answer the current step, as JSON or as a plain HTML form post. A form post gets `303 See Other`. |
| `/interaction/v1-rc.0/{interactionId}/cancel`   | POST   | Cancel the interaction: the client gets `access_denied`.                                         |

An answer and a cancel need the realm origin (`Sec-Fetch-Site: same-origin`, or an `Origin` of the
realm), the flow cookie and the CSRF value of the step read, checked in that order; the sign-in
engine runs only once all three pass. A request from another origin and a wrong CSRF value get one
generic `403` `forbidden`, audited as `request.csrf_rejected` with `form: interaction`. A CSRF value
answers its step view once: a processed answer, a refused one included, gives the step a new value,
while an answer refused before it is processed (a `400`, a `429`, a `503`) leaves it as it was. A
body is JSON or `application/x-www-form-urlencoded` (else `415`), at most 16 KiB, or 64 KiB for an
answer to `webauthn_create` (else `413`); a form field may not be repeated (`400` `invalid_answer`).
A form post gets `303` to the ceremony app's page of the interaction (under the realm's
sign-in pages), or to the final redirect; a JSON answer gets the next step or the redirect as JSON. The redirect is
taken from the interaction and the realm, never from the request. When a sign-in finishes, its
authorization request goes on (#628): it is checked and decided again for the new session, and the
client gets its code, or the next interaction starts; a cancel checks the request again before the
client gets `error=access_denied`. Every answer is `Cache-Control: no-store`, sends no CORS header, and every
error is a problem document without `detail` or `instance`; a throttled sign-in is `429` with
`Retry-After`. Rate limits count per address and route: an answer that carries a credential (a
password, a one-time or recovery code, a passkey response, a device's user code) counts against the
sign-in form's limit (`LOGIN_RATE_LIMIT` per `LOGIN_RATE_WINDOW`), as one sign-in form post does;
any other answer and the cancel count against the authorization endpoint's (`AUTHORIZE_RATE_LIMIT`
per `AUTHORIZE_RATE_WINDOW`), as do the personal read and the step read. The ceremony app's server
reads the step for every browser, so a step read from one of its addresses that the operator lists
in `CEREMONY_APP_PEERS` counts per interaction instead, under `CEREMONY_APP_PEER_RATE_LIMIT` reads
a minute. With the list empty, as by default, every person signing in through that server shares
its one address bucket.

---

## Hosted UI

Server-rendered, cookie-authenticated pages back the browser leg of
`authorization_code` — see [Hosted UI](/integrate/hosted-ui/) for the full
behaviour, including the pending-authorization mechanics behind the login
bounce.

| Endpoint                                | Method    | Purpose                                                                             |
| --------------------------------------- | --------- | ----------------------------------------------------------------------------------- |
| `/ui/login`                             | GET, POST | Session-cookie login page and form submission                                       |
| `/ui/consent`                           | GET, POST | OAuth consent screen and decision submission                                        |
| `/ui/resume/{handle}`                   | GET       | Resume a pending authorization after login (single-use, 10-minute TTL)              |
| `/ui/verify`                            | POST      | The form of the emailed verification link ([`GET /auth/verify`](#get-authverify))   |
| `/ui/upstream/{type}`                   | GET       | A provider button of the login page: back to the request with `qauth_upstream`      |
| `/ui/upstream/{type}/start`             | GET       | Start the routed upstream provider, then the waiting page that sends the browser on |
| `/ui/upstream-link/{interactionId}`     | GET       | "I already have an account" or a new one: the `upstream_link` step's form (#670)    |
| `/ui/upstream-link-refused`             | GET       | The page of a refused upstream link (#670); no flow sends the browser here (#1081)  |
| `/ui/recovery-code/{interactionId}`     | GET       | "Use a recovery code": the `recovery_code` step's form (#649)                       |
| `/ui/recovery-codes/{interactionId}`    | GET       | "Save your recovery codes": a new set, shown once, and its confirmation (#649)      |
| `/ui/passkey/{interactionId}`           | GET       | "Sign in with a passkey": the `webauthn_get` step's ceremony (#651)                 |
| `/ui/passkey-enrolment/{interactionId}` | GET       | "Add a passkey": the `webauthn_create` step's ceremony, or "Not now" (#651)         |
| `/ui/totp/{interactionId}`              | GET       | "Enter the code from your authenticator app": the `totp` step's form (#653)         |
| `/ui/totp-setup/{interactionId}`        | GET       | "Set up an authenticator app": the secret as a QR code and text, and a first code   |

The account pages below are registered **only** while the hosted pages are on
(`INTERACTION_UI_ENABLED`); with the switch off every path 404s. They are
experimental: the design-system account console replaces them. See
[Hosted UI → The account pages](/integrate/hosted-ui/#the-account-pages) for
the checks every form post meets (#844).

| Endpoint                                               | Method    | Purpose                                                                                 |
| ------------------------------------------------------ | --------- | --------------------------------------------------------------------------------------- |
| `/ui/account`                                          | GET       | The overview of the browser session's account; a browser with no session signs in first |
| `/ui/account/password`                                 | GET, POST | Change the password, with the current one, under the realm's password policy            |
| `/ui/account/reauthenticate`                           | POST      | "Confirm it's you": a fresh sign-in, then back to the page                              |
| `/ui/account/passkeys/add`                             | POST      | Add a passkey: a fresh sign-in, then the `webauthn_create` step                         |
| `/ui/account/passkeys/{passkeyId}/rename`              | POST      | Rename a passkey                                                                        |
| `/ui/account/passkeys/{passkeyId}/remove`              | POST      | Remove a passkey                                                                        |
| `/ui/account/totp/setup`                               | POST      | Set up an authenticator app: a fresh sign-in, then the `totp_setup` step                |
| `/ui/account/totp/remove`                              | POST      | Turn the authenticator app off                                                          |
| `/ui/account/recovery-codes/regenerate`                | POST      | A new set of recovery codes, shown once                                                 |
| `/ui/account/recovery-codes/confirm`                   | POST      | Confirm the new set is saved                                                            |
| `/ui/account/sessions/{sessionId}/end`                 | POST      | Sign one session out                                                                    |
| `/ui/account/sessions/end-all`                         | POST      | Sign out everywhere                                                                     |
| `/ui/account/linked-accounts/link`                     | POST      | Link an upstream account by signing in to it                                            |
| `/ui/account/linked-accounts/{linkedAccountId}/unlink` | POST      | Unlink an upstream account                                                              |

The wallet-login screens below are registered **only** when
`WALLET_FEDERATION_ENABLED` is on; with the flag off (the default) every path
404s. See [Wallet sign-in](/integrate/wallet-login/) for the flow they implement.

| Endpoint                           | Method    | Purpose                                                                                                                                                                                                                                             |
| ---------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/ui/wallet-login`                 | GET, POST | GET renders the ADR-009 identifier form; POST starts the sign-in. The form field `device` (`this` \| `other`, absent ⇒ `other`) says where the wallet is: `this` renders the deep link, `other` the QR code (#405).                                 |
| `/ui/wallet-login/{handle}`        | GET       | The waiting screen for a pending presentation.                                                                                                                                                                                                      |
| `/ui/wallet-login/{handle}/status` | GET       | Poll the presentation's outcome. Completes a cross-device sign-in once the presentation lands; a same-device one only once its return leg has, and rejects it if the redirect never arrives.                                                        |
| `/ui/wallet-login/return`          | GET       | The same-device return leg: `?response_code=` carries the single-use Response Code the wallet received from `POST /oid4vp/response`. Spent first, then bound to the browser that started the flow; every refusal renders one identical page (#405). |
| `/ui/wallet-link`                  | GET, POST | GET renders the confirmation screen; POST starts the link (issue #238) for a wallet on this device. Linking is same-device only: the form field `device` accepts only `this` (absent means the same), `other` answers `400` `validation_error`.     |
| `/ui/wallet-link/{handle}`         | GET       | The waiting/outcome screen for a pending link.                                                                                                                                                                                                      |

---

## Developer API (`developer` family, v1-rc.0)

A developer's OAuth clients, their static API keys, and the developer's own consents (#524). The
paths follow the [API conventions](/reference/api-conventions/): JSON members in `camelCase`, except
registered OAuth client metadata, which keeps its RFC 7591 name (`client_id`, `client_name`,
`redirect_uris`, `grant_types`, `response_types`, `token_endpoint_auth_method`, `client_secret`);
times as RFC 3339 strings; lists as `{ "items": [...], "nextCursor": ... }` with `limit` (1 to 200,
default 50) and `cursor`; an `ETag` on every read of a client, and `If-Match` on its update; errors as
problem documents.

**Authentication.** `Authorization: Bearer <access_token>` (or `DPoP` while DPoP is on), where the
token's only audience is `urn:qauth:aud:developer:v1-rc.0`, it carries no `act` claim, and its subject
is an enabled user of the realm. A token for another family, or with no family audience, is refused with
`401` `invalid_access_token`, before the request is validated.

**Scopes.** A list or a read needs `qauth:developer:read`; a create, update, delete, secret
regeneration, API key mint or revocation, and consent revocation needs `qauth:developer:write`
(#933). The two are independent. A token without the scope an operation needs is refused with `403`
`forbidden` and `WWW-Authenticate: Bearer realm="OAuth", error="insufficient_scope", scope="…"`,
before the request is validated. The token [`POST /auth/login`](#post-authlogin) mints for the
developer portal carries both. Another client gets them only when an operator lists the developer
audience in its `audience` and the scopes in its `scopes`
([API conventions](/reference/api-conventions/#issuing-a-family-audience)).

**Ownership.** Every route reads only the caller's own clients. A client that does not exist, that
another developer owns, or that belongs to another realm is `404` `not_found`, never `403`.

### `GET /developer/v1-rc.0/clients`

List the caller's clients, newest first.

**Query**: `limit`, `cursor`.

**`200 OK`**

```json
{
  "items": [
    {
      "id": "0b9f7d4e-5c1a-4f7e-9d2b-3a6c8e1f0a42",
      "client_id": "3f1c…",
      "client_name": "My App",
      "description": null,
      "redirect_uris": ["https://app.example.com/cb"],
      "scopes": ["openid"],
      "grant_types": ["authorization_code", "refresh_token"],
      "response_types": ["code"],
      "token_endpoint_auth_method": "client_secret_basic",
      "enabled": true,
      "suspended": false,
      "requirePkce": true,
      "environment": "production",
      "staticApiKeysAllowed": false,
      "createdAt": "2026-10-31T09:30:00.000Z",
      "updatedAt": "2026-10-31T09:30:00.000Z",
      "lastUsedAt": null
    }
  ],
  "nextCursor": null
}
```

`scopes` is a list, as the client stores it. `environment`, `staticApiKeysAllowed` and `suspended`
are read-only. Errors: `400` (`validation_error` for a `limit` above 200, `invalid_cursor` for a cursor
this list did not issue), `401`, `403`.

### `POST /developer/v1-rc.0/clients`

Create a client. The body is a closed object: `client_name` (required), `description`,
`redirect_uris`, `scopes`, `grant_types`, `response_types`, `token_endpoint_auth_method`. Left out,
they take the defaults of dynamic registration: `authorization_code` and `refresh_token`, the `code`
response type, and a public client (`none`, PKCE).

**`201 Created`**, with `ETag` and `Location`: the client, and `client_secret` for a confidential
client, in this answer only. Errors: `400` (`validation_error`, `invalid_redirect_uri`,
`invalid_client_metadata` for a scope the realm does not allow), `401`, `403` (the scope, or the per-developer
client limit), `429`.

### `GET /developer/v1-rc.0/clients/{clientId}`

One client, with its `ETag`. `{clientId}` is the client's `id`, not its `client_id`. The `ETag` covers
every member but `lastUsedAt`, which changes whenever the client is used and no update writes.
Errors: `400`, `401`, `403`, `404`.

### `PATCH /developer/v1-rc.0/clients/{clientId}`

Change a client with a JSON Merge Patch (RFC 7396), sent as `application/merge-patch+json`, naming
the version it changes in `If-Match`. Members: `client_name`, `description`, `redirect_uris`,
`scopes`, `grant_types`, `response_types`, `token_endpoint_auth_method`, `enabled`. A member left out
keeps its value; a list is replaced whole; `null` gives a member the value a create gives it when it
is left out (`description` none, the lists empty, the grant and response types and the auth method
their defaults, `enabled` true). `enabled` does not lift an operator's suspension.

The merged client must pass the rules a create checks, and a refusal answers as there: `400`
`invalid_redirect_uri` (a user-facing grant left without a redirect URI) or `invalid_client_metadata`
(grant and response types that do not fit, a scope the realm does not allow).

**`200 OK`**: the client and its new `ETag`. Errors: `400` (`validation_error`, also for a member the
patch may not name, such as `client_id`; the create rules above), `401`, `403`, `404`, `412` (`precondition_failed`: the client
changed since that `ETag`; read it again), `415` (a body that is not a merge patch), `422`
(`unprocessable_content`: `client_name` set to `null`), `428` (`precondition_required`: no
`If-Match`).

### `DELETE /developer/v1-rc.0/clients/{clientId}`

Delete a client. **`204 No Content`**. Errors: `400`, `401`, `403`, `404`.

### `POST /developer/v1-rc.0/clients/{clientId}/regenerate-secret`

Issue a new `client_secret` for a confidential client; the old one stops working at once.
**`200 OK`**: the client and `client_secret`, in this answer only. Errors: `400` (a public client has
no secret), `401`, `403`, `404`, `429`.

### `GET /developer/v1-rc.0/clients/{clientId}/api-keys`

A client's static API keys, newest first, masked (`prefix`, `last4`), revoked ones included
(`revokedAt` set). `clientId` in each key is the client's `id`. **Query**: `limit`, `cursor`.
**`200 OK`**: `{ "items": [...], "nextCursor": ... }`. Errors: `400`, `401`, `403`, `404`.

### `POST /developer/v1-rc.0/clients/{clientId}/api-keys`

Mint a key: `{ "name": "ci" }`. Only while the client's effective environment is `development`
(ADR-008 §6). **`201 Created`**: the key's fields and the plaintext `key`, in this answer only.
Errors: `400`, `401`, `403` (the scope, or not a development client: use `client_credentials`), `404`, `429`.

### `DELETE /developer/v1-rc.0/clients/{clientId}/api-keys/{keyId}`

Revoke a key, idempotently: **`200 OK`** with the key, `revokedAt` set. Errors: `400`, `401`, `403`, `404`.

### `GET /developer/v1-rc.0/consents`

The caller's own active consents, as a user, by when each was first given, newest first (a new grant
to the same client keeps its place, so a page never skips one). It serves the developer portal until the
account console takes them over.

**`200 OK`**

```json
{
  "items": [
    {
      "id": "0b9f7d4e-5c1a-4f7e-9d2b-3a6c8e1f0a42",
      "client_id": "https://agent.example.com/client.json",
      "client_name": "My Agent",
      "scopes": ["openid"],
      "grantedAt": "2026-10-31T09:30:00.000Z"
    }
  ],
  "nextCursor": null
}
```

Errors: `400`, `401`, `403`.

### `DELETE /developer/v1-rc.0/consents/{consentId}`

Revoke one of the caller's consents, with the refresh tokens and the unredeemed authorization codes
the caller holds for that client. **`204 No Content`**. Errors: `400`, `401`, `403`, `404` (a consent of
another user is the same `404` as one that does not exist).

---

## Account API (`account` family, v1-rc.0)

An end user's own account (#524), for the account console's backend. A token whose only audience
is `urn:qauth:aud:account:v1-rc.0`, sent as a Bearer or DPoP token; a token for the developer API is
refused here with `401`, and the reverse. A read needs `qauth:account:read` and a change
`qauth:account:write` (#933), or `403` `forbidden` with the `insufficient_scope` challenge. The
conventions are those of the developer API above.

### `GET /account/v1-rc.0/consents`

The user's active consents, in the order and representation of
`GET /developer/v1-rc.0/consents`. Errors: `400`, `401`, `403`.

### `DELETE /account/v1-rc.0/consents/{consentId}`

Revoke one of the user's consents, as `DELETE /developer/v1-rc.0/consents/{consentId}` does.
**`204 No Content`**. Errors: `400`, `401`, `403`, `404`.

### `GET /account/v1-rc.0/linked-accounts`

The upstream accounts linked to the user (#670), newest first, a page at a time: each with its
`id`, its `provider` type, the provider's `providerName` while the realm has it on, and
`createdAt`. Never the identity's subject at the provider. Linking one is no operation here: it is
an authorization request with
[`qauth_link`](/integrate/oauth-flow/#linking-an-upstream-account), which asks the person to sign
in again. Errors: `400`, `401`, `403`.

### `DELETE /account/v1-rc.0/linked-accounts/{linkedAccountId}`

Unlink one of the user's upstream accounts: the account no longer signs in through that provider,
and the owner gets an email notice. Needs a fresh sign-in with the account's strongest factor and
refuses an act-chain token, as every change to the ways into the account does. The account's last
way to sign in is `409` `last_credential`; one of another user is the same `404` as one that does
not exist. **`204 No Content`**. Errors: `400`, `401`, `403`, `404`, `409`.

---

## Consents (`/consents/`)

:::caution[Deprecated]
Deprecated since #524: every answer carries the `Deprecation` header (RFC 9745), and the operations
are `deprecated` in `openapi.json`. Use [`GET /account/v1-rc.0/consents`](#get-accountv1-rc0consents).
The path keeps working until the release-candidate cleanup removes it
([Deprecations](/reference/api-conventions/#deprecations)).
:::

Lets a signed-in user manage their own OAuth consent grants from the auth-server's
**hosted UI**. **Cookie-authed** (`__Host-qauth_session`), so it carries a CSRF
token.

If you are calling from a separate origin — the developer portal, or your own
front end — use [`/api/consents/`](#consents-api-apiconsents) below instead. That
cookie is set only by `POST /ui/login` and is `SameSite=Lax`, so it will not be
attached to a cross-site `fetch()` whatever `credentials: 'include'` says.

### `GET /consents/`

List the signed-in user's active consents. The response also carries a
per-session CSRF token that **must** be echoed back as `X-CSRF-Token` on
`DELETE /consents/{id}`.

**`200 OK`**

```json
{
  "consents": [
    {
      "id": "...",
      "clientId": "...",
      "clientName": "My App",
      "scopes": ["openid"],
      "grantedAt": 1750000000000
    }
  ],
  "csrfToken": "..."
}
```

Errors: `401` `unauthorized` (no or invalid session), a problem document like every other error
here. The credential is a cookie, so the answer carries no `WWW-Authenticate` challenge.

### `DELETE /consents/{id}`

Revoke one consent owned by the signed-in user. The refresh tokens and the
unredeemed authorization codes the user holds for that client are revoked with
it. Access tokens already issued stay valid until they expire.

**Headers**: `X-CSRF-Token: <csrfToken from GET /consents/>` (required).

**`204 No Content`**. Errors: `400` (`invalid_csrf_token` — missing or
mismatched `X-CSRF-Token`; the first outcome you'll hit if the header isn't
wired up yet), `401` (`unauthorized` — no or invalid session), `404`
(`not_found` — consent does not exist or is not owned by the caller).

---

## Consents API (`/api/consents/`)

:::caution[Deprecated]
Deprecated since #524, with the same `Deprecation` header. Use
[`GET /developer/v1-rc.0/consents`](#get-developerv1-rc0consents) (the developer portal does) or
the account API. The shapes below stay as they are until the path is removed.
:::

The same consent management, **Bearer-authed** — the credential the developer
portal and any other API client actually holds. Same auth model as
[`/api/clients/`](#client-management-apiclients): `Authorization: Bearer
<access_token>`, scoped strictly to the token subject, with `qauth:developer:read`
to list and `qauth:developer:write` to revoke (#933).

**No CSRF token.** A Bearer token is not ambient authority a cross-site page can
make the browser attach, so there is nothing for one to add. The cookie-authed
`/consents/` above needs one precisely because its credential is ambient.

Ownership and auditing are shared with `/consents/`, so the two surfaces cannot
diverge on who may revoke what.

### `GET /api/consents/`

List the authenticated user's active consents.

**Headers**: `Authorization: Bearer <access_token>` (required).

**`200 OK`**

```json
{
  "consents": [
    {
      "id": "...",
      "clientId": "...",
      "clientName": "My App",
      "scopes": ["openid"],
      "grantedAt": 1750000000000
    }
  ]
}
```

No `csrfToken` field — see above. Errors: `401` (missing/invalid bearer).

### `DELETE /api/consents/{id}`

Revoke one consent owned by the authenticated user, with the same effect as
[`DELETE /consents/{id}`](#delete-consentsid).

**`204 No Content`**. Errors: `401` (missing/invalid bearer), `404` (consent
does not exist **or** is not owned by the caller — deliberately the same
outcome, so the API never reveals that another user's consent id exists).

---

## Client management (`/api/clients/`)

:::caution[Deprecated]
Deprecated since #524, with the same `Deprecation` header: use the
[Developer API](#developer-api-developer-family-v1-rc0), which serves the same clients and API keys
in the API conventions' representation. These routes accept only the developer portal's token, whose
audience is `urn:qauth:aud:developer:v1-rc.0` since #524. The shapes below stay as they are until
the paths are removed. Each route needs the developer scope of the operation it aliases (#933):
`qauth:developer:read` for a `GET`, `qauth:developer:write` for any other method, or `403`
`forbidden` with the `insufficient_scope` challenge. The portal's token carries both.
:::

Developer-portal API for managing a developer's own OAuth clients. **JSON**,
**camelCase**, and authenticated with a developer **`Authorization: Bearer`**
access token (from [`POST /auth/login`](#post-authlogin)). Results are scoped to
the token subject's `developer_id`; the client secret is **never** returned.

:::note[Dynamically registered clients and ownership]
A client registered **anonymously** through [`POST /oauth/register`](/integrate/oauth-flow/#dynamic-client-registration-rfc-7591)
or materialised from a CIMD document has no developer to attribute to, so its
`developer_id` is `NULL` and it will **not** appear here for anyone. That is
deliberate: inventing an owner would hand an anonymous caller's client to
whoever the server guessed. Manage such a client out of band, or register it
with attribution instead.

**To get a manageable client from dynamic registration, send your developer
access token with the registration request** (#374):

```bash
curl -s -X POST https://auth.example.com/oauth/register \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{ "client_name": "My App", "redirect_uris": ["https://app.example.com/cb"] }'
```

The client is then owned by that token's subject and behaves like any client
created through `POST /api/clients/`, including the per-developer limit on the
number of clients (`MAX_CLIENTS_PER_DEVELOPER`, `403` once reached). The token
needs `qauth:developer:write`, as `POST /api/clients/` does (#933), or the
registration answers `403` `access_denied`. A token
that does not verify is rejected
rather than silently ignored — otherwise you would get an unowned client while
believing you owned it, which is the failure this note exists to prevent.
:::

### `GET /api/clients/`

List the authenticated developer's OAuth clients.

**Headers**: `Authorization: Bearer <access_token>` (required).

**`200 OK`**

```json
{
  "clients": [
    {
      "id": "0190f7…",
      "clientId": "0190f7a0-…-uuid",
      "name": "My App",
      "description": null,
      "redirectUris": ["http://localhost:5173/callback"],
      "scopes": ["openid", "profile"],
      "grantTypes": ["authorization_code", "refresh_token"],
      "responseTypes": ["code"],
      "tokenEndpointAuthMethod": "none",
      "enabled": true,
      "suspended": false,
      "requirePkce": true,
      "createdAt": 1750000000000,
      "updatedAt": 1750000000000,
      "lastUsedAt": null
    }
  ]
}
```

A developer with no clients gets `{ "clients": [] }`. Errors: `401` (missing/invalid bearer).

`enabled` is the owner's switch. `suspended` is read-only: `true` when the
operator has suspended the client, which is then refused wherever a disabled
client is (`unauthorized_client` at `/oauth/authorize`, `invalid_client` at the
token, introspection and revocation endpoints), whatever `enabled` says. Only
the operator lifts a suspension.

> **Ownership & 404 semantics.** Every per-client route is scoped to the token
> subject's `developer_id`. A client that exists but is owned by another
> developer is reported as **`404 Not Found`** (not `403`) so the API never
> confirms the existence of clients the caller does not own.

### `POST /api/clients/`

Create an OAuth client owned by the authenticated developer. The server
generates the `clientId` (UUID) and, for confidential clients, a 32-byte
`clientSecret`. **The plaintext `clientSecret` is returned in this response
only** — only its argon2id hash is stored, so it is unrecoverable afterwards.

**Headers**: `Authorization: Bearer <access_token>` (required).

**Body** (all besides `name` optional):

| Field                     | Type     | Default                                  | Notes                                                                                                                                                                                                                                                                                                                        |
| ------------------------- | -------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                    | string   | —                                        | Required, 1–255 chars.                                                                                                                                                                                                                                                                                                       |
| `description`             | string   | `null`                                   |                                                                                                                                                                                                                                                                                                                              |
| `redirectUris`            | string[] | `[]`                                     | At most 20. Each validated (OAuth 2.1 §10.3 — `https`, loopback `http`, an RFC 8252 private-use scheme such as `com.example.app:`, or a scheme without a period listed in `REDIRECT_URI_CUSTOM_SCHEMES`; any other scheme is refused). **Required (≥1) for user-involving grants** (`authorization_code` / `refresh_token`). |
| `scopes`                  | string[] | `[]`                                     | At most 100. Capped to the realm's allowed-scopes policy (same allowlist as dynamic registration); a scope outside it is rejected.                                                                                                                                                                                           |
| `grantTypes`              | string[] | `["authorization_code","refresh_token"]` | At most 8. `authorization_code` / `refresh_token` / `client_credentials`.                                                                                                                                                                                                                                                    |
| `responseTypes`           | string[] | `["code"]`                               | At most 4. OAuth 2.1 only supports `code`.                                                                                                                                                                                                                                                                                   |
| `tokenEndpointAuthMethod` | string   | `"none"`                                 | `none` (public) / `client_secret_post` / `client_secret_basic` / `private_key_jwt`.                                                                                                                                                                                                                                          |

**Rate limit**: per-IP, shared budget with `POST /oauth/register`
(`REGISTER_CLIENT_RATE_LIMIT` / `REGISTER_CLIENT_RATE_WINDOW`) — create runs an
argon2id hash on every call, so the cap is mandatory (`429` on exceed).

**`201 Created`** (`Cache-Control: no-store`)

```json
{
  "id": "0190f7…",
  "clientId": "0190f7a0-…-uuid",
  "name": "My App",
  "description": null,
  "redirectUris": ["https://app.example.com/cb"],
  "scopes": ["openid"],
  "grantTypes": ["authorization_code", "refresh_token"],
  "responseTypes": ["code"],
  "tokenEndpointAuthMethod": "client_secret_post",
  "enabled": true,
  "suspended": false,
  "requirePkce": true,
  "createdAt": 1750000000000,
  "updatedAt": 1750000000000,
  "lastUsedAt": null,
  "clientSecret": "a1b2c3…(64 hex chars, shown once)"
}
```

Public clients (`tokenEndpointAuthMethod: "none"`) get **no** `clientSecret`.
A repeated scope is stored once. A client created here is not
operator-provisioned: an authorization error that `/oauth/authorize` would send
before the user sees any QAuth page (for example `login_required` for
`prompt=none`) is shown on an issuer page with a link to the redirect URI, not
redirected automatically (see [Errors](/integrate/oauth-flow/#errors)). A developer may own at most
`MAX_CLIENTS_PER_DEVELOPER` clients (default 100), counting the ones registered
with attribution through `POST /oauth/register`.
Errors: `400` (invalid `redirectUri`, inconsistent grant/response types, missing
`redirectUris` for a user-involving grant, or a scope outside the realm policy),
`401` (missing/invalid bearer, or a non-user token), `403` (the developer already
owns `MAX_CLIENTS_PER_DEVELOPER` clients), `429` (rate limited).

### `GET /api/clients/{id}`

Get one of the developer's clients. Safe fields only — never the secret.

**`200 OK`** — the same shape as a `GET /api/clients/` list item.
Errors: `401`; `404` (not found or not owned).

### `PATCH /api/clients/{id}`

Partially update a client. Any subset of: `name`, `description`,
`redirectUris`, `scopes`, `grantTypes`, `responseTypes`,
`tokenEndpointAuthMethod`, `enabled`, with the same limits as on create. `clientId`, the secret, and
`developerId` are **immutable** here (unknown/immutable keys are ignored). The
_effective_ configuration (request value or persisted value) is re-validated:
grant/response-type consistency, a redirect URI for user-involving grants, and
the realm scope cap when `scopes` is changed.

`enabled` is the owner's switch and may be set either way. It does not lift an
operator's suspension: `suspended` cannot be written here, and a suspended
client stays refused after `"enabled": true` until the operator lifts it.

**`200 OK`** — the updated client (safe fields, no secret).
Errors: `400` (validation / inconsistent config / disallowed scope / missing
redirect for a user-involving grant), `401`, `404`.

### `DELETE /api/clients/{id}`

Delete a client. After deletion the client can no longer authenticate at the
token endpoint and cannot start new authorization flows. Note: already-issued
**access tokens are stateless JWTs** and remain valid until they expire;
short access-token lifetimes bound this window.

**`204 No Content`**. Errors: `401`; `404` (not found or not owned).

### `POST /api/clients/{id}/regenerate-secret`

Issue a new `clientSecret`. The previous secret is invalidated immediately;
**the new plaintext secret is returned in this response only.**

**`200 OK`** (`Cache-Control: no-store`) — the client (safe fields) plus a
`clientSecret` string. Errors: `400` (public client — no secret to rotate),
`401`, `404`, `429` (rate limited — argon2id, same per-IP budget as create).

Clients may also be obtained outside this API: via **CIMD**, the mechanism
MCP Authorization 2026-07-28 says to prefer; via
[Dynamic Client Registration](/integrate/oauth-flow/#dynamic-client-registration-rfc-7591)
(`POST /oauth/register`), which that revision deprecates but QAuth still
supports; or via the `seed-oauth-clients` script.

---

## API keys (`/api/clients/{clientId}/api-keys`)

Static, long-lived developer API keys scoped to one of the developer's own
OAuth clients — an alternative to `client_credentials` for **development-only**
use. Same Bearer developer authentication and ownership/404 rules as client
management, above.

> **Environment-gated (ADR-008 §6).** Minting a key is permitted only while the
> client resolves to a **development** environment; a staging/production (or
> unset-environment) client is refused with `403`. Use the OAuth
> `client_credentials` grant instead for anything beyond local development.

### `POST /api/clients/{clientId}/api-keys`

Mint a static API key for the client.

**Request** (`application/json`): `{ "name": "..." }` (1–255 chars).

**`201 Created`**

```json
{
  "id": "...",
  "clientId": "...",
  "name": "local dev",
  "prefix": "...",
  "last4": "...",
  "createdAt": 1750000000000,
  "lastUsedAt": null,
  "revokedAt": null,
  "key": "...(plaintext, shown once)"
}
```

Errors: `400`, `401`, `403` (client not in a development environment), `404`.

### `GET /api/clients/{clientId}/api-keys`

List the client's API keys — masked fields only (`prefix` + `last4`, never the
key or its hash). Includes revoked keys (`revokedAt` set).

**`200 OK`**: `{ "apiKeys": [ { "id": "...", "clientId": "...", "name": "...", "prefix": "...", "last4": "...", "createdAt": 0, "lastUsedAt": null, "revokedAt": null } ] }`

Errors: `401`, `404`.

### `DELETE /api/clients/{clientId}/api-keys/{keyId}`

Revoke one API key. Idempotent soft-delete — the row is retained with
`revokedAt` set, and a revoked key never authenticates again.

**`200 OK`** — the revoked key (masked fields, `revokedAt` set).
Errors: `401`, `404` (client or key not found / not owned).

---

## Wallet federation transport (`/oid4vp/request/{handle}`, `/oid4vp/response`)

**Flag-gated, off by default.** `POST /oid4vp/response` is registered only when
`WALLET_FEDERATION_ENABLED=true` **and** a `VerifierProfile` is configured for
the deployment; both default off, and with either missing the route does not
exist (404) or fails closed. See the [Status page](/reference/status/) for
where wallet federation stands overall.

**Even when enabled, this endpoint is transport only.** It is the OID4VP 1.0
`direct_post` Response Endpoint: it structurally parses and correlates a
wallet's Authorization Response (`vp_token` + `state`, or `error` + `state`)
against a single-use presentation request. **It performs no signature,
credential, or issuer validation, and authenticates no user.**

**Request** (form-urlencoded): `state` (required), `vp_token`, `error`,
`error_description`.

**`200 OK`** — a transport-level acknowledgement: a JSON object, sent
`Cache-Control: no-store` (OID4VP 1.0 §8.2). For a **cross-device** request
the object is empty, `{}`, and the wallet is not required to do anything
further. For a request the user started as **same-device**, and for every account-link
request (linking is same-device only), it is
`{ "redirect_uri": "https://<issuer>/ui/wallet-login/return?response_code=<43 base64url chars>" }`
— an absolute URI under the issuer carrying a fresh, single-use Response Code,
which the wallet MUST redirect the user agent to (HAIP 1.0 §5.1); it is returned
on the accepted path and on a wallet-reported error alike. Either way the
acknowledgement confirms only that the response was well-formed and correlated.
It does **not** assert that any credential was verified or any user
authenticated — whoever follows the `redirect_uri` must also hold the browser
binder of the flow the code names, and the return route decides that, not this
body. Cross-device (QR) flows are unchanged by #405.

### `GET /oid4vp/request/{handle}`

**Flag-gated on the same variable, and registered only alongside the endpoint
above.** This is the JAR Request Object Endpoint (RFC 9101 §5.2.2, HAIP 1.0
§5.1): under a `VerifierProfile` that mandates signed Authorization Requests,
the wallet invocation URI carries a `request_uri` pointing here instead of the
request parameters inline, and the wallet fetches the signed request object from
it (#377).

**`200 OK`** — the compact JWS, served as `application/oauth-authz-req+jwt` with
`Cache-Control: no-store`. Its `x5c` header carries the Verifier's leaf
certificate and any intermediates, with the trust anchor excluded; `client_id`
is the base64url SHA-256 of that leaf.

**It consumes nothing and writes nothing.** The request `state` is not redeemed
here — a wallet may legitimately retry the fetch — so single use stays enforced
where it belongs, at `POST /oid4vp/response`. An unknown, expired or malformed
handle all produce the **same** bare `404`, so the endpoint is not an oracle for
which requests exist.

---

## See also

- [OAuth 2.1 Flow](/integrate/oauth-flow/) — worked flows with `curl`.
- [Hosted UI](/integrate/hosted-ui/) — the login, consent, and resume screens.
- [Agent Authorization](/integrate/agent-authorization/) — the agent-native layer
  (`is_agent`, Token Exchange, scope modes, step-up, audit).
- [Code Examples](/integrate/code-examples/) — runnable Node/TS and browser clients.
- [MCP Quickstart](/integrate/mcp-quickstart/) — protect an MCP server end-to-end.
- [`@qauth-labs/resource-guard`](https://github.com/qauth-labs/qauth/blob/main/libs/sdk/resource-guard/README.md) — the
  resource-server SDK that validates the tokens these endpoints issue.

---

# Code Examples

URL: https://docs.qauth.dev/integrate/code-examples/

Copy-paste-ready client code for QAuth. All snippets target a local instance at
`http://localhost:3000` (your `JWT_ISSUER`); override with an env var for other
environments. See the [API Reference](/integrate/api-reference/) for full endpoint
contracts and the [OAuth 2.1 Flow](/integrate/oauth-flow/) for the protocol details.

> **Never hard-code secrets.** Client secrets and passwords below are read from
> environment variables. Public clients (SPA / native / CLI) hold no secret and
> authenticate with PKCE instead.

---

## Node.js / TypeScript

Requires **Node 20+** (global `fetch`). Run any snippet with
`npx tsx example.ts`.

### 1. First-party: register → login → call a protected endpoint

Mirrors the [first-party auth endpoints](/integrate/api-reference/#first-party-authentication):
create a user, log in for tokens, then call a Bearer-protected endpoint
(`GET /api/clients`).

Registration answers every address with the same `202`, and a new account can
log in only once it is verified (the realm's
`accounts.requireVerifiedAccount`, on by default). So run the script once with `QAUTH_REGISTER=1`, open the link in the
email and confirm with the password, then run it again without the variable.

```ts
// first-party.ts
const QAUTH = process.env.QAUTH_URL ?? 'http://localhost:3000';
const email = process.env.QAUTH_EMAIL ?? 'dev@example.com';
const password = process.env.QAUTH_PASSWORD ?? 'corr3ct-h0rse-batt3ry'; // demo only

async function post(path: string, body: unknown, token?: string) {
  const res = await fetch(`${QAUTH}${path}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
    },
    body: JSON.stringify(body),
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok) throw new Error(`${path} → ${res.status}: ${JSON.stringify(json)}`);
  return json as any;
}

async function main() {
  // 1. Register, once. The answer is the same 202 whether or not the address
  //    already has an account; the next step arrives by email.
  if (process.env.QAUTH_REGISTER === '1') {
    const { message } = await post('/auth/register', { email, password });
    console.log(message);
    console.log('Open the link in the email, confirm, then run again without QAUTH_REGISTER.');
    return;
  }

  // 2. Log in → tokens. Until the address is verified this is the same 401 as a
  //    wrong password.
  const { access_token, refresh_token, expires_in } = await post('/auth/login', {
    email,
    password,
  });
  console.log(`logged in; access token expires in ${expires_in}s`);

  // 3. Call a protected endpoint with the bearer token.
  const res = await fetch(`${QAUTH}/api/clients`, {
    headers: { Authorization: `Bearer ${access_token}` },
  });
  const data = await res.json();
  console.log(`GET /api/clients → ${res.status}`, data); // { clients: [] } for a new user

  // 4. (Later) renew the access token without re-prompting:
  const renewed = await fetch(`${QAUTH}/oauth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token }),
  }).then((r) => r.json());
  console.log('refreshed access token:', renewed.access_token?.slice(0, 12), '…');
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});
```

### 2. Machine-to-machine: `client_credentials` → call a resource

For service clients (no user). The token is audience-bound (RFC 8707) and useless
at any other resource server. Provision the client with the `seed-oauth-clients`
script so it has the right `scopes` + `audience` (see the
[MCP Quickstart](/integrate/mcp-quickstart/#option-b--verify-the-handshake-with-curl-no-browser)).

```ts
// machine.ts
const QAUTH = process.env.QAUTH_URL ?? 'http://localhost:3000';
const RESOURCE = process.env.MCP_RESOURCE ?? 'http://localhost:8088';
const clientId = process.env.CLIENT_ID!; // e.g. "memory-mcp-demo"
const clientSecret = process.env.CLIENT_SECRET!; // from the seed script output

async function getToken(scope: string): Promise<string> {
  const basic = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
  const res = await fetch(`${QAUTH}/oauth/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${basic}`, // client_secret_basic
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      scope,
      resource: RESOURCE, // binds the token `aud` to this resource
    }),
  });
  if (!res.ok) throw new Error(`token → ${res.status}: ${await res.text()}`);
  const { access_token } = await res.json();
  return access_token;
}

async function main() {
  const token = await getToken('mcp:read');
  const res = await fetch(`${RESOURCE}/mcp/memory`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  console.log(`GET ${RESOURCE}/mcp/memory → ${res.status}`, await res.json());
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});
```

```bash
CLIENT_ID=memory-mcp-demo CLIENT_SECRET=<from seed output> npx tsx machine.ts
```

---

## Browser / JavaScript — Authorization Code + PKCE

A public SPA client (no secret) using the Web Crypto API for PKCE. Register the
client first with `token_endpoint_auth_method: "none"` and your `redirect_uri`
(see the [OAuth Flow, step 0](/integrate/oauth-flow/#0-prerequisites--a-client)).

The app calls the token endpoint and UserInfo from its own origin, so the
operator lists that origin in [`CORS_ORIGIN`](/operate/configuration/). The
sign-in itself is a redirect to `/oauth/authorize`, which answers no CORS
(OAuth 2.1 §3.1): never `fetch()` it.

```js
// auth.js — drop into a SPA; serves the redirect at /callback
const QAUTH = 'http://localhost:3000';
const CLIENT_ID = 'YOUR_PUBLIC_CLIENT_ID';
const REDIRECT_URI = window.location.origin + '/callback';
const SCOPE = 'openid profile email';
// No RFC 8707 `resource` here: this app calls QAuth's own UserInfo, which
// accepts a token whose `aud` is the app's client_id — the default when no
// `resource` is named. A token bound to another resource server is refused
// there (401). See /integrate/oauth-flow/#userinfo-oidc.

// --- PKCE helpers (RFC 7636) ---
function base64url(bytes) {
  return btoa(String.fromCharCode(...new Uint8Array(bytes)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}
function randomVerifier() {
  return base64url(crypto.getRandomValues(new Uint8Array(48))); // 64 chars
}
async function challengeFrom(verifier) {
  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
  return base64url(digest);
}

// --- 1. Begin login: redirect to /oauth/authorize ---
async function login() {
  const verifier = randomVerifier();
  const state = base64url(crypto.getRandomValues(new Uint8Array(16)));
  sessionStorage.setItem('pkce_verifier', verifier);
  sessionStorage.setItem('oauth_state', state);

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    code_challenge: await challengeFrom(verifier),
    code_challenge_method: 'S256',
    scope: SCOPE,
    state,
  });
  window.location.assign(`${QAUTH}/oauth/authorize?${params}`);
}

// --- 2. Handle the redirect back at /callback ---
async function handleCallback() {
  const url = new URL(window.location.href);
  const code = url.searchParams.get('code');
  const returnedState = url.searchParams.get('state');
  if (!code) return; // not a callback

  if (returnedState !== sessionStorage.getItem('oauth_state')) {
    throw new Error('state mismatch — possible CSRF');
  }
  const verifier = sessionStorage.getItem('pkce_verifier');

  const res = await fetch(`${QAUTH}/oauth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: REDIRECT_URI,
      client_id: CLIENT_ID, // public client: no secret
      code_verifier: verifier,
    }),
  });
  const tokens = await res.json();
  if (!res.ok) throw new Error(`token → ${res.status}: ${JSON.stringify(tokens)}`);

  sessionStorage.removeItem('pkce_verifier');
  sessionStorage.removeItem('oauth_state');
  return tokens; // { access_token, refresh_token, id_token, expires_in, token_type, scope }
  // id_token is present because SCOPE above includes `openid` — see
  // https://docs.qauth.dev/integrate/oauth-flow/#id-token-claims-oidc
}

// --- 3. Read the user's claims at UserInfo with the access token ---
async function callApi(accessToken) {
  const res = await fetch(`${QAUTH}/oauth/userinfo`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  // { sub, email?, email_verified? } — email claims are OMITTED when the
  // user has no verified email attribute. Always handle absence:
  //   const { sub, email } = await callApi(token);
  //   if (email === undefined) { /* no verified email on record */ }
  return res.json();
}

// Wire up: run handleCallback() on /callback, login() on a button click.
handleCallback().then((tokens) => {
  if (tokens) callApi(tokens.access_token).then((u) => console.log('user:', u));
});
```

> **Security notes.** Always validate `state` on return (CSRF). Keep the
> `code_verifier` out of the URL and in `sessionStorage`. For production SPAs,
> prefer storing tokens in memory and renewing via the
> [`refresh_token` grant](/integrate/oauth-flow/#refresh-token-rotation) over persisting
> long-lived tokens.

---

## See also

- [API Reference](/integrate/api-reference/) — full endpoint contracts.
- [OAuth 2.1 Flow](/integrate/oauth-flow/) — protocol walkthrough with `curl`.
- [`memory-mcp` example](https://github.com/qauth-labs/qauth/blob/main/libs/sdk/resource-guard/examples/memory-mcp/server.ts) —
  a runnable resource server protected by `@qauth-labs/resource-guard`.

---

# Agent Authorization

URL: https://docs.qauth.dev/integrate/agent-authorization/

> ADR-007 §2 · epic #181 · the agent-native authorization layer.

QAuth is an OAuth 2.1 authorization server for MCP servers and AI agents. The
[MCP Quickstart](/integrate/mcp-quickstart/) and [OAuth 2.1 Flow](/integrate/oauth-flow/) cover
the generic handshake any client uses. **This guide covers the agent-native
layer on top of it** — the five pieces that let an autonomous agent act _on
behalf of_ a user with bounded, auditable authority:

1. [**Agent client type** (`is_agent`)](#1-agent-client-type-is_agent) — marking a
   client as an agent, and why the flag is treated as untrusted.
2. [**Token Exchange** (RFC 8693)](#2-token-exchange-rfc-8693--on-behalf-of-delegation) —
   exchanging a user's token for a delegated one carrying an `act` (actor) claim.
3. [**Scope modes**](#3-scope-modes-readonly--admin--exec) — `agent:readonly` /
   `agent:admin` / `agent:exec` reserved scopes bounded by an operator-set cap.
4. [**Step-up authentication**](#4-step-up-authentication-before-dangerous-operations) —
   forcing fresh auth / re-consent before dangerous operations.
5. [**Per-agent audit**](#5-per-agent-action-audit) — what every delegated action
   records.

The unifying principle is **default-deny on untrusted input**: a client can
_claim_ to be an agent, but every capability that claim would unlock is gated by
an independent, server-side criterion. A client that omits `is_agent` to dodge
controls simply is not an agent and gets nothing extra; a client that asserts it
still cannot exceed what an operator provisioned for it.

---

## 1. Agent client type (`is_agent`)

An **agent** is an OAuth client whose `oauth_clients.is_agent` column is `true`.
There are three ways it is set, all of which write the same column:

| Path                                       | How                                                                                                                                                   |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dynamic Client Registration** (RFC 7591) | Send `"is_agent": true` in the `POST /oauth/register` body. Optional boolean, defaults to `false`; echoed back in the response as `"is_agent": true`. |
| **Client ID Metadata Documents** (CIMD)    | Include `"is_agent": true` in the hosted metadata document the `client_id` URL resolves to.                                                           |
| **Seed / operator provisioning**           | Set `"is_agent": true` on a client entry in the `seed-oauth-clients` manifest.                                                                        |

Register an agent via DCR:

```bash
curl -s -X POST http://localhost:3000/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "My Agent",
    "grant_types": ["client_credentials"],
    "response_types": [],
    "token_endpoint_auth_method": "client_secret_basic",
    "is_agent": true
  }' | jq
# → { "client_id": "…", "client_secret": "…", "is_agent": true, … }
```

> ℹ️ **Ask for the delegation grant explicitly.** The registration above gets you
> a client, but §2's on-behalf-of delegation additionally requires
> `urn:ietf:params:oauth:grant-type:token-exchange` in `grant_types` — `POST
> /oauth/token` gates delegation on `client.grantTypes.includes(...)`, so a
> client without it is refused with `unauthorized_client`:
>
> ```jsonc
> {
>   "client_name": "My Agent",
>   "grant_types": ["client_credentials", "urn:ietf:params:oauth:grant-type:token-exchange"],
>   "response_types": [],
>   "token_endpoint_auth_method": "client_secret_basic",
>   "is_agent": true,
> }
> ```
>
> Two constraints to know:
>
> - **The client must be confidential.** Token exchange authenticates the agent
>   through the confidential client-auth path, so
>   `token_endpoint_auth_method: "none"` is refused at registration rather than
>   at every exchange. On CIMD, where a client is public unless it publishes a
>   key set for `private_key_jwt`, the grant is dropped from the materialised row
>   instead — CIMD documents describe a client across every AS it talks to, so an
>   unusable-here grant is not an error.
> - **`response_types` must be `[]`** for a token-endpoint-only registration.
>   That is not specific to this grant — `client_credentials` alone needs it too,
>   because the normalizer refuses a `code` response type without the
>   `authorization_code` grant.
>
> Holding the grant confers no authority by itself. The exchange still requires a
> valid subject token you already hold, preserves-or-narrows its scope and
> audience, and clamps any reserved `agent:*` scope to the operator-set
> `max_agent_mode` — which self-registration never sets. See §2.
>
> _(Before #381 this was impossible: the grant was advertised and enforced but
> rejected by every provisioning path, so it had to be written straight into the
> `oauth_clients.grant_types` JSONB column.)_

### An agent's owner is a verified account

A registration that carries a developer's access token (the developer portal's
token, with `qauth:developer:write`) makes the developer the client's owner.
For an agent client that makes the developer the owner of an agent, and only a
**verified account** may own one (ADR-015 Decision 8). An account is verified
when the identity it was created with — its primary identity — is proved:

| The account was created with | It is verified when                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
| a password                   | the code mailed to its address was entered                                                        |
| a passkey                    | its registration checked the authenticator's user-verification flag                               |
| a wallet credential          | always: only QAuth's own verifier writes one                                                      |
| an upstream provider         | the realm still offers the provider, and the provider's "accounts count as verified" switch is on |

A credential added later never counts: an account created with an unconfirmed
address stays unverified after it adds a passkey. A password account is found
and reset by its address, so a key added later proves who holds the account but
not that the address is theirs; counting it would let someone who registered
another person's address keep the account from its owner. `REQUIRE_VERIFIED_ACCOUNT`,
which only decides whether an unconfirmed password account may sign in, plays
no part. Otherwise the registration is refused with `403`
`{"error": "access_denied"}`, no client is created, and the refusal is recorded
as the `user.agent_ownership_refused` event on the account, with the reason. A
registration with no token has no owner and is not checked.

### `is_agent` is self-asserted and untrusted

`is_agent` is **client-controlled input** — the client sets it in its own DCR
body or CIMD document. QAuth therefore **never trusts it alone**. It is read
through a fail-closed accessor (`isAgentClient(client)`, which is true only for
an explicit `isAgent === true`, never a missing/null value), and on its own it
gates nothing dangerous. Every agent capability requires a _second_,
**server-side** condition:

- **Token Exchange** additionally requires confidential-client authentication
  _and_ that the subject token was minted for this agent (see §2).
- **Scope modes** additionally require an operator-set `max_agent_mode` cap that
  covers the requested mode (see §3) — and that cap is **not** accepted from the
  client's own registration request.

The safe outcome is the same whether a client lies, omits, or sends a malformed
value: no agent privilege.

---

## 2. Token Exchange (RFC 8693) — on-behalf-of delegation

> On-behalf-of delegation is an MCP auth **extension**
> ([ext-auth](https://github.com/modelcontextprotocol/ext-auth)), not core MCP —
> QAuth provides it as a value-add.

An agent exchanges a user's access token (`subject_token`) for a **delegated**
access token whose `sub` remains the user and whose `act` (actor) claim
identifies the agent. Chained delegation nests `act` (RFC 8693 §4.1).

```bash
curl -s -X POST http://localhost:3000/oauth/token \
  -u "AGENT_CLIENT_ID:AGENT_CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token=USERS_ACCESS_TOKEN \
  -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d 'scope=read:docs' | jq
```

Response — `issued_token_type` is required by RFC 8693 §2.2.1:

```jsonc
{
  "access_token": "eyJ…", // sub = user, act = { "sub": "AGENT_CLIENT_ID" }
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "read:docs",
}
```

### Request parameters

| Parameter               | Required | Notes                                                                                         |
| ----------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `grant_type`            | yes      | Exactly `urn:ietf:params:oauth:grant-type:token-exchange`.                                    |
| `subject_token`         | yes      | The user's QAuth-issued access token (the party being acted for).                             |
| `subject_token_type`    | yes      | Must be `urn:ietf:params:oauth:token-type:access_token`. Any other type → `invalid_request`.  |
| `actor_token`           | no       | The acting party's token. When present, `actor_token_type` is **required** (RFC 8693 §2.1).   |
| `actor_token_type`      | cond.    | Required iff `actor_token` is sent; must be the access-token type, else `invalid_request`.    |
| `requested_token_type`  | no       | If present, must be the access-token type; anything else → `invalid_request`.                 |
| `scope`                 | no       | Space-separated; a **subset** of the subject token's scope. Omit to inherit the full set.     |
| `resource` / `audience` | no       | RFC 8707 / RFC 8693 targets; must fall **within** the subject token's `aud`. Omit to inherit. |

### The `act` claim shape

The delegated access token carries an RFC 8693 §4.1 `act` claim. The current
actor (the authenticated agent's own `client_id`) is the outermost `act`; any
pre-existing delegation chain on the subject token nests beneath it:

```jsonc
{
  "sub": "<user-id>", // the delegated token's subject stays the USER
  "act": {
    "sub": "AGENT_CLIENT_ID", // the agent acting now
    "act": { "sub": "UPSTREAM_AGENT_ID" }, // a prior actor, if re-exchanged
  },
}
```

The `act.sub` is always the **authenticated agent's** `client_id` — never a
value self-declared in an `actor_token`. Access tokens also carry a
`token_use: "access"` marker.

### Security model (default-deny)

These guarantees hold even against an attacker who has captured a user's token
and knows a public agent `client_id`:

- **Agent-only.** The client must be classified as an agent
  (`isAgentClient(client)`, fail-closed) **and** be granted the token-exchange
  grant type. Otherwise → `unauthorized_client`.
- **Confidential clients only.** Token exchange requires confidential client
  authentication (`client_secret_basic` / `client_secret_post`). A public agent
  (`token_endpoint_auth_method=none`) presents no secret and is rejected with
  `invalid_client`. This is a deliberate security floor (RFC 9700): on-behalf-of
  delegation must not be mintable by a client that proves only knowledge of a
  `client_id`.
- **Subject token must be bound to the agent.** The `subject_token` must verify
  as a QAuth-issued **access token** — EdDSA signature + `exp`, QAuth's own
  `iss`, and an access-token use marker (ID tokens and other JWTs are rejected
  with `invalid_request`) — **and** its `aud` must contain the requesting
  agent's `client_id`. Combined with the confidential-client requirement, this
  closes the unauthorized-delegation gap: a captured token alone is not enough.
  The subject user must also still exist and be enabled.
- **Scope and audience are narrowed, never widened.** A requested `scope` must
  be a subset of the subject token's scope (else `invalid_scope`); `resource` /
  `audience` must fall within the subject token's `aud` (else `invalid_target`).
- **Scope-mode cap still applies.** Any reserved `agent:*` scope that survives
  narrowing is additionally checked against the agent's server-side
  `max_agent_mode` (see §3), so a capped agent cannot launder a higher mode
  through delegation even when the subject token carried it. An over-cap scope
  **rejects the whole exchange** with `invalid_scope`; it is never silently
  reduced to the cap.
- **Lifetime never exceeds the subject token.** `expires_in` is clamped to
  `min(configured_lifespan, subject_token_remaining)`, so a delegated token can
  never outlast — or be re-exchanged to extend — the authority it derives from.
- **Bounded delegation depth.** Each re-exchange nests another `act`. The chain
  is capped at **4 actors**; a deeper request → `invalid_request`.
- **No refresh token** is issued — a delegated token is intentionally
  short-lived; the agent re-exchanges as needed.
- **Every exchange is recorded** as an event (success and failure), including
  the actor and delegation depth (see §5).

For copy-paste `curl` and the full error table, see the
[Token Exchange section of the OAuth 2.1 Flow guide](/integrate/oauth-flow/#token-exchange--agent-on-behalf-of-delegation-rfc-8693).

---

## 3. Scope modes (ReadOnly / Admin / Exec)

QAuth bounds what an agent can do with a small, opinionated capability taxonomy
layered over raw OAuth scopes, so operators get a coarse, legible control
instead of hand-curating scope strings.

### The taxonomy

| Mode     | Reserved scope   | Meaning                                          |
| -------- | ---------------- | ------------------------------------------------ |
| ReadOnly | `agent:readonly` | Read-only access                                 |
| Admin    | `agent:admin`    | Administrative; ranks above ReadOnly for the cap |
| Exec     | `agent:exec`     | Action-taking; the most privileged               |

Cap ordering — **which modes a client is allowed to request** — is **ReadOnly <
Admin < Exec**. A client whose maximum mode is `admin` may request
`agent:readonly` and/or `agent:admin`, but not `agent:exec`. The cap is a
**maximum**, not an exact match. This ordering is a provisioning ceiling only:
it says what a client may ask for, never that one granted scope stands in for
another.

The modes are plain OAuth scopes (`agent:*`), so the **existing** scope
machinery enforces them with no new claim system — the per-client allowlist and
`validateScopes` at the token endpoint, scope filtering at the authorize /
consent screens, and `@qauth-labs/resource-guard`'s resource-server scope checks. The
granted mode is therefore already visible to resource servers in the token's
`scope` set.

### The three modes are independent scopes, not a hierarchy

> **Corrected 2026-08-06.** This guide previously described `agent:admin` as
> "⊇ ReadOnly" and the ordering as "ReadOnly ⊂ Admin ⊂ Exec". **That reading is
> wrong at enforcement time**, and a client built on it will break.

The three reserved scopes are three ordinary, **independent** OAuth scopes. A
broader mode does **not** imply a narrower one:

- `@qauth-labs/resource-guard` matches scopes **exactly and case-sensitively** per
  RFC 6749 §3.3, with no hierarchical or prefix semantics (`missingScopes` in
  `libs/sdk/resource-guard/src/lib/scope.ts`). This is deliberate and is
  not changing.
- A token carrying only `agent:admin` therefore **does not** satisfy a route
  that requires `agent:readonly` — it gets a `403 insufficient_scope`, exactly
  as it would for any other unrelated missing scope.
- **A client that needs both must request both**, e.g.
  `scope=agent:readonly agent:admin`. Being capped at `admin` permits that
  request; it does not perform it for you.

`max_agent_mode` is a **maximum requestable ceiling**, not an implication
relation between the scopes.

### Enforcement: deny-by-default, untrusted `is_agent`

A reserved `agent:*` scope is granted **only** when **both** hold:

1. the client is classified as an agent via the fail-closed `isAgentClient`
   accessor (`isAgent === true`, never missing/null), **and**
2. the requested mode is within the client's **server-side** `max_agent_mode`
   cap.

`oauth_clients.max_agent_mode` is **operator-set server state** — provisioned
via the seed script or admin, and **never** accepted from a client's own
registration request (an escalation control must not be self-asserted). It is
**absent from the DCR request and response schemas entirely.** It defaults to
`NULL`, meaning **no agent mode is permitted**.

Consequences (all fail-closed):

- A client that **omits** `is_agent` is not an agent → **no** `agent:*` scope.
- A client with **no cap** (`NULL`) gets **no** `agent:*` scope — not even
  ReadOnly.
- An **unknown** stored mode parses to `null` and denies.
- A capped agent **cannot** obtain a higher mode (`admin`-capped → `agent:exec`
  rejected with `invalid_scope`).

### Where the cap is enforced

The cap is enforced on **every** path that can grant a reserved-mode scope, so
the control holds wherever the code is actually issued:

| Grant / surface           | Where                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| `/oauth/authorize`        | `findExceedingAgentScopesForClient` → `invalid_scope` redirect (fast path, prior consent covers). |
| `/ui/consent`             | The same gate on the POST (code issuance) **and** GET (render) — the common first-time path.      |
| `authorization_code`      | `enforceAgentScopeCap` on the code's scopes at redemption: a cap lowered after consent applies.   |
| `refresh_token`           | `validateScopes` on the refreshed scope set (allowlist and cap) before rotation.                  |
| `client_credentials`      | `validateScopes(scope, client.scopes, toAgentScopeContext(client))` in the token endpoint.        |
| Token Exchange (RFC 8693) | `enforceAgentScopeCap` against the narrowed scope set before the delegated token is minted.       |

Provision an agent with a cap via the `seed-oauth-clients` manifest:

```jsonc
{
  "realm": "master",
  "clients": [
    {
      "client_id": "my-agent",
      "name": "My Agent",
      // Only authorization_code / refresh_token / client_credentials validate
      // here — the manifest is checked against the `grant_type` pg enum. The
      // token-exchange URN fails validation; see the note under §1.
      "grant_types": ["client_credentials"],
      "scopes": ["agent:readonly", "agent:admin"],
      "token_endpoint_auth_method": "client_secret_basic",
      "is_agent": true, // self-asserted classification
      "max_agent_mode": "admin", // operator-set ceiling — agent:exec stays denied
    },
  ],
}
```

```bash
DATABASE_URL="postgresql://qauth:${DB_PASSWORD}@localhost:5432/qauth" \
  pnpm nx run infra-db:db:seed-oauth-clients -- --manifest=/path/to/manifest.json
```

---

## 4. Step-up authentication before dangerous operations

`resource-guard` emits the runtime `403 insufficient_scope` + `WWW-Authenticate`
challenge when a resource needs a scope the presented token lacks (shipped in
T1). The authorization-server half of that loop lives in `/oauth/authorize`:
when a client returns asking for an **increased** scope set, QAuth must not
silently widen an existing grant. Crossing into a more-privileged scope set is a
**step-up** — it requires a **fresh authentication** and/or **explicit
re-consent** (MCP 2026-07-28 incremental consent — the "Step-Up Authorization
Flow").

### What counts as "dangerous"

The classification is conservative and **server-side only** — never driven by a
client signal:

- any `write:*` scope (mutating access), and
- the higher agent modes **`agent:admin`** and **`agent:exec`** (both are
  action-taking). `agent:readonly` is **not** dangerous.

### The decision

Evaluated from the requested scopes versus what a prior consent already covers,
plus the standard OIDC `prompt` / `max_age` request parameters:

- **Any newly-requested scope** beyond a prior consent ⇒ **re-consent**
  required (never auto-widen).
- **`prompt=consent`** ⇒ re-consent even with no elevation.
- **Any dangerous scope being granted** — whether newly elevated _or_ already
  covered by a remembered prior consent ⇒ **fresh login** required. A
  state-changing capability is only granted right after the user proves
  presence; a stale grant cannot satisfy it, and no client opt-in is involved.
- **`prompt=login`** ⇒ fresh login.
- **`max_age`** present and the session is older than it ⇒ fresh login
  (`max_age=0` demands a brand-new authentication; second-granularity flooring
  makes the post-login round-trip terminate instead of looping).

For an operator-flagged first-party client the prior consent is its
administrative consent, the requested scopes minus the dangerous ones, so a
dangerous scope always asks for re-consent; a `native_backend` client's request
counts as `prompt=login` whatever it says
([Hosted UI](/integrate/hosted-ui/#a-first-party-client)).

### The 403 → re-authorize → retry loop

```
1. Agent calls the resource with a token lacking the needed (e.g. write/exec) scope.
   → resource-guard returns 403 insufficient_scope + WWW-Authenticate scope hint.
2. Agent re-runs /oauth/authorize requesting the larger scope set.
   → the agent scope-mode cap is checked first; an over-cap agent:* scope
     yields an invalid_scope redirect.
   → step-up evaluation decides fresh login / re-consent is needed.
3. User re-authenticates at /ui/login (and/or re-consents), creating a fresh session.
4. User returns to the original /oauth/authorize URL; the session is now fresh,
   step-up is satisfied, and the authorization code is issued.
```

### `prompt=none` (no UI allowed)

When the caller forbids UI but step-up would otherwise display a screen, the
authorize endpoint returns the matching OIDC error as an `error=` redirect
instead of silently elevating (OIDC Core §3.1.2.1):

| Condition                          | Error code             |
| ---------------------------------- | ---------------------- |
| A fresh authentication is required | `login_required`       |
| Only re-consent is required        | `consent_required`     |
| Generic interaction fallback       | `interaction_required` |

A fresh-login requirement takes precedence over a pending consent — the user
cannot consent before re-authenticating.

An agent client never skips the consent screen, even when a stored consent
covers the request: the screen names it as an AI agent and says how long it may
keep working ([Hosted UI](/integrate/hosted-ui/#an-ai-agent-client)). So
`prompt=none` from an agent answers `consent_required` whenever no fresh login
is needed (ADR-015 Decision 11).

For a client no operator provisioned (one registered through
`POST /oauth/register`, a Client ID Metadata Document or `POST /api/clients`),
these errors are shown on an issuer page with a link back to the client rather
than redirected automatically (RFC 9700 §4.11.2; see
[Errors](/integrate/oauth-flow/#errors)).

---

## 5. Per-agent action audit

Every agent-attributable action is recorded as an event in the event store
(`token.issued`, `token.request_failed`, `step_up.elevated`; see
[Events](/reference/events/)). The agent attribution lives in the envelope and
the event's `data`:

| Member                  | What it records                                                                                                                                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `subject`               | The end user the agent acted **on behalf of**. Absent for `client_credentials` (no subject user).                                                                                                                                                                        |
| `actor.id`              | The `client_id` **string** of the agent that performed the action. An event references no table, so the attribution survives deletion of the client row.                                                                                                                 |
| `actor.delegationChain` | The RFC 8693 `act` chain flattened to an ordered list of actor `client_id`s — the acting agent first, each following entry a prior actor. Absent when not delegated.                                                                                                     |
| `data.scopeMode`        | The effective agent scope mode (`readonly` \| `admin` \| `exec`) the action ran under — the highest-ranked mode present in the granted scope set. A rollup only: it does **not** imply the lower modes were granted. Absent when the action carries no agent-mode scope. |
| `data.delegationDepth`  | How many actors the `act` chain of the issued token holds.                                                                                                                                                                                                               |

What each grant attributes:

- **Token Exchange** — the subject is the user, the actor the agent with its
  delegation chain, `scopeMode` the highest granted agent mode. Failures are
  recorded too, as `token.request_failed` with the OAuth error and a reason
  code.
- **`client_credentials`** (agent acting as itself) — the actor is the client,
  with no chain and no subject user; `scopeMode` is set when the client is a
  verified agent. An ordinary (non-agent) machine client records **no**
  `scopeMode`.

**No tokens or secrets are ever recorded.** Only public client identifiers
reach an event — the `subject_token` / `actor_token`, client secrets and any
sensitive material never do, and the event contract's payload rules refuse an
event that would carry one.

The granted scopes (including every `agent:*` scope) are the event's
`data.scopes`; `scopeMode` is the rollup over them.

Before 0.2.0 these attributes were columns of the `audit_logs` table
(`actor_client_id`, `delegation_chain`, `scope_mode`). The table is read-only
since then; the upgrade copied its rows into the event store.

---

## See also

- [OAuth 2.1 Flow](/integrate/oauth-flow/) — the underlying endpoints with copy-paste
  `curl`, including the [Token Exchange](/integrate/oauth-flow/#token-exchange--agent-on-behalf-of-delegation-rfc-8693)
  section.
- [API Reference](/integrate/api-reference/) — endpoint contracts, including the
  `is_agent` DCR field and the token-exchange grant.
- [MCP Quickstart](/integrate/mcp-quickstart/) — end-to-end QAuth → MCP handshake.
- [ADR-007: MCP-First Positioning](/reference/records/adr/007-mcp-first-positioning/) — why the
  agent-native layer is QAuth's differentiation.
- [`@qauth-labs/resource-guard`](https://github.com/qauth-labs/qauth/blob/main/libs/sdk/resource-guard/README.md) — the
  resource-server SDK that emits the `403 insufficient_scope` step-up challenge.

---

# Wallet sign-in (OID4VP)

URL: https://docs.qauth.dev/integrate/wallet-login/

How an end user signs in with a wallet credential, what the server does at each
step, and what is deliberately not built yet. Implements
[ADR-004](/reference/records/adr/004-wallet-agnostic-federation/) and
[ADR-009](/reference/records/adr/009-wallet-account-resolution/) (issue #239).

> **Experimental.** Wallet sign-in is off by default, and every route it adds is
> tagged `x-qauth-stability: experimental` in the API reference. The verifier
> profile it has been validated on, `oid4vp-1.0-base`, is an
> [experimental item](/reference/experimental-features/#oid4vp-10-base): it may
> change in a minor release without a deprecation window, and the server logs a
> warning at boot while it is on.

> **Status (updated by #238): the sign-in completes, and a wallet credential can
> be linked to an existing account.** Presentation validation (#234), issuer
> trust (#236) and subject resolution (#300) are now wired end to end — see
> [The authentication seam](#the-authentication-seam) and
> [Account linking](#account-linking-238). A deployment additionally has to
> configure `OID4VP_ISSUER_JWKS` (whose key each issuer signs with) and
> `OID4VP_SUBJECT_BINDING_CLAIMS` (the entitlement check). Since #379 the second
> of those is a **boot requirement**, not a runtime one: a deployment with
> `WALLET_FEDERATION_ENABLED=true` and no usable subject-resolution
> configuration now **refuses to start**, naming the variable to set. It
> previously started and then refused every presentation.
>
> Claims normalization into `user_attributes` (#235) landed too: a validated
> credential's claims become `source='wallet'` attribute rows at every wallet
> sign-in.
>
> **Behaviour change (ANT-2026-NCX3VXDP, breaking).** `v0.1.0-rc.1` to
> `v0.1.0-rc.3` created an account when a wallet was presented on an identifier
> that had none. Wallet sign-in no longer creates accounts
> ([ADR-009](/reference/records/adr/009-wallet-account-resolution/) §1, amended
> 2026-10-19): that presentation is refused exactly like one on a taken
> identifier. Accounts created that way keep signing in. To give someone wallet
> sign-in, they sign in to their account and link the wallet
> ([Account linking](#account-linking-238)). Wallet-first sign-up arrives with
> the hosted sign-up pages
> ([ADR-017](/reference/records/adr/017-first-party-login/)).
>
> The whole flow is covered end to end against real containers and a mock wallet
> (#240) — see [End-to-end tests](#end-to-end-tests-and-the-mock-wallet-240).
> Interoperability with a REAL wallet remains **unverified**.
>
> **Since #405 the user says where the wallet is.** A sign-in started with
> **Use a wallet on this device** is finished on a browser return leg — the
> Response Endpoint hands the wallet a `redirect_uri` carrying a single-use
> Response Code (OID4VP 1.0 §8.2 / §14.2, HAIP 1.0 §5.1) and only the browser
> that started the flow can spend it; a sign-in started with **Scan with a
> wallet on another device** completes by polling exactly as before. See
> [The flow](#the-flow) and [ADR-013](/reference/records/adr/013-same-device-return-leg/).
>
> **Behaviour change (2026-11-07): linking is same-device only.** A wallet is
> linked to an account only from a browser on the same device as the wallet.
> The linking page has no QR code, and a request for the cross-device mode
> (`device=other`) is refused with `400` `validation_error`. A link flow
> started cross-device before the upgrade is refused when it is polled. Wallet
> sign-in keeps both modes. See [Account linking](#account-linking-238).

## Where it lives

The browser-facing screens are server-rendered by `apps/auth-server`, next to the
password login they extend:

| Path                                  | What it does                                                                                                                       |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `GET /ui/login`                       | Password form; offers a **Sign in with your wallet** link when the flow is usable                                                  |
| `GET /ui/wallet-login`                | Collects the account identifier the user asserts                                                                                   |
| `POST /ui/wallet-login`               | Issues an OID4VP request; `device=this` renders the deep link, `device=other` (or absent) the QR code                              |
| `GET /ui/wallet-login/:handle`        | Re-renders a flow in progress; the no-JavaScript refresh path                                                                      |
| `GET /ui/wallet-login/:handle/status` | Polled by the page; completes a cross-device sign-in when the wallet has responded, and a same-device one once its return leg has  |
| `GET /ui/wallet-login/return`         | The same-device **return leg** — the `redirect_uri` the wallet brings the browser back to, carrying the Response Code (#405)       |
| `GET /ui/wallet-link`                 | **Signed-in only.** Confirmation screen for linking a wallet credential (#238)                                                     |
| `POST /ui/wallet-link`                | Starts a linking flow for a wallet on this device; renders the deep link, never a QR code; refuses `device=other`                  |
| `GET /ui/wallet-link/:handle`         | Re-renders a linking flow; the no-JavaScript refresh path                                                                          |
| `POST /auth/link/wallet`              | JSON API: starts a linking flow (session cookie + `X-CSRF-Token`; optional `{ "device": "this" }`, `other` refused)                |
| `GET /auth/link/wallet/:handle`       | JSON API: polls; reports the outcome once the return leg has completed the link                                                    |
| `POST /oid4vp/response`               | The `response_uri` the **wallet** posts to (issue #233) — not a browser surface; answers `{ redirect_uri }` for a same-device flow |
| `GET /oid4vp/request/:handle`         | The `request_uri` a **wallet** fetches a signed request object from (#377)                                                         |

`libs/ui` is the React primitive set used by the developer portal; it is not
involved here.

## The flow

1. **The user asserts an account.** The identifier field is REQUIRED. ADR-009
   Decision §1: `asserted-lookup` is the universal default because no
   protocol-guaranteed stable wallet subject identifier exists, so **there is no
   usernameless wallet login**. The user says which account they mean; the
   presentation proves entitlement to it. The identifier is normalized exactly as
   the password provider normalizes an email, because it lands in the same
   `user_credentials.external_sub` column.

   It is never looked up at this step. Every submission renders the pending page
   — a QR code or a deep link — whether or not the account exists, so the screen
   is not an account oracle.

   The identifier must belong to an account the wallet was linked to. A
   presentation on an identifier with no account is refused exactly like one on
   an account the wallet is not bound to, and creates nothing, so the field can
   neither reveal which accounts exist nor claim one.

2. **The user says where the wallet is.** The identifier form has two submit
   buttons on the one form — **Use a wallet on this device** (`device=this`) and
   **Scan with a wallet on another device** (`device=other`). An absent field is
   cross-device, so anything built before #405 keeps the path it had. The
   choice is written atomically with the request: `same_device` on the
   request-state row and `sameDevice` on the flow record. A boolean names no
   browser, so the wallet-side row still cannot.

3. **The server issues a presentation request.** An OID4VP 1.0 Authorization
   Request (`response_type=vp_token`, `response_mode=direct_post`) is built under
   the active `VerifierProfile`, its `state` digest is persisted, and the pending
   page renders **exactly one** affordance for the wallet invocation URI: the
   **Open my wallet** deep link — a plain user-gesture `href` — for a
   same-device flow ("Opening your wallet on this device… When you're done,
   your wallet will bring you back here."), the QR code for a cross-device one
   ("Waiting for your wallet…"). Both carry a **Start again** link to a fresh
   flow with the other choice available. The URI itself is **opaque to the
   UI**: under `oid4vp-1.0-base` it carries the request inline; under a profile
   that mandates signed requests it is a `request_uri` reference to a signed JAR
   the wallet fetches from `GET /oid4vp/request/:handle` (#377). The page
   renders what the backend produced, and which form it is follows from the
   Client Identifier Prefix rather than from a setting.

4. **The wallet responds.** It posts the Authorization Response to
   `POST /oid4vp/response`, which redeems the single-use `state` and publishes a
   transport signal. That signal says a structurally valid `vp_token` came back —
   nothing about who presented it. The endpoint answers `200` with a JSON object
   (OID4VP 1.0 §8.2): `{}` for a cross-device flow, and for a same-device flow
   `{ "redirect_uri": "<issuer>/ui/wallet-login/return?response_code=…" }` — a
   fresh, single-use Response Code minted in the same statement that redeemed
   the row, on the accepted path **and** on a wallet-reported error (§8.2
   permits the member "for Error Responses"; HAIP 1.0 §5.1's MUST has no
   success qualifier).

5. **The browser is told — two ways.**
   - **Cross-device:** the page polls the status endpoint every three seconds.
     On completion it navigates to the original `return_to`; on any failure it
     shows one fixed sentence. Byte-for-byte the pre-#405 behaviour.
   - **Same-device:** the wallet follows the `redirect_uri`, in a **new** tab,
     to `GET /ui/wallet-login/return`. The route spends the code first (one
     guarded `UPDATE` — unknown, expired, replayed and cross-device codes all
     fail it identically), then matches the row against the flows this browser's
     signed binder cookie names, and only then runs the one state machine: the
     session is minted exactly as by polling and a "You're signed in" page tells
     the user to go back to the tab where they started — that tab's next poll
     consumes a done-marker and navigates to `return_to` on its own, so the
     OAuth client's `state` and PKCE verifier are still in the tab that
     continues. The poll **never** completes a same-device flow: it answers
     `pending` after the presentation arrives, and if the redirect has not
     landed within 180 s (the code's own lifetime) it rejects the presentation
     outright, with a reason in the log. A landing in a browser that does not
     hold the flow's binder — a different browser, an in-app browser with its
     own cookie jar, a replayed code — spends the code, discards the parked
     presentation, and the initiating tab is told `rejected`; the page it
     renders is one refusal page for every such case, with no "Try again".

## Scope decision — QR / deep link only

OID4VP 1.0 offers two ways to reach a wallet: the cross-device QR / same-device
deep link (the two `device` choices above), and the browser-native **Digital
Credentials API**, whose `origin:` Client Identifier Prefix is reserved for it.

**This ships QR/deep-link only.** The DC API path needs the `origin:` prefix,
which QAuth's client-identifier module does not implement. Signed requests are no
longer the blocker — #377 wired the ES256/JAR crypto from #298 into the request
path — but the missing prefix still is. Shipping half of it would mean an entry point
that works in one browser build and fails everywhere else. Because the invocation
URI is treated as opaque throughout, adding the DC API later changes what the
backend produces, not the structure of these screens.

## Fail-closed gating

The wallet entry point appears only when the deployment can actually serve the
flow. Every one of these turns it off — with no button rendered, rather than a
button that fails:

- `WALLET_FEDERATION_ENABLED` is off (default). The routes are not registered at
  all: the paths 404.
- No `VerifierProfile` is selected, or the selected one is not provisioned. There
  is never a fallback to the more capable profile (#296, LOCKED).
- The profile mandates SIGNED requests and the deployment provisioned no verifier
  signing material. Signing itself is built (#377): a deployment that configures
  the verifier's certificate chain, and holds the ES256 key the chain names in
  its key store, signs an `x509_hash`-identified request through the signer and
  delivers it by `request_uri`. Set `OID4VP_VERIFIER_SIGNING_KEY` for one boot
  of a process with the signer role and it is imported into the default
  realm's store (#546); the boot stops when the chain names no stored key.
  What is refused is the profile mandating signing with nothing to sign with.
- The profile signs its requests and the request's realm holds no active
  `oid4vp_request_signing` key the chain names. Keys are kept per realm, and
  the import lands in the default realm only, so under `haip-1.0` another
  realm's sign-in page offers no wallet login (#546). The unsigned
  `oid4vp-1.0-base` profile reads no key and is offered in every realm.
- The profile's response posture contradicts its permitted modes — a table
  entry requiring encryption while listing only plain `direct_post`, say. An
  encrypted response itself is never a reason: `direct_post.jwt` is built (#377
  Phase C) and needs nothing provisioned, because the ECDH-ES key is minted per
  request, published in `client_metadata.jwks`, and the private half rides the
  request-state row until the wallet's JWE arrives — and no longer: the same
  statement that consumes the row erases the key, so a consumed row can never
  decrypt its response again. While the row is live the stored key is sealed
  by the signer with the realm's `data_at_rest` key, bound to the row's `kid`
  (#546), so it opens only through the signer. `OID4VP_RESPONSE_KEY_SECRET`
  is read only to open rows a release before 0.2 wrote with it.
- The profile does not permit `dc+sd-jwt`, the one credential format QAuth ships
  an adapter for.
- `OID4VP_REQUESTED_VCT` is unset. A DCQL query with no type constraint asks a
  wallet for any credential it holds, which OID4VP 1.0 §15.6 warns Verifiers
  against.

## Configuration

| Variable                            | Default        | Notes                                                             |
| ----------------------------------- | -------------- | ----------------------------------------------------------------- |
| `WALLET_FEDERATION_ENABLED`         | `false`        | Registers the wallet provider and these routes                    |
| `OID4VP_VERIFIER_PROFILE`           | _(none)_       | `oid4vp-1.0-base`, or `haip-1.0` once fully provisioned (#377)    |
| `OID4VP_REQUESTED_VCT`              | _(none)_       | Comma-separated `vct` values; **no wallet flow without it**       |
| `OID4VP_WALLET_INVOCATION_ENDPOINT` | `openid4vp://` | The wallet Authorization Endpoint the QR and deep link target     |
| `OID4VP_VERIFIER_SIGNING_KEY`       | _(none)_       | ES256 request key, imported once into the key store (#546)        |
| `OID4VP_VERIFIER_CERTIFICATE_CHAIN` | _(none)_       | `x5c` chain, leaf first, **anchor excluded** (#377)               |
| `OID4VP_VERIFIER_TRUST_ANCHORS`     | _(none)_       | Anchors QAuth's OWN chain must terminate at (#377)                |
| `OID4VP_RESPONSE_KEY_SECRET`        | _(none)_       | Opens response keys stored before 0.2 only; remove after (#546)   |
| `OID4VP_TRUSTED_ISSUERS`            | _(empty)_      | Per-realm issuer allowlist (#236) — the opposite trust direction  |
| `OID4VP_ISSUER_JWKS`                | _(empty)_      | Issuer public JWKs (#234) — **nothing verifies without it**       |
| `OID4VP_SUBJECT_RESOLUTION`         | _(profile)_    | Account-resolution strategy (#300); defaults to `asserted-lookup` |
| `OID4VP_SUBJECT_BINDING_CLAIMS`     | _(none)_       | The entitlement check (#300) — **required to BOOT when enabled**  |
| `OID4VP_ISSUER_ASSURANCE`           | _(empty)_      | Per-realm issuer → eIDAS LoA (#237); drives the `acr` claim       |
| `OID4VP_ATTESTING_ISSUERS`          | _(empty)_      | Issuance chains that attest key storage (#308/#379)               |
| `OID4VP_EMAIL_VERIFYING_ISSUERS`    | _(none)_       | Issuers whose email is verified without `email_verified: true`    |
| `ACR_VALUE_STYLE`                   | `eidas-uri`    | Vocabulary the `acr` value is written in (#237)                   |

### Subject resolution is required to BOOT when wallet federation is on (#379)

`WALLET_FEDERATION_ENABLED=true` with **no** `OID4VP_SUBJECT_*` variables used to
start. It is now refused at startup, beside the issuer-allowlist and
credential-status gates, with the resolver's own message naming the variable.

This is a deliberate breaking change and it takes nothing away. The profile
default is `asserted-lookup`, and `asserted-lookup` with no binding claims has
nothing to match a presentation against — [ADR-009](/reference/records/adr/009-wallet-account-resolution/)
§1 calls that a total authentication bypass, so the server already rejected every
presentation. What changes is only where the operator finds out: a failed start
instead of a 100% login-failure rate. Set `OID4VP_SUBJECT_BINDING_CLAIMS` (and,
for `issuer-scoped-claim`, `OID4VP_SUBJECT_CLAIM` and
`OID4VP_SUBJECT_CLAIM_ISSUERS`), or turn `WALLET_FEDERATION_ENABLED` off —
which remains a clean boot with no wallet configuration present at all.

The **request path is unchanged**. A half-configured deployment that still
reaches it logs at `error` and returns the same uniform refusal a forged
credential gets; the boot gate replaces the operator's discovery channel and
changes nothing an anonymous caller can observe.

### Key-storage assurance (#308/#379)

An `OID4VP_ISSUER_ASSURANCE` entry may demand a minimum holder key storage with
`requiresKeyStorage: "hardware"`, optionally with a
`requiresKeyStorageAttackPotential` floor. Omitting the floor selects the strict
reading (`iso_18045_high`), because an unqualified `"hardware"` is asking for
eIDAS `high`'s secure cryptographic device.

The floor is refused unless `requiresKeyStorage` is `"hardware"`. It decides only
whether graded evidence reads as `hardware` or as `software`, and a `"software"`
requirement accepts either reading — so under `"software"` every floor in the
§D.2 vocabulary admits exactly the same evidence, and an operator who stated one
demanded nothing by it. A configuration that reads like a requirement and imposes
none is refused rather than ignored, the same way a floor stated with no
`requiresKeyStorage` at all is.

The evidence comes from `OID4VP_ATTESTING_ISSUERS` — the operator's record of
which issuance chains validate a wallet's key attestation per HAIP §4.5.1, and at
what grade. Recording an issuer there produces evidence, never a level: the realm
still has to name the issuer in its own `OID4VP_ISSUER_ASSURANCE` and accept it in
its own `OID4VP_TRUSTED_ISSUERS`.

**The recorded grade must clear the selected profile's own floor.** A profile
declaring `keyStorageAssurance: required` usually declares a minimum too —
`haip-1.0` requires `iso_18045_high` — and a deployment whose
`OID4VP_ATTESTING_ISSUERS` records nothing stronger than `iso_18045_basic` would
start and then refuse every presentation for attack potential below the minimum.
That is refused at startup instead, naming both the profile's floor and the
strongest grade recorded. The comparison takes the strongest, not the weakest: a
registry pairing a strong ecosystem with a weak one is a working deployment with
one ecosystem that will not reach the floor.

The recorded grade is a **cap**, not a default result. A recorded issuer may
lower it for one credential with an issuer-signed `key_storage` claim, and may
never raise it. A `key_storage` claim that cannot be ranked (an unknown value,
a bare string, an empty list, `null`) establishes no grade at all, so under
`haip-1.0` that credential is refused for attack potential below the minimum.

Key attestations conveyed **into a presentation** need wallet-provider trust
anchors, which have no configuration surface yet. Until they do, a conveyed
attestation is skipped rather than refused and the credential falls through to
the transitive path above — a wallet doing the more conformant thing must not be
worse off than one conveying nothing. It grants no more than the operator's
recorded claim, and the evidence still reports its source as `issuer-attested`.
The grade the skipped attestation states, and a `key_storage` claim beside it,
are still read (unverified) and can only lower that record: an attestation
stating `iso_18045_basic` does not clear the `haip-1.0` floor. One that cannot
be read, or states a grade that cannot be ranked, establishes no grade.

Note that `oid4vp-1.0-base` declares `keyStorageAssurance: forbidden`, so on the
base profile this machinery establishes nothing and changes no behaviour. It is
reachable under `haip-1.0`, whose posture is `required` at `iso_18045_high`, and
which boots once the verifier identity, an attesting-issuer registry and the
status-list pair are all provisioned (#377, #379). See
[ADR-010](/reference/records/adr/010-acr-assurance-mapping/) §5.

Three variables answer three different questions and must not be conflated:
`OID4VP_VERIFIER_PROFILE` is _who are we, to a wallet?_, `OID4VP_TRUSTED_ISSUERS`
is _which issuers does a realm accept?_, and `OID4VP_ISSUER_JWKS` is _which key
does an issuer sign with?_. Configuring a key grants no trust, and allowlisting
an issuer with no configured key can never verify anything — both directions fail
closed.

The `response_uri` is built on the issuer of the realm the sign-in page was
served for, so it is always the same origin that realm publishes as its issuer
identifier. So are the `request_uri` and the same-device return URI, for the same
reason. No request header decides any of them.

The three `OID4VP_VERIFIER_*` variables are a FOURTH question, and the only one
pointing outward: _how does QAuth prove who IT is to a wallet?_ Each has a
`_PATH` sibling. They are not token-issuance keys — the key configured here is
published nowhere, never reaches the JWT plugin, and cannot sign an access or ID
token, which `verifier-key-isolation.integration.test.ts` asserts. Unset all
three and the deployment runs the unsigned `redirect_uri` path, which is the
default; set SOME of them and the boot refuses, because a half-provisioned
verifier identity would otherwise fall back silently to a weaker one.

`OID4VP_WALLET_INVOCATION_ENDPOINT` accepts any wallet scheme — `openid4vp://`,
`haip://`, a vendor's `eudi-wallet://` or its `https://` universal link — but
**refuses to boot on a script-capable one** (`javascript:`, `data:`,
`vbscript:`, including case- and HTML-entity-encoded spellings). The value is
rendered into an `href`, so such a scheme would be a stored XSS payload served
to everyone who opens the sign-in screen; the render path re-checks it too.

## Assurance level and the `acr` claim

A wallet sign-in can tell a downstream application **how strong** the
authentication was. QAuth carries that as the OIDC `acr` (Authentication Context
Class Reference) claim of the ID token it issues to the client. The full decision
— including the research showing that no registered `acr` value for an eIDAS
Level of Assurance exists — is [ADR-010](/reference/records/adr/010-acr-assurance-mapping/).

### What a downstream application sees

| Authentication                                        | `acr` in the ID token                    |
| ----------------------------------------------------- | ---------------------------------------- |
| Password login                                        | **absent**                               |
| Wallet login, issuer not in `OID4VP_ISSUER_ASSURANCE` | **absent**                               |
| Wallet login, issuer assured `substantial`            | `http://eidas.europa.eu/LoA/substantial` |
| Wallet login, issuer assured `high`                   | `http://eidas.europa.eu/LoA/high`        |

(Values shown for the default `eidas-uri` style; under `loa-name` they are the
bare strings `substantial` and `high`.)

**The absence of `acr` is the signal for "no higher assurance was established".**
It is never emitted with a "low" value, so an RP may treat presence alone as "this
session came from an assured credential" and compare the value when it needs a
specific level:

```js
// Require an eIDAS "high" wallet credential for a sensitive operation.
if (idTokenClaims.acr !== 'http://eidas.europa.eu/LoA/high') {
  // Re-authenticate, or refuse.
}
```

`acr` is bound to the authorization code at `/oauth/authorize` time and rendered
at `/oauth/token`, so it reflects the authentication that actually backs the code
— not the moment the token was requested. Refresh rotation and RFC 8693 token
exchange issue no ID token, so neither can launder an `acr` value.

### Where the level comes from

Not from the wallet. OID4VP 1.0 §5 fixes the response type to `vp_token`, so
there is no wallet-signed assertion for a level to travel in, and HAIP 1.0 §1
states that the profile alone does not reach LoA `high`. The level is a property
of the **issuer**: which issuer signed the credential, under which trust anchor,
and which credential type it is. An operator states that in
`OID4VP_ISSUER_ASSURANCE`, per realm, and QAuth evaluates it against the
credential #234 validated — **after** the #236 trust gate has already refused an
untrusted issuer.

Listing an issuer in `OID4VP_ISSUER_ASSURANCE` does **not** make it trusted. The
two variables answer different questions and an issuer must appear in both.

### Reachable as of #240

`resolveWalletPresentation` now returns an authenticated user, so a completed
wallet login does produce a level and the resulting ID token carries `acr`. The
E2E suite asserts both its presence and its absence, and that the password login
still carries no `acr` with wallet federation on or off.

This requires `WALLET_FEDERATION_ENABLED=true`; with the flag off the routes are
never registered and no wallet login exists to produce a level.

## Security properties

- **Login CSRF.** The identifier form carries the same signed double-submit
  `__Host-` CSRF cookie the password form uses, checked before any presentation
  request is minted.
- **Browser binding.** A flow handle is unguessable, but unguessable is not bound:
  a handle can be mailed. A separate signed `__Host-qauth_wallet_flow` cookie is
  minted on the POST that creates the flow and required on every read, so an
  attacker cannot start a flow, present their own credential and hand the victim a
  URL that signs the victim in as the attacker.
- **Single use, and short.** The presentation request expires in five minutes and
  its `state` redeems exactly once, in one guarded `UPDATE`. Every terminal
  outcome deletes the flow record and the wallet signal, so nothing can be polled
  or replayed afterwards.
- **Session fixation.** A fresh session id is minted on every successful
  authentication, exactly as the password login does.
- **Response Code / same-device session binding.** For a flow started with
  `device=this`, the Response Endpoint's `redirect_uri` carries a fresh 32-byte
  Response Code whose SHA-256 digest is written in the same statement that
  redeems the request (only the digest is stored); the return route spends it
  in one guarded `UPDATE` **before** looking at the browser, then requires the
  flow's binder cookie as well — two cryptographically random values, one
  managing state with the wallet and one proving the browser, which is OID4VP
  1.0 §14.3.3's second option. The poll never completes such a flow (§14.2:
  the frontend MUST pass the Response Code), so the poll and the return leg
  cannot race. A code that lands anywhere is dead everywhere: a return in a
  different browser or user session spends it and discards the presentation
  (HAIP 1.0 §5.1), and a redirect never followed rejects it at the 180 s
  deadline. The code rides a query parameter so the `<noscript>` twin keeps
  working; in return every response of the route is `Cache-Control: no-store`
  and `Referrer-Policy: no-referrer`, both terminal pages scrub it from the
  address bar with a nonced `history.replaceState`, and the request log
  redacts `response_code`. The cross-device sign-in flow has no equivalent —
  §14.2 says the technique is not applicable there — and leans on the browser
  binder and the asserted identifier instead. Linking is same-device only. See
  [ADR-013](/reference/records/adr/013-same-device-return-leg/).
- **One refusal.** Expired request, wallet-reported error, unvalidatable
  presentation, untrusted issuer, unknown account and disabled account all render
  the same sentence. "Unknown account" includes an identifier with no account at
  all, which is never enrolled. #236 requires that an untrusted issuer be indistinguishable
  from a malformed presentation; on a login screen, distinguishing "no such
  account" from "credential rejected" would hand any anonymous visitor an account
  oracle. The specific reason is logged server-side only.
- **CSP.** The polling script is the only inline script the server emits and it
  carries the per-request nonce; `script-src` stays `'self'` with no
  `'unsafe-inline'`. The QR code is inline SVG with presentation attributes, so no
  style relaxation is needed either.

## Accessibility and language

The screens follow the existing login/consent pattern: `lang="en"`, labels
wrapping their controls, `aria-describedby` on the identifier hint, `role="alert"`
on errors, an `aria-live="polite"` status region for the wait, an `aria-label` on
the QR image, and a `<noscript>` path that refreshes the same flow server-side.
QAuth has no i18n framework today; when one lands, these strings localize with the
rest of the sign-in copy.

## The authentication seam

`apps/auth-server/src/app/helpers/wallet-presentation.ts` is the single point
where a presentation becomes a session or a linked credential. Five gates run,
in this order, and none of them is optional:

1. **#234 — presentation validation.** Issuer signature, every Disclosure digest,
   the validity window, and the Key Binding JWT bound to this request's `nonce`
   and this Verifier's `client_id`.
2. **#236 — issuer trust.** A validated credential from an issuer the realm does
   not trust is a forgery with extra steps.
3. **#237 — assurance.** The realm's `OID4VP_ISSUER_ASSURANCE` policy is read
   AFTER the trust gate, never before: an untrusted issuer and an unassured
   trusted issuer both resolve to `low`, so reading a level first would say
   "authenticated at low assurance" where the answer is "not authenticated".
4. **#300 — subject resolution.** ADR-009 §1 requires verifying that the presented
   credential matches the binding stored for the **asserted** account; without
   that check anyone holding any valid credential could sign in as anyone.
5. **#235 — the account and its claims.** `helpers/wallet-account.ts` signs in
   the account the strategy matched — never a new one — and writes the
   credential's claims as attributes.

Steps 1 and 2 are composed in one function, `verifyWalletPresentations`
(`@qauth-labs/fastify-plugin-federation`), precisely so a caller cannot wire up
only the first — the first produces a plausible-looking `ValidatedCredential`
with claims in it, which is exactly the object someone in a hurry would use.
The trust question is asked inside validation, as soon as the issuer's
signature has verified and BEFORE the key-storage and credential-status gates
act on what the issuer wrote. An issuer whose key is pinned in
`OID4VP_ISSUER_JWKS` but whom the realm does not trust therefore never gets a
status-list URI fetched, nor a failed fetch counted against the status endpoint
breaker that every other issuer's users share.

### Where the bytes come from, and what they are checked against

The wallet posts to an endpoint nobody authenticated (`POST /oid4vp/response`,
OID4VP 1.0 §8.2 — a wallet has no client credentials). That endpoint decides
nothing: it redeems the single-use `state`, structurally parses the `vp_token`,
and **parks** the presented bytes under the `state` digest. Validation then runs
on the cookie-bound browser poll — or, for a same-device flow, on the
cookie-bound return leg that also carries the Response Code — where the session
and the asserted identifier exist, and where the expensive signature work is not
on an anonymous surface.

Everything a presentation is CHECKED AGAINST — the `nonce`, the `client_id`, the
DCQL query, the realm — lives on the browser-side flow record. A wallet can
choose what it presents and nothing about what makes a presentation acceptable.

## Account linking (#238)

An existing user (typically a password account) can attach a wallet credential to
the account they are **already signed in to**, producing a second
`user_credentials` row (`provider_type='wallet'`) under the same `users.id`. That
is ADR-004's account-linking model and ADR-009 §5's `session-binding` strategy.

It has to be a separate, session-bound flow because ADR-009 §1's second bootstrap
case forbids the alternative:

> An account already exists without a wallet binding (typically a password
> account on the same email) — the presentation MUST NOT silently create one.
> Allowing it would let any holder of any trusted credential claim an existing
> account by asserting its email.

So `asserted-lookup` **refuses** such an account at login, and linking is how its
owner — proven by their session, not by the presentation — opts in.

Linking is also the only way a wallet gets an account today. Wallet sign-in
never creates one (ADR-009 §1, amended 2026-10-19), so a person who has only a
wallet first creates an account, signs in, and links the wallet here. Wallet-first
sign-up arrives with the hosted sign-up pages (ADR-017).

Two entry points, both requiring a session: the server-rendered screens at
`/ui/wallet-link` (confirmation → open the wallet → outcome, the same chrome as
the sign-in screens) and the JSON API at `POST /auth/link/wallet` for a
first-party settings UI. QAuth ships no account-management page today, so
`/ui/wallet-link` is the affordance a deployment links to from its own account
screen.

### Same device only

A wallet is linked only from a browser on the **same device** as the wallet
([ADR-013](/reference/records/adr/013-same-device-return-leg/), amended
2026-11-07). Wallet sign-in still offers both devices; linking does not.

- The confirmation form has one button, **Use a wallet on this device**
  (`device=this`). The pending page renders the **Open my wallet** deep link
  and no QR code.
- The wallet answers `POST /oid4vp/response` and is handed a `redirect_uri`
  carrying a single-use Response Code. The link completes when the wallet
  brings the **same browser**, signed in as the same account, back to
  `GET /ui/wallet-login/return`. The poll never completes a link: it answers
  `pending`, then the outcome once.
- A request for the cross-device mode is refused. `POST /auth/link/wallet`
  with `{ "device": "other" }`, or the form posting `device=other`, answers
  `400` `validation_error` with `errors` naming `/device`. An absent `device`
  means same-device.
- A link flow started cross-device before the upgrade is answered `rejected`
  when it is polled, and nothing is linked.

A person whose wallet is on their phone signs in on the phone and links it
there. After that, wallet sign-in works from any device, the QR included.

### What gets written

| Column            | Value                                                                |
| ----------------- | -------------------------------------------------------------------- |
| `user_id`         | the session's `users.id`                                             |
| `provider_type`   | `wallet`                                                             |
| `external_sub`    | the identifier the account already owns — read from its password row |
| `credential_data` | `{ wallet_binding, issuer, vct }`                                    |

`external_sub` is deliberately the same value `PasswordProvider` fills (ADR-009
§1), which is what makes a later wallet login resolve back to **this** account:
both credentials key on one identifier, so either sign-in mints a token with the
identical `sub`. Under `issuer-scoped-claim` it is instead the digest of
`(validated issuer, disclosed claim)`.

`wallet_binding` is a digest over the validated issuer, the `vct` and the
configured `OID4VP_SUBJECT_BINDING_CLAIMS` values — never the claim values in the
clear. It is what a later `asserted-lookup` login re-derives and compares in
constant time.

A binding claim (or the `issuer-scoped-claim` subject claim) that is a JSON
**number** takes part only when it is an integer within ±(2^53 − 1). Larger
integers and fractions are rounded when the credential is parsed, so two
holders' different numbers could become one. Such a claim is treated as withheld.
An issuer with longer identifiers must sign them as strings. An account enrolled
on such a value before this rule no longer matches. Each refusal for this reason
logs a `warn` line that names the claim (never its value).

Re-linking a re-issued credential **updates** the row the account already owns; a
row belonging to a different account is never overwritten.

### Duplicate detection is strategy-scoped, and usually unavailable

#238 originally asked for "reject linking a wallet already bound to a different
`users.id`". ADR-009's Negative consequences record that this lost its premise:
there is no stable, unique per-wallet identifier. So the check runs **only** under
`issuer-scoped-claim`, where `(validated issuer, disclosed claim)` supplies one.
Under `asserted-lookup` it is not performed, not approximated and not asserted —
a check that keyed on the asserted account identifier would tell an operator
their wallets are unique when they are not.

The shipped `uniqueIndex(realm_id, provider_type, external_sub)` still prevents
two rows sharing an `external_sub` under either strategy. That is a key
collision, not wallet duplicate detection.

### Security properties specific to linking

- **A session is the entire authority.** Every linking surface requires a live
  `__Host-qauth_session` cookie; there is no identifier field, because the account
  is the session's and a second answer could disagree with the cookie.
- **The session is re-read at completion**, and must be the SAME user who started
  the flow — a handle captured from a shared screen cannot be finished by a
  different signed-in user.
- **Modes do not cross.** A flow is `login` or `link`, and each completion path
  refuses the other's handle. Completing a link flow on the login path would sign
  a browser in as the linking user with no credential of that account checked.
- **Same device only.** A link completes only on the return leg, with the
  Response Code the wallet brought back to the signed-in browser. A link flow
  not recorded as same-device is refused by the state machine and again by the
  writer, before the presentation is read (see [Same device only](#same-device-only)).
- **CSRF.** The JSON `POST` takes the per-session `X-CSRF-Token` header (the same
  token `GET /consents` returns); the UI form takes the signed double-submit
  login-CSRF cookie.
- **One exception to the uniform refusal.** `conflict` is reported distinctly,
  because the caller is authenticated and acting on their own account, so it
  enumerates nothing they could not already establish. Every other failure renders
  the same sentence.

### Subject resolution (#300) and the account store

`@qauth-labs/server-federation`'s `subject/` module ships the
`SubjectResolutionStrategy` seam ADR-009 specifies: `asserted-lookup` (the
default), `issuer-scoped-claim` (opt-in per named issuer, with the mandatory
fallback), and `session-binding` (the linking path, #238). `key-thumbprint` and
`rp-pseudonym` are reserved ids that refuse with the gate that blocks them.

A deployment selects one with `OID4VP_SUBJECT_RESOLUTION` and configures the
entitlement check with `OID4VP_SUBJECT_BINDING_CLAIMS`; unset means "the active
`VerifierProfile`'s default", which is `asserted-lookup` for both shipped
profiles. `resolveSubjectResolution` folds the fail-closed assertions in, so a
half-configured selection throws rather than quietly building a weaker strategy —
and the seam turns that throw into the same uniform refusal, logging the reason.

#238 supplied the inputs the strategy was waiting for: `resolve()` consumes a
`ValidatedCredential` (now produced by the verification seam above) and a
`SubjectAccountLookup` — the account-store port that answers "which accounts in
this realm does this asserted identifier resolve to, and what wallet binding does
each carry". The adapter over `user_credentials` is
`apps/auth-server/src/app/helpers/wallet-account-lookup.ts`.

Two properties of that adapter are load-bearing. It returns rows across **every**
provider type, so a password account with no wallet binding stays visible and is
refused as an account that exists, rather than looking like "no account". And it
lets a database failure propagate, because the strategy contains it and turns it
into the same uniform refusal — swallowing it here would turn a broken database
into "no such account".

When the identifier resolves to several accounts and at least one carries a
wallet binding, `asserted-lookup` sets aside the accounts that carry none
before it looks for the sole account. An anonymous `POST /auth/register` can
add an unbound password account on a wallet-only user's email. Counting that
account would lock the wallet owner out. Two bound accounts, or several unbound
ones, are still `ambiguous`, and the remaining account still has to pass the
binding comparison.

Under `issuer-scoped-claim` the asserted identifier still names the account
(ADR-009 §2, amended 2026-11-07). The `(validated issuer, claim)` subject finds
the account the holder's wallet is linked to, and the identifier the user typed
must name that same account, normalized and looked up exactly as
`asserted-lookup` does. An identifier that names another account, or none, is
refused with the same answer as any other non-match, after the same lookups.
No credential claim is used to find an account. A sign-in with no usable
identifier is refused before any lookup.

Note the boot posture, deliberately unchanged: selecting a strategy is **not** a
startup gate. A deployment that names a strategy and omits its settings fails at
`resolveSubjectResolution` on the request path — logged as an operator error and
rendered as a refusal, never as a distinct status an anonymous caller could
drive.

The login path **never** enrols (ADR-009 §1, amended 2026-10-19). `no-match` —
no account for the asserted identifier — is refused exactly like `ambiguous` and
`rejected`, after the same single lookup, and writes nothing
(`helpers/wallet-account.ts`). Until that amendment it enrolled: the presentation
established a new account, bound to whoever presented, on the identifier they
typed. That answered "free" differently from "taken", which revealed wallet-only
accounts to any holder of a trusted credential, and it let that holder claim
someone else's identifier (ANT-2026-NCX3VXDP). `rejected` still carries ADR-009's
second bootstrap case, an account that exists for the identifier with no
matching wallet binding; signing in there would be the account takeover the ADR
names.

The same seam also resolves the assurance level (#237) — it returns an optional
`assuranceLevel` alongside the user, and everything downstream of it (the browser
session, the authorization code, the ID token's `acr` claim) is already wired for
it.

## VC claims normalization (#235)

A validated credential's claims become `user_attributes` rows with
`source='wallet'`, `verified=true`, and `expires_at` taken from the credential's
own `exp` (NULL when it carries none, so an attribute never outlives the
credential asserting it). `'wallet'` is the top of ADR-002's trust order, so a
verified wallet email outranks any `self_reported` one in
`helpers/email-claims.ts`.

The **email row is the exception**. It is written `verified=true` only when the
presentation discloses `email_verified: true`, or when the credential's issuer
is listed in `OID4VP_EMAIL_VERIFYING_ISSUERS`. A disclosed
`email_verified: false` always leaves it unverified. An absent flag does not
count as verified: in SD-JWT VC the holder chooses the Disclosures, so a missing
flag may be an `email_verified: false` the holder left out. An unverified email
row is never emitted as an `email` claim.

> **Behaviour change (ANT-2026-BGP7XCR2).** Earlier releases treated an absent
> `email_verified` as verified. An issuer that signs no flag at all (typical for
> a PID) now yields no `email` claim downstream unless the operator lists it in
> `OID4VP_EMAIL_VERIFYING_ISSUERS`. List only issuers that never issue an
> unverified address. Rows already stored as verified are rewritten at the
> user's next wallet sign-in.

Three properties are worth knowing before extending it:

- **The mapping is per credential format.** SD-JWT VC and ISO mdoc use different
  names for the same attribute — the EUDI PID's SD-JWT VC encoding carries
  `birthdate`, its mdoc encoding `birth_date` (ADR-009 Finding 1) — so
  `libs/server/federation/src/claims/` carries a claim-adapter registry with one
  adapter per format. `mso_mdoc` is deliberately absent and is REFUSED rather
  than served by the SD-JWT path.
- **The claim table is an allowlist.** `SD_JWT_VC_ATTRIBUTE_CLAIMS` names every
  claim that may become an attribute; anything else produces no row. Issuer trust
  bounds who may write, the table bounds what they may write. Claims left out on
  purpose — `nationalities` (an array), `address` (structured), `portrait` (a
  biometric), the attestation metadata — are recorded with their reason in
  `SD_JWT_VC_UNMAPPED_CLAIMS`.
- **`external_sub` is never derived from the credential.** It is whatever the
  subject-resolution strategy resolved. The wallet `credential_data` row records
  the format, the validated issuer, the credential type and the wallet binding —
  a digest, so the account is matchable without a second copy of the person's
  attributes sitting in the column.

### What a wallet attribute rests on, and when it is withdrawn

Each `source='wallet'` row records its **provenance** in
`user_attributes.provenance` (migration 0022): the validated issuer and the
issuer-signed `status` reference of the credential that wrote it. Two rules use
it.

- **At every emission** (token grants, userinfo, password sign-in), a wallet row
  is asserted only while the account's realm still trusts its issuer. Removing
  an issuer from `OID4VP_TRUSTED_ISSUERS`, or turning `WALLET_FEDERATION_ENABLED`
  off, stops its attributes from being emitted at once. The next source in the
  trust order answers instead, or the claim is omitted. This check is local; it
  makes no outbound request. Wallet rows written before migration 0022 carry no
  provenance and are withheld until the account's next wallet sign-in rewrites
  them.
- **At the account's next wallet sign-in**, every verified wallet row that the
  presentation did not rewrite is checked again against the same gates a
  presentation meets: issuer trust and credential status. A row whose credential
  no longer reads `VALID` on its status list is set `verified=false`, and so is
  a row whose issuer is no longer trusted. That covers a revoked credential
  whose replacement the holder presents without the old claim. A status list
  that cannot be read counts as a failure (fail-closed).

**Not covered:** credential status is not re-checked on the token or userinfo
paths, because that would put a status-list fetch on every token grant. After an
issuer revokes a credential, the attributes it wrote keep being emitted (through
a password sign-in or a refresh token) until the account's next wallet sign-in,
the credential's own `exp`, or the operator removing the issuer from trust,
whichever comes first. Tokens already issued are not affected.

## End-to-end tests and the mock wallet (#240)

The whole stack is exercised against a real Postgres, a real Redis and a mock
wallet in `apps/auth-server/src/app/wallet-federation.integration.test.ts`, run
by `pnpm nx test-integration auth-server` (Docker required) and by CI's
`integration` job. It covers the refusal of a presentation on an identifier with
no account (identical to one on a taken identifier, and creating nothing), a
linked wallet's first and returning sign-ins, the ADR-009 §1 takeover attempt,
untrusted-issuer rejection (including an issuer removed from trust), account
linking, `acr` presence and absence, the password-login regression, the
fail-closed posture with no `VerifierProfile`, and the `vp_token`-keyed-by-DCQL-id
contract. Every scenario that signs a wallet in links it to a password account
first, through `linkWalletToNewAccount` in `src/testing/e2e-harness.ts`.

The wallet is `apps/auth-server/src/testing/mock-wallet.ts`. It is built on
`@qauth-labs/core-crypto` and `jose` and imports nothing from the verifier, so
the E2E is an interoperability test rather than a round trip through QAuth's own
encoder. It parses the authorization request off the wire, evaluates the DCQL
query, and dispatches presentation building through a per-format table with
`dc+sd-jwt` present and `mso_mdoc` deliberately absent — so an mdoc wallet is a
new table entry, not a rewrite.

The mock wallet also verifies a SIGNED request the way a real one would (#377):
it parses the `request_uri` reference, fetches the JAR, checks the `x5c` chain
against a trust anchor it holds **out of band** — never one the request carried —
and checks `client_id` against the digest of the leaf before verifying the
signature. That path is exercised by `helpers/wallet-login-request.test.ts`.

A `haip-1.0` suite runs alongside it (`wallet-federation-haip.integration.test.ts`,
#377 Phase C): the same wallet fetches and verifies the signed JAR, reads the
per-request encryption key out of its `client_metadata`, encrypts the whole
Authorization Response to it with `jose` directly, and posts one `response`
parameter — which the intake finds by the JWE `kid`, consumes, decrypts and
carries through to a session. It also proves what the encrypted mode adds: a
replayed `response` is refused because its row was consumed, a response
encrypted to a key QAuth never published is refused after consuming the row,
and the same presentation posted in the clear is refused. The boot-gate half
still asserts that a half-provisioned `haip-1.0` takes the deployment DOWN,
naming the key-storage assurance count rather than any count #377 cleared.

Both suites also drive the same-device return leg (#405) on their profile: a
sign-in started with `device=this` whose mock wallet parses the `redirect_uri`
out of the acknowledgement and follows it with the initiating browser's cookie
jar, landing on the signed-in page and proving the session through the original
jar once its poll has consumed the done-marker; a wrong or replayed code
refused; a landing from a fresh cookie jar refused, with the initiating poll
answering `rejected` and no session minted; a redirect never followed, with the
poll pending until the deadline and rejected after it; a cross-device sign-in
(`device` omitted) acknowledged with `{}` and completed by polling exactly as
before; and the link flow, which is same-device only: the base suite also
pins that a cross-device link is refused at both starts, and that a
cross-device link flow left from before the upgrade is refused on its poll. The
mock wallet's acknowledgement parser is I/O-free and imports nothing from the
verifier.

Interoperability with a REAL wallet is unverified, and which wallets implement
HAIP 1.0 is an open research question. The procedure for a manual pass — and the
place to record findings — is
[docs/wallet-interop-manual-validation.md](https://github.com/qauth-labs/qauth/blob/main/docs/wallet-interop-manual-validation.md).

---

# Account API from a backend

URL: https://docs.qauth.dev/integrate/account-api-backend/

The [account API](/reference/account-api/) is called by backends that hold a person's access
token: the account console's backend, or any backend for frontend (BFF) that lets a person manage
their own account. This page is for the people who write one. The contract lists every operation;
this page explains the one guard every call passes, and what a BFF does with each answer.

## The token

Ask for the token with the [authorization code flow and PKCE](/integrate/oauth-flow/), naming the
account API as the RFC 8707 resource:

```http
GET /oauth/authorize?response_type=code&client_id=account-console
    &redirect_uri=https%3A%2F%2Faccount.example.com%2Fcallback
    &scope=openid%20qauth%3Aaccount%3Aread%20qauth%3Aaccount%3Awrite
    &resource=urn%3Aqauth%3Aaud%3Aaccount%3Av1-rc.0
    &code_challenge=…&code_challenge_method=S256&state=…
```

- The client must list `urn:qauth:aud:account:v1-rc.0` in its `audience`. A client that does not
  gets `invalid_target`; an operator provisions the console's client with it.
- The token needs the account scope of each operation's `x-qauth-class`: `qauth:account:read` to
  read, `qauth:account:write` to change anything. Ask for both when the BFF does both; the write
  scope does not reach a read. The client must hold them in its `scopes`, which only an operator
  writes, and the token endpoint issues them only to a client that lists the account audience. A
  call without the scope it needs gets 403 `forbidden` with
  `WWW-Authenticate: Bearer realm="OAuth", error="insufficient_scope", scope="qauth:account:write"`,
  before any rule below: a new sign-in does not help, a token with the scope does.
- The token's only audience is the account API. Keep it on the server side, as every BFF keeps its
  tokens; no cookie authenticates a call.
- It carries how the person signed in: `auth_time` (when) and `amr` (with what: `pwd`, `pop` for a
  passkey, `otp` for an authenticator app, `mfa` for two kinds). A token from the code exchange
  also names the browser session it came from, in `sid`. A token from a refresh does not: its
  family records no session.

## Fresh authentication

An operation whose `x-qauth-fresh-authentication` is not `none` changes a credential, an
identifier, the contact address or a linked account, or deletes the account. It needs a sign-in at
most 300 seconds old whose `amr` holds the account's strongest bound factor: `pop` when the
account has a passkey, else `otp` when it has an authenticator app, else `pwd`. A disabled factor
still counts.

When the token does not meet that, the call is refused before anything changes, with the step-up
challenge of [RFC 9470](https://www.rfc-editor.org/rfc/rfc9470.html) §3:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication", max_age="300"
Content-Type: application/problem+json

{"type":"https://docs.qauth.dev/reference/problem-types/#insufficient-user-authentication","title":"Insufficient user authentication","status":401,"code":"insufficient_user_authentication","trace_id":"…","max_age":300}
```

- `max_age="300"`: the sign-in is too old, or the token says nothing of when it happened, or it
  dates the sign-in more than a minute ahead of the server's clock.
- `max_age="0"`: the sign-in is recent but lacks the strongest factor. The person signs in again
  now.
- A DPoP-bound token gets the same challenge under the `DPoP` scheme, with the proof algorithms in
  `algs`.

To answer it, send the person to `/oauth/authorize` with the same request and `max_age` set to the
challenge's value, exchange the new code, and repeat the call with the new token. The sign-in that
follows ends with the account's strongest bound factor, since a sign-in completes only once it has
proved it. Read `max_age` from the problem document or the header; both carry the same value.

## After a lost factor

A person who lost their passkey or authenticator app signs in with a recovery code in its place. A
recovery code adds no `amr` value, so such a sign-in never meets the rule above. It counts only for
the two halves of a rebind, the operations whose `x-qauth-fresh-authentication` is
`strongest-factor-or-recovery-code`: removing a passkey or the authenticator app
(`account.passkeys.delete`, `account.totp.delete`) and binding a new authenticator app
(`account.totp.enrollment.create`, `account.totp.enrollment.confirm`). Every other operation
answers the challenge with `max_age="0"`.

The guard finds the recovery code through the token's `sid`: the browser session records that its
sign-in took one. So make the rebind calls with the token of that sign-in's code exchange, within
the five minutes; a refreshed token names no session and gets the challenge.

## Refusals a step-up cannot lift

- **403 `delegated_token_refused`**: the token is an act-chain token (RFC 8693 `act`), held by an
  admin or an agent acting for the person. Every operation that changes a credential, an
  identifier, the contact address or a linked account refuses one, and so do deleting the account
  and reporting a sign-in as not the person's (`x-qauth-act-chain: refused`). The refusal comes
  before any fresh-authentication check, and no sign-in lifts it: only the person, with their own
  token, may make the change.
- **503 `service_unavailable`** with `Retry-After`: the guard could not read what it decides on,
  the account's factors or the session. Nothing changed; try again after the given seconds.

Every refusal is recorded as a
[`request.account_operation_refused`](/reference/events/#requestaccount_operation_refused-v1-rc0) event,
with the operation, the reason, the factor the sign-in needed and the challenge's `max_age`. The
security log a person reads leaves it out: a refused change changes nothing on the account.

---

# Operate

URL: https://docs.qauth.dev/operate/

This lane is for teams self-hosting and operating a QAuth instance.

---

# Docker Guide

URL: https://docs.qauth.dev/operate/docker/

This guide covers the Docker setup for QAuth: **production** (prod build, no watch) and **development** (dev image, Compose Watch + `nx serve --watch`).

## Overview

QAuth uses Docker Compose to orchestrate the following services:

| Service              | Image                | Purpose                                                  |
| -------------------- | -------------------- | -------------------------------------------------------- |
| **postgres**         | `postgres:18-alpine` | Primary database (PostgreSQL 18 with `uuidv7()` support) |
| **redis**            | `redis:7-alpine`     | Session cache and rate limiting                          |
| **migration-runner** | Custom               | Applies the pending database migrations, then exits      |
| **auth-server**      | Custom               | Main authentication API server                           |
| **developer-portal** | Custom               | TanStack Start web UI for registration/login/consents    |

Compose builds the three custom images from source. Each release also
publishes the `migration-runner` and `auth-server` images, signed and
attested, so a deployment can pin their digests instead of building them:
see [Published images](/operate/images/).

### Production vs development

| Use case        | Compose file(s)                                 | Service image                                | Watch                |
| --------------- | ----------------------------------------------- | -------------------------------------------- | -------------------- |
| **Production**  | `docker-compose.yml`                            | `Dockerfile` (multi-stage prod build)        | No                   |
| **Development** | `docker-compose.yml` + `docker-compose.dev.yml` | `Dockerfile.dev` (deps + source, dev server) | Yes (sync + rebuild) |

Both `auth-server` and `developer-portal` follow this convention: a multi-stage
`Dockerfile` for production and a `Dockerfile.dev` for the watch-based dev flow.

## Prerequisites

- Docker **23.0+** (BuildKit on by default) or earlier Docker with `DOCKER_BUILDKIT=1` set. The auth-server and migration-runner Dockerfiles use `# syntax=docker/dockerfile:1.7` and a `--mount=type=cache` pnpm-store mount, both of which require BuildKit.
- Docker Compose 2.0+
- Docker Compose **2.24.4+** for development (`docker-compose.dev.yml` uses the `!reset` merge tag; `--watch` needs 2.22+)
- OpenSSL (for generating JWT keys)

## Quick Start

### 1. Generate JWT Keys

QAuth uses EdDSA (Ed25519) for JWT signing. Generate a key pair:

```bash
# Generate private key
openssl genpkey -algorithm Ed25519 -out private.pem

# Extract public key
openssl pkey -in private.pem -pubout -out public.pem
```

See the [Keys guide](/operate/keys/) for RS256 and ML-DSA key generation, and
why to generate PKCS#8 keys with `openssl genpkey`.

### 2. Configure Environment

```bash
# Copy the example environment file
cp .env.docker.example .env

# Edit .env and add your JWT keys
# The keys should include the BEGIN/END lines
```

Example `.env` content:

```bash
DB_PASSWORD=your_secure_password

JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIKx...
-----END PRIVATE KEY-----"

JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA...
-----END PUBLIC KEY-----"

JWT_ISSUER=http://localhost:3000

# The key-encryption key: openssl rand -base64 32. Back it up apart from the
# database backups: losing it loses every stored key.
KEK=...
```

> **Set a KEK.** At its first boot the server imports the JWT keys and
> `SESSION_COOKIE_SECRET`, when set, into the realm's encrypted key store,
> wrapped with `KEK`, and refuses to start without one. See
> [the key store](/operate/keys/#the-key-store).
>
> **`SESSION_COOKIE_SECRET` is optional.** The session cookie is signed with
> the realm's cookie key in the key store, which the first boot generates. Set
> it only to keep the secret a deployment already signs with.

> **The JWT keys are optional.** Tokens are signed with the realm's keys in
> the key store. Set `JWT_PRIVATE_KEY` to keep the key a deployment already
> signs with; leave it unset and the first boot generates the keys.
> `JWT_PUBLIC_KEY` is derived from the private key when unset. See
> [the key store](/operate/keys/#the-key-store).

### 3. Start Services

**Production** (prod build, no watch):

```bash
docker compose up -d
docker compose logs -f
```

**Development** (dev image, Compose Watch, `nx serve --watch`; requires Docker Compose 2.24.4+):

```bash
# In .env: NODE_ENV=development, LOG_LEVEL=debug
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --watch
```

- Sync: changes in `apps/auth-server/` and `libs/` are synced into the container; `nx serve --watch` rebuilds and restarts.
- Rebuild: changes to `package.json`, lockfile, `nx.json`, etc. trigger a full image rebuild.
- See [Compose file watch](https://docs.docker.com/compose/file-watch/).

### 4. Verify Setup

```bash
# Check all services are healthy
docker-compose ps

# Test the auth-server readiness endpoint
curl http://localhost:3000/ready
```

Expected response:

```json
{
  "status": "ok",
  "roles": ["web", "api", "admin", "signer", "delivery"],
  "checks": {
    "database": { "status": "ok" },
    "redis": { "status": "ok" },
    "kek": { "status": "ok" },
    "outbox": { "status": "ok" }
  }
}
```

`/ready` answers `503` with the failing check while a dependency is down;
`/health` answers `200` while the process runs, whatever its dependencies do.
See [Health and readiness](/operate/observability/#health-and-readiness).

The developer-portal has no dedicated health endpoint (see
[Developer Portal](#developer-portal) below); confirm it's up by opening
`http://localhost:3001` in a browser, or checking that Compose reports its
container `healthy`:

```bash
docker compose ps developer-portal
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Docker Network                          │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │   postgres   │  │    redis     │  │ migration-runner │   │
│  │   :5432      │  │    :6379     │  │   (runs once)    │   │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘   │
│         │                 │                   │              │
│         │  health check   │                   │ waits for    │
│         │  dependency     │                   │ postgres     │
│         ▼                 ▼                   ▼              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                    auth-server                          │  │
│  │                      :3000                              │  │
│  │  Waits for: postgres (healthy), redis (healthy),       │  │
│  │             migration-runner (completed)                │  │
│  └───────────────────────────┬────────────────────────────┘  │
│                              │ health check dependency        │
│                              ▼                                 │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                 developer-portal                        │  │
│  │                      :3001                              │  │
│  │  Waits for: auth-server (healthy). Calls it server-     │  │
│  │  side at http://auth-server:3000 over the network.      │  │
│  └────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## Service Details

### PostgreSQL

- **Image**: `postgres:18-alpine`
- **Port**: 5432 (mapped to host)
- **Database**: `qauth`
- **User**: `qauth`
- **Features**: `uuidv7()` native support (PostgreSQL 18+)

Connect via psql:

```bash
docker exec -it qauth-postgres psql -U qauth -d qauth
```

### Redis

- **Image**: `redis:7-alpine` (Redis 7)
- **Port**: 6379 (mapped to host)

Connect via redis-cli:

```bash
docker exec -it qauth-redis redis-cli
```

### Migration Runner

A dedicated service that applies the pending database migrations before
auth-server starts.

- The image holds Node and one bundled program with the migrations beside it:
  no pnpm, nx or drizzle-kit. It reads `DATABASE_URL`, and the optional
  system-client and database-user variables below.
- It takes a Postgres advisory lock, so a second runner waits, then finds
  nothing to do. It logs each migration it applies with its duration.
- It exits `0` when the database is current, whether it applied migrations or
  found none pending, and non-zero with a message naming the failed migration
  otherwise; a failed run rolls back. The exit codes are on the
  [Upgrades](/operate/upgrades/) page.
- Exits after completion (restart: "no"); auth-server waits for it to complete
  successfully.

Run migrations manually, or only check what is pending:

```bash
docker-compose run --rm migration-runner
docker-compose run --rm migration-runner --check
```

The auth server also checks at boot: when the database lacks migrations of its
release, it waits up to `DB_MIGRATION_WAIT_MS` (60 seconds) for the runner,
then exits naming them.

> Upgrading an existing deployment past the ADR-002 identity migration
> (0011)? Read the [Upgrades runbook](/operate/upgrades/) before running this
> — that migration is destructive and has a required backfill precondition.

#### The system client

The developer portal signs in through the **system client**, the client named
by `SYSTEM_CLIENT_ID` (`system` by default) in the default realm. The operator
provisions it
([ADR-017](/reference/records/adr/017-first-party-login/) phase F0): a
`private_key_jwt` client with the portal's public keys, the first-party profile
`web_redirect` and the portal's callback as its redirect URI. Set these on the
migration runner, and every run provisions it once the migrations are applied:

| Variable                     | Required                          | Meaning                                                                             |
| ---------------------------- | --------------------------------- | ----------------------------------------------------------------------------------- |
| `SYSTEM_CLIENT_REDIRECT_URI` | to provision                      | The portal's callback: `https`, or `http` on a loopback address for a local portal. |
| `SYSTEM_CLIENT_JWKS_URI`     | one of the two, with the callback | An `https` URL of the portal's JWK Set.                                             |
| `SYSTEM_CLIENT_JWKS`         | one of the two, with the callback | The portal's JWK Set inline, as JSON: public keys only.                             |
| `SYSTEM_CLIENT_ID`           | no                                | The system client's id, `system` by default. The same value as on the auth server.  |
| `DEFAULT_REALM_NAME`         | no                                | The realm, `master` by default. The same value as on the auth server.               |

- Without `SYSTEM_CLIENT_REDIRECT_URI` the runner leaves the system client
  alone. A key variable set without it, or the callback without exactly one key
  variable, is a usage error (exit `2`) and the runner does nothing at all.
- The runner rewrites only the authentication method, the keys, the redirect
  URI, the `authorization_code` and `refresh_token` grants, PKCE and the
  profile. The row keeps its id, name, scopes, audience and an operator's
  suspension, so tokens issued under it before stay valid. A second run with
  the same values changes nothing.
- A new deployment has no realm yet when the runner first runs: the auth server
  creates it at its first boot. The runner reports that and still exits `0`;
  run it once more after that boot, or provision through the seed manifest's
  `system_client` section (see
  [First-party clients](#first-party-clients-adr-017)).
- A row named by `SYSTEM_CLIENT_ID` that a developer owns, an agent, or a
  dynamic or CIMD registration can never be first party: the runner names it,
  changes nothing and exits `4`.

Until the system client is provisioned, the portal's sign-in still works: the
auth server creates a placeholder that holds no secret and no key, and so
authenticates nowhere.

#### The roles' database users

A split deployment can give each service role a Postgres user of its own,
with only the grants the role needs
([#498](https://github.com/qauth-labs/qauth/issues/498); see
[Topology](/operate/topology/#one-user-per-role)). Create the users, then name
them to the migration runner, whose `DATABASE_URL` stays the owner of the
tables. Every run then gives each user exactly the grants of its roles once
the migrations are applied:

| Variable           | Meaning                                     |
| ------------------ | ------------------------------------------- |
| `DB_USER_WEB`      | The database user the `web` role uses.      |
| `DB_USER_API`      | The database user the `api` role uses.      |
| `DB_USER_ADMIN`    | The database user the `admin` role uses.    |
| `DB_USER_SIGNER`   | The database user the `signer` role uses.   |
| `DB_USER_DELIVERY` | The database user the `delivery` role uses. |

- None of them set, the runner grants nothing: every role connects as the one
  user, which owns the tables. That is the single deployment's default.
- Set one, set all five: roles that run in one process name the same user. A
  partial set, or a name Postgres would cut short (over 63 bytes), is a usage
  error (exit `2`), and the runner does nothing at all.
- The grants are applied in one transaction under the migration lock: each
  user's grants on the schema are revoked, the map's are granted, and the run
  commits only once every user holds exactly them. A second run gives the same
  grants.
- A user that does not exist, a superuser, the owner of the tables or a member
  of the owner, a user with `REPLICATION`, `CREATEROLE` or a predefined role
  that reads past the grants, or a user that would still hold more through
  `PUBLIC` or any role it is a member of, fails the run (see
  [Topology](/operate/topology/#one-user-per-role)): the runner names it,
  leaves the grants as they were and exits `5`, the migrations applied.

### Auth Server

The main authentication API server.

- **Port**: 3000 (mapped to host)
- **Health Check**: `GET /ready` in `docker-compose.yml`: the container is
  `healthy` once Postgres, Redis, the KEK and the event delivery queue
  answer. The image's own
  `HEALTHCHECK` calls `GET /health`, liveness only, for a runtime that
  restarts an unhealthy container.
- **Metrics**: `GET /internal/metrics` on the internal listener,
  `127.0.0.1`, port `3443`, inside the container, never on port 3000 (see
  [Observability](/operate/observability/#who-can-read-the-metrics)).
- **Production**: `Dockerfile` → a `pnpm deploy --prod` bundle, started by
  `docker-entrypoint.sh` via `exec tsx src/main.ts`
  (`apps/auth-server/docker-entrypoint.sh:5`).
- **Development**: `Dockerfile.dev` → `pnpm nx serve auth-server --watch`; use with `docker-compose.dev.yml` and `--watch`.

### Developer Portal

The TanStack Start web UI for user registration, email verification, login, and
OAuth consent management. It renders server-side and calls the auth-server only
from its server functions — tokens never reach the browser.

- **Port**: 3001 (mapped to host)
- **Health Check**: a raw TCP connect check on port 3001
  (`docker-compose.yml`, `developer-portal.healthcheck`) — liveness only, and
  does **not** depend on the auth-server being reachable. The portal build has
  no dedicated `/healthz` route, so there is nothing to `curl`.
- **Production**: `Dockerfile` → runs `node server/index.mjs`, the
  self-contained server the build emits (see below).
- **Development**: `Dockerfile.dev` → `pnpm nx dev developer-portal` (Vite dev
  server); use with `docker-compose.dev.yml` and `--watch`.
- **Depends on**: `auth-server` (healthy).
- **Address**: fixed at `172.30.80.10` on the Compose network, so the
  auth-server's `TRUST_PROXY` can name it (see Production Considerations
  below). If Compose reports that an existing `qauth-network` must be
  recreated, run `docker compose down` once (named volumes are kept).

The portal is built by TanStack Start's Vite plugin alone, which emits a
**self-contained, self-listening** Node server at
`dist/apps/developer-portal/server/index.mjs` (a small srvx server,
`apps/developer-portal/src/node-entry.ts`, with every runtime dependency bundled
in) plus static assets under `public/`. The production image's runner
stage just copies `server/` and `public/` and runs `node server/index.mjs` — no
separate `pnpm deploy` step is needed (`apps/developer-portal/Dockerfile`).

> **Build context note:** the portal source is excluded from the auth-server /
> migration-runner build contexts by the root `.dockerignore` (see the build
> note below). The portal image lifts that exclusion for its own build via a
> sibling `apps/developer-portal/Dockerfile.dockerignore`, which BuildKit
> prefers over the root file when present. No action is needed — this is wired
> up already.

Open the portal at `http://localhost:3001` once the stack is up. Set a
`PORTAL_SESSION_SECRET` in `.env` first (see Environment Variables). A
developer who signs up there can log in only after confirming the address from
the emailed link, so the stack needs a mail provider that delivers (see the
note under Environment Variables).

## Common Operations

### Rebuild Images

**Production:**

```bash
docker compose up -d --build
# Or rebuild a single service
docker compose build auth-server && docker compose up -d auth-server
docker compose build developer-portal && docker compose up -d developer-portal
```

Build the portal image directly (from the repo root, BuildKit on):

```bash
DOCKER_BUILDKIT=1 docker build -f apps/developer-portal/Dockerfile -t qauth-developer-portal .
```

**Development:** use `docker compose -f docker-compose.yml -f docker-compose.dev.yml up --watch`; sync/rebuild is automatic. For dependency or config changes, the dev setup will rebuild the auth-server image when those files change.

### View Logs

```bash
# All services
docker-compose logs -f

# Specific service
docker-compose logs -f auth-server

# Last 100 lines
docker-compose logs --tail=100 auth-server
```

### Stop Services

```bash
# Stop all services (keeps data)
docker-compose stop

# Stop and remove containers (keeps volumes)
docker-compose down

# Stop and remove everything including volumes
docker-compose down -v
```

### Reset Database

```bash
# Remove postgres volume and restart
docker-compose down -v
docker-compose up -d
```

### Shell Access

```bash
# Auth server
docker exec -it qauth-auth-server sh

# PostgreSQL
docker exec -it qauth-postgres sh

# Redis
docker exec -it qauth-redis sh
```

## Environment Variables

> **The Compose `environment:` map is an allowlist.** The `auth-server` service
> in `docker-compose.yml` configures itself through an explicit `environment:`
> map. There is no `env_file:`, no bind mount of the repo into the container, and
> the root `.dockerignore` excludes `.env` from the build context — so the
> container never reads `.env` itself. Compose reads `.env` only to resolve the
> entries **the map already contains**. A variable the map does not name resolves
> to its schema default inside the container no matter what `.env` says,
> silently.
>
> Every variable documented on this page is on that map, so `.env` works for all
> of them. Entries take one of two forms: `VAR: ${VAR:-default}` restates a
> default in the file, while a bare `VAR:` is a null value that Compose resolves
> from `.env` (or the shell) and omits entirely when unset, letting the schema
> default apply without this file having to track it. Prefer the bare form when
> adding a variable — restating defaults in two places is what let them drift
> apart before.

See `.env.docker.example` for all available variables. Key variables:

| Variable                       | Required | Description                                                                                                                                                      |
| ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_PASSWORD`                  | Yes      | PostgreSQL password                                                                                                                                              |
| `JWT_PRIVATE_KEY`              | No       | EdDSA private key (PEM format), imported into the realm key store; unset, the first boot generates the signing keys                                              |
| `JWT_PUBLIC_KEY`               | No       | EdDSA public key (PEM format); derived from the private key when unset                                                                                           |
| `KEK`                          | Yes      | Key-encryption key, the base64 of 32 random bytes; wraps every key in the realm key store (or `KEK_PATH`, a file holding it, mounted into the container)         |
| `JWT_ISSUER`                   | No       | JWT issuer URL (default: http://localhost:3000). At first boot it becomes the default realm's permanent issuer; a later boot with another value refuses to start |
| `DEFAULT_REALM_ENDPOINT_HOSTS` | No       | Names server-side callers reach the auth-server by (default: `auth-server`, the developer portal's)                                                              |
| `EMAIL_PROVIDER`               | No       | Email provider of a new realm: mock, resend, smtp (default: mock); the realm row decides afterwards                                                              |
| `REQUIRE_VERIFIED_ACCOUNT`     | No       | Refuse password login until the account is verified (`true`), in a new realm; the realm row decides afterwards                                                   |
| `NODE_ENV`                     | No       | `production` (default) or `development` for dev                                                                                                                  |
| `LOG_LEVEL`                    | No       | `info` (default); use `debug` for development                                                                                                                    |

> **The `mock` email provider delivers nothing, and a new account cannot sign in
> until its address is verified.** `REQUIRE_VERIFIED_ACCOUNT` defaults to `true`
> since 2026-10-19: with it off, registering an address and then logging in
> with the chosen password would tell a free address from a registered one. A
> stack on `EMAIL_PROVIDER=mock` therefore cannot complete a sign-up. Point
> `smtp` at a real server or a local mail catcher. For a throwaway local trial
> only, `REQUIRE_VERIFIED_ACCOUNT=false` in `.env` before the first start lets
> unverified accounts sign in, and gives that answer back. It seeds the default
> realm's `accounts.requireVerifiedAccount` when the realm is created: on a stack
> that already started once, the realm keeps its stored value, so remove the
> volumes (`docker-compose down -v`, which deletes all data) to start over with it.

#### Developer Portal

| Variable                 | Required | Default                   | Description                                                                           |
| ------------------------ | -------- | ------------------------- | ------------------------------------------------------------------------------------- |
| `PORTAL_SESSION_SECRET`  | Yes      | —                         | 32+ char secret signing the portal session cookie                                     |
| `PORTAL_SESSION_TTL`     | No       | `900`                     | Session cookie lifetime in seconds                                                    |
| `PORTAL_AUTH_SERVER_URL` | No       | `http://auth-server:3000` | Base URL the portal uses (server-side) to reach auth-server                           |
| `QAUTH_NETWORK_PREFIX`   | No       | `172.30.80`               | Compose network `/24` (first three octets); the portal is `<prefix>.10`               |
| `PORTAL_TRUST_PROXY`     | No       | _(unset)_                 | Address of a reverse proxy in front of the portal (single addresses, comma-separated) |

Generate a secret with `openssl rand -hex 32`. The portal will not start without
`PORTAL_SESSION_SECRET`.

For **development** with `docker-compose.dev.yml`, set `NODE_ENV=development` and `LOG_LEVEL=debug` in `.env`.

### Client ID Metadata Documents (CIMD)

CIMD is the recommended MCP client-registration mechanism (see [ADR-007](/reference/records/adr/007-mcp-first-positioning/)) — MCP Authorization 2026-07-28 says authorization servers and MCP clients **SHOULD** support it, and deprecates RFC 7591 dynamic registration in its favour. When a `client_id` is an HTTPS URL, the auth-server fetches and validates the client's metadata document on demand instead of persisting a registration record. All settings have safe defaults — none are required to run.

Whether a realm accepts CIMD clients, and from which hosts, is the realm's own policy: `registration.cimd.enabled`, `trustPolicy` and `trustedDomains` on [Realm policies](/reference/realm-policies/) ([#534](https://github.com/qauth-labs/qauth/issues/534)). The authorization, consent and token endpoints and the realm's discovery documents read it off the realm row, so two realms of one deployment can differ. `CIMD_ENABLED`, `CIMD_TRUST_POLICY` and `CIMD_TRUSTED_DOMAINS` only seed it, for a new realm and for a realm that had no policies at the first boot after the upgrade that put them on the row: a later change of them leaves every existing realm as it is (see [Changing a realm's CIMD policy](#changing-a-realms-cimd-policy)). The cache, size and timeout settings stay the deployment's.

| Variable                  | Required | Default            | Description                                                                                                                                                                             |
| ------------------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CIMD_ENABLED`            | No       | `true`             | Seeds a new realm's switch. A realm with it off treats a URL-formatted `client_id` as an unknown client and does not advertise `client_id_metadata_document_supported`.                 |
| `CIMD_TRUST_POLICY`       | No       | `accept-any-https` | Seeds a new realm's trust policy: `accept-any-https` (any validating HTTPS document) or `allowlist` (only the realm's trusted domains).                                                 |
| `CIMD_TRUSTED_DOMAINS`    | No       | _(empty)_          | Seeds a new realm's trusted domains, comma/space-separated, for the `allowlist` policy. A leading `*.` permits subdomains. An `allowlist` realm with no domains accepts no CIMD client. |
| `CIMD_CACHE_DEFAULT_TTL`  | No       | `300`              | Cache TTL (seconds) when the document carries no usable `Cache-Control`/`Expires`.                                                                                                      |
| `CIMD_CACHE_MAX_TTL`      | No       | `3600`             | Hard upper bound (seconds) on any cached document, regardless of upstream `max-age`.                                                                                                    |
| `CIMD_MAX_DOCUMENT_BYTES` | No       | `65536`            | Maximum document size in bytes.                                                                                                                                                         |
| `CIMD_FETCH_TIMEOUT_MS`   | No       | `5000`             | Per-fetch timeout in milliseconds.                                                                                                                                                      |

A fetched document is cached per URL, for every realm. Each realm's switch and trust policy are checked before the cache is read, so a document one realm resolved never lets its client into a realm that refuses the host.

A metadata document and a client's `jwks_uri` are fetched through the egress client and never reach a private, loopback or link-local address, whatever the configuration: the client named them, and the [egress allowlist](#outbound-calls-and-the-egress-allowlist) applies only to destinations the operator or an admin set.

> **Note:** the `CIMD_*` variables are optional and default-safe, so the stack runs without them, and `.env.docker.example` does not list them. The `auth-server` `environment:` map does, so setting them in `.env` seeds the realms the server creates. Be deliberate about the trust policy: it defaults to `accept-any-https`, which returns before the trusted domains are consulted — so populating the domain list alone changes nothing until the trust policy is also `allowlist`.

#### Changing a realm's CIMD policy

The admin API's realm policy update, `realms.policies.update` ([#517](https://github.com/qauth-labs/qauth/issues/517)), changes a realm's CIMD policy; the environment keys no longer do. On a deployment that runs no admin listener, switch CIMD off for a realm, or hold it to an allowlist, by changing its stored policies in Postgres:

```sql
-- Switch CIMD off for the realm `master`.
UPDATE realms
   SET policies = jsonb_set(policies, '{registration,cimd,enabled}', 'false')
 WHERE name = 'master' AND policies_version > 0;

-- Or accept CIMD clients of the realm `master` only from these hosts.
UPDATE realms
   SET policies = jsonb_set(
         jsonb_set(policies, '{registration,cimd,trustPolicy}', '"allowlist"'),
         '{registration,cimd,trustedDomains}', '["client.example.com", "*.example.org"]')
 WHERE name = 'master' AND policies_version > 0;
```

The update raises the realm's `policies_version`, and every node applies it within the realm resolver's cache time (30 s by default), with no restart; a client may hold the realm's discovery documents for up to an hour (`max-age=3600`). Write a domain in lower case, with at least two labels and no IP address: a value the [policy schema](/reference/realm-policies/#registration) refuses fails the realm's token, authorization and discovery requests until it is corrected. `policies_version > 0` leaves alone a realm that has no policies yet, which runs on the environment until a boot fills it.

#### Hostile document hosts

Under `accept-any-https`, anyone can make the server fetch a document from a host they choose, by
sending its URL as a `client_id`. The fetch includes a TLS handshake with that host, and a hostile
host can keep the TLS library busy for seconds per handshake, in one call nothing interrupts. QAuth
never runs that handshake on the thread that serves requests:

- The CIMD and `jwks_uri` fetches run on worker threads, at most 8 at a time and 2 per host name. A
  thread a host keeps busy holds its slot until the handshake ends, so a caller with many host names
  can fill all 8. Other documents that are not cached then fail to load, and their clients are
  refused, until the slots free.
- The SSRF-safe egress client, which these fetches move to (#481), runs each exchange in a fetch
  process of its own instead. A process is killed at its deadline and a fresh one takes its place,
  so a hostile host holds a slot for no longer than the deadline. At most 8 processes run, and the
  host names under one registrable domain (`a.example.com`, `b.example.com`) share 2 of them. A
  process starts with an empty environment and, on Linux, none of the server's open files (on
  other systems, a descriptor the server inherited without close-on-exec reaches it). Each takes about
  70 MB, so a full pool needs about 600 MB beside the server; Linux ends a fetch process first
  when memory runs out.

Neither makes a hostile host free: a caller who names enough domains still keeps fetches busy until
their deadlines. The mitigation is the `allowlist` trust policy, in every realm that accepts CIMD
clients: the server then fetches a Client ID Metadata Document only from the realm's trusted
domains, so an unauthenticated caller can no longer pick the host. `CIMD_TRUST_POLICY=allowlist`
and `CIMD_TRUSTED_DOMAINS` seed it for a new realm; set an existing realm's as in
[Changing a realm's CIMD policy](#changing-a-realms-cimd-policy).

#### What the consent screen shows for a CIMD client

The consent screen names a CIMD client by the host of its `client_id` URL and
nothing else: that host is all the server verified, by fetching the document
from it. Under `accept-any-https`, a host that serves anyone's files (a code
hosting service, a shared static site, an object store bucket on a provider's
domain) lets anyone publish a document there, and the screen shows that
client under the provider's host. The registrable domain is in bold and a host
under a shared-hosting suffix of the Public Suffix List is flagged, but a
provider's own domain that is not on that list is not. A deployment that
accepts third-party agents or MCP clients should give each realm the
`allowlist` trust policy and list in its trusted domains only hosts whose every
document comes from the party the user expects.

#### Granting scopes to a CIMD client

A CIMD client starts with no scopes, so it is granted none of the scopes it asks for. Its document owns its name, redirect URIs and grant types; which scopes it may receive is the operator's decision, which a document cannot make. Grant them in the `cimd_clients` section of the seed manifest, and run `db:seed-oauth-clients` as for any other manifest:

```json
{
  "realm": "master",
  "cimd_clients": [
    {
      "client_id": "https://client.example.com/oauth/metadata.json",
      "scopes": ["mcp:read", "mcp:write", "offline_access"],
      "audience": ["https://mcp.example.com/mcp"]
    }
  ]
}
```

- Write `client_id` exactly as the client sends it: an `https` URL of at most 255 ASCII characters, with a path beyond `/` and no fragment.
- An entry sets only `scopes`, `audience` and `client_credentials_scopes` (below). `audience` is the token audience when the client names no `resource`. An empty `scopes` list withdraws the grant.
- `audience` cannot hold a value in the reserved `urn:qauth:aud:` namespace, such as the developer API's `urn:qauth:aud:developer:v1-rc.0`: a CIMD client never gets an API family audience ([API conventions](/reference/api-conventions/#issuing-a-family-audience)). A `clients` entry may list one, and the token endpoint then issues it to that client.
- An entry has no secret, so the seed prints none and `--rotate` does not apply. Every run sets the row to the entry's values and leaves the rest of it alone.
- Until the client's first authorization, its row has no redirect URI. That authorization reads the document and fills the row in, and later re-resolutions never change the grant.
- The grant is a ceiling: the user still consents, for each resource.
- The seed refuses an entry whose `client_id` belongs to a client that is not a CIMD client, and changes nothing for it.
- The client resolves only while its realm's CIMD policy is on and the realm's trust policy accepts its host.

##### Tokens a CIMD client gets as itself

A document that declares `token_endpoint_auth_method: private_key_jwt` and a key set (`jwks` or `jwks_uri`) may also declare the `client_credentials` grant. A token from that grant names no user: its `sub` is the client's `client_id`. The document's host chooses the grant, not you, while `scopes` holds what you granted the client for its users. So the grant issues a CIMD client no token until its entry lists the scopes it may get as itself, out of `scopes`, in `client_credentials_scopes`:

```json
{
  "realm": "master",
  "cimd_clients": [
    {
      "client_id": "https://client.example.com/oauth/metadata.json",
      "scopes": ["notes:read", "ssf:stream"],
      "client_credentials_scopes": ["ssf:stream"],
      "audience": ["https://auth.example.com"]
    }
  ]
}
```

- Without the list, the token endpoint refuses every `client_credentials` request of the client with `invalid_scope`; for a scope in `scopes`, the event reason is `scope_not_allowed_for_grant`. With it, the client gets a token of its own for the listed scopes only, and the scopes its users grant it, `notes:read` here, reach only the tokens a user granted.
- List only scopes a token without a user may carry, such as `ssf:stream` for a relying party that manages its [SSF stream](/operate/ssf-transmitter/#register-a-receiver). A resource server that does not check `sub` may act on such a token for every user.
- The seed refuses a scope that `scopes` does not hold and an empty list. It cannot check the grant: the document may add or drop `client_credentials` at any resolution, and the list applies whenever it does.
- Each run writes the list to the row, without `--rotate`, as it writes `scopes`. An entry without the list removes it, which closes the grant again, and the seed prints the list it removed: a node of an earlier release, during a rolling upgrade, issues every scope of `scopes` to a CIMD client without one. A resolution of the document never changes the list.
- The token endpoint reads the row on every request, so the next token request follows the list. A token issued before keeps its scopes until it expires.

### Redirect URI schemes for native apps

A redirect URI must be `https`, `http` to a loopback host, or a private-use scheme written as a reverse domain name, such as `com.example.app:/callback` (RFC 8252 §7.1). Some native apps call back on a scheme without a period instead. Cursor's desktop app, for one, uses `cursor://anysphere.cursor-mcp/oauth/callback`. List each such scheme you accept in `REDIRECT_URI_CUSTOM_SCHEMES`:

```bash
# .env — accept the Cursor desktop app's callback
REDIRECT_URI_CUSTOM_SCHEMES=cursor
```

| Variable                      | Required | Default   | Description                                                                                                       |
| ----------------------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `REDIRECT_URI_CUSTOM_SCHEMES` | No       | _(empty)_ | Scheme names, separated by spaces or commas, that a redirect URI may use besides the three kinds above. No colon. |

- A listed scheme is accepted everywhere a redirect URI is: dynamic client registration, `POST /api/clients`, CIMD documents, a seeded client, `/oauth/authorize` and the consent screen. Matching stays exact.
- Without it, registration refuses such a URI with `invalid_redirect_uri: unsupported scheme`, and `/oauth/authorize` refuses one already stored with `redirect_uri not permitted for this environment`. The client's `https` and loopback callbacks keep working either way.
- The default is empty on purpose. The reverse-domain form only makes an accidental clash between two apps unlikely. Neither form stops a malicious app on the same device from claiming the scheme; PKCE, which QAuth requires of every client, is what protects the code (RFC 8252 §8.1). Which apps to trust on your users' devices is your choice, one scheme at a time.
- The server refuses to start when an entry is not a scheme name, or names a scheme a browser or the operating system acts on itself: `http`, `https`, `javascript`, `data`, `file`, `blob`, `intent`, `mailto` and the like. Such schemes are refused at authorization whatever the list holds.

### ID-JAG / enterprise-managed authorization (ADR-011)

**Off by default**, and doubly fail-closed: with `ID_JAG_ENABLED` off the
`jwt-bearer` grant is neither advertised nor accepted, and even with it on an
empty `ID_JAG_TRUSTED_ISSUERS` rejects every assertion and keeps the grant out
of the discovery metadata. See
[ID-JAG](/integrate/oauth-flow/#id-jag--enterprise-managed-authorization-adr-011).

| Variable                         | Required          | Default   | Description                                                                                                                                                                                                                                                                                                          |
| -------------------------------- | ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ID_JAG_ENABLED`                 | No                | `false`   | Master switch. Gates both the `jwt-bearer` grant and the discovery members that advertise it.                                                                                                                                                                                                                        |
| `ID_JAG_TRUSTED_ISSUERS`         | Yes, when enabled | _(empty)_ | Allowlist of enterprise IdP issuers whose assertions may be redeemed. Empty rejects everything — an assertion never nominates its own trust.                                                                                                                                                                         |
| `ID_JAG_MAX_ASSERTION_LIFETIME`  | No                | `300`     | Seconds. Bounds the replay window a `jti` is tracked for.                                                                                                                                                                                                                                                            |
| `ID_JAG_ISSUED_LIFETIME`         | No                | `300`     | Seconds. Lifetime stamped on assertions QAuth **mints**, capped at the subject token's remaining lifetime.                                                                                                                                                                                                           |
| `ID_JAG_CLOCK_SKEW_LEEWAY`       | No                | `60`      | Seconds of tolerance on `exp` / `nbf` / `iat`.                                                                                                                                                                                                                                                                       |
| `ID_JAG_JWKS_CACHE_TTL`          | No                | `300`     | Seconds to cache a trusted issuer's discovery document and JWKS. At most `3600`: a larger value stops the server at boot. `0` turns the cache off, and every assertion then costs the issuer two fetches.                                                                                                            |
| `ID_JAG_JWKS_REFRESH_COOLDOWN`   | No                | `30`      | Seconds between two refreshes that an assertion with an unknown `kid` may force for one issuer. Inside the cooldown such an assertion is refused without a fetch, so a rotated key is picked up at most this long after it is first presented, or after the negative cache below lapses if a fetch failed. 1 to 300. |
| `ID_JAG_JWKS_NEGATIVE_CACHE_TTL` | No                | `30`      | Seconds a failed discovery or JWKS fetch is remembered. Meanwhile nothing is fetched from that issuer, so an outage costs one attempt per window; keys already cached keep working. 1 to 300.                                                                                                                        |
| `ID_JAG_FETCH_TIMEOUT_MS`        | No                | `5000`    | Timeout for issuer discovery / JWKS fetches.                                                                                                                                                                                                                                                                         |
| `ID_JAG_MAX_DOCUMENT_BYTES`      | No                | `65536`   | Size cap on a fetched discovery or JWKS document.                                                                                                                                                                                                                                                                    |

> **Note:** the `auth-server` `environment:` map forwards every `ID_JAG_*`
> variable, so setting them in `.env` takes effect. A trusted issuer's
> discovery URL is an operator-set destination: an
> [egress allowlist](#outbound-calls-and-the-egress-allowlist) entry can open
> its private host for a realm. The `jwks_uri` its discovery document names
> never reaches a private address, so an issuer whose keys sit on a private
> network cannot be used from discovery alone yet.

#### Provisioning a client for ID-JAG

The switches above turn the feature on. Each client still needs its own list of
targets: the foreign authorization servers and MCP servers it may name when it
mints an ID-JAG, and the MCP servers it may redeem an assertion for. Set it with
`id_jag_targets` on the client's entry in the `db:seed-oauth-clients` manifest:

```json
{
  "realm": "master",
  "clients": [
    {
      "client_id": "partner-agent",
      "name": "Partner agent (mints ID-JAGs)",
      "grant_types": ["urn:ietf:params:oauth:grant-type:token-exchange"],
      "scopes": ["chat.read"],
      "token_endpoint_auth_method": "client_secret_basic",
      "is_agent": true,
      "id_jag_targets": ["https://auth.partner.example", "https://mcp.partner.example/mcp"]
    },
    {
      "client_id": "enterprise-mcp-client",
      "name": "MCP client (redeems ID-JAGs)",
      "grant_types": ["urn:ietf:params:oauth:grant-type:jwt-bearer"],
      "scopes": ["chat.read"],
      "token_endpoint_auth_method": "client_secret_basic",
      "id_jag_targets": ["https://mcp.example.com/mcp"]
    }
  ]
}
```

Two client columns hold resource identifiers, and each does one job:

| Manifest field   | Column                         | What it bounds                                                                                                                                                                                  |
| ---------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audience`       | `oauth_clients.audience`       | The tokens QAuth issues to the client: the `resource` values `client_credentials` accepts, the token `aud` when a grant names no `resource`, and the token audiences the client may introspect. |
| `id_jag_targets` | `oauth_clients.id_jag_targets` | ID-JAG only. Minting: the `audience` (the target authorization server's issuer) and the `resource` (the MCP server) must both be listed. Redeeming: the assertion's `resource` must be listed.  |

- Neither list falls back to the other. A server listed only in `audience` is not
  an ID-JAG target, and one listed only in `id_jag_targets` is not a
  `client_credentials` audience.
- An empty or missing `id_jag_targets` denies both minting and redeeming.
- Only the manifest's `clients` entries set it. Dynamic registration,
  `POST /api/clients`, a CIMD metadata document and the manifest's `cimd_clients`
  entries cannot, and a client created by one of them has an empty list.
- The seed skips a client that already exists. To change the list of an existing
  client, re-run its entry with `--rotate`, which also issues a new secret, or set
  `oauth_clients.id_jag_targets` with an `UPDATE` by hand.
- Before migration 0027 the targets were read from `audience`. The migration
  copies nothing, so a client set up that way mints and redeems nothing until its
  targets are listed here.

### First-party clients (ADR-017)

A client is **first party** only when the operator says so
([ADR-017 Decision 2](/reference/records/adr/017-first-party-login/)): an app
that the entity operating this server controls and that users see under that
entity's brand. Another entity's app, a tenant's included, stays a third-party
client on `/oauth/authorize`. Set the profile on the client's entry in the
`db:seed-oauth-clients` manifest, with a written reason:

```json
{
  "realm": "master",
  "clients": [
    {
      "client_id": "notes-backend",
      "name": "Notes",
      "grant_types": ["authorization_code", "refresh_token"],
      "redirect_uris": ["com.example.notes:/callback"],
      "token_endpoint_auth_method": "private_key_jwt",
      "jwks_uri": "https://notes.example.com/.well-known/jwks.json",
      "first_party_profile": "native_backend",
      "first_party_policy": { "flows": ["login", "register", "reset"] },
      "first_party_reason": "Notes is our own app, published under our brand."
    }
  ],
  "system_client": {
    "redirect_uris": ["https://portal.example.com/auth/callback"],
    "jwks_uri": "https://portal.example.com/.well-known/jwks.json"
  }
}
```

| Manifest field        | Meaning                                                                                                                                                                                                                                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `first_party_profile` | `web_redirect`: a web front-end on the redirect flow; it earns only the consent waiver at `/oauth/authorize`. `native_backend`: the backend of a native app, for the authorization challenge endpoint; at `/oauth/authorize` it gets the same waiver, and every request of it counts as `prompt=login`. |
| `first_party_policy`  | `native_backend` only: `flows` (a non-empty set of `login`, `register`, `reset`; default `["login"]`), `email_code_after_password` (default `false`) and `pkce_required` (default `true`). No other member is accepted.                                                                                 |
| `first_party_reason`  | Required with a profile, refused without one: why the app is first party. It is stored with the client and recorded in the change's event.                                                                                                                                                              |
| `system_client`       | The developer portal's system client, as the migration runner provisions it: `redirect_uris`, `jwks` or `jwks_uri`, and optionally `client_id` (by default the seed's `SYSTEM_CLIENT_ID` when it is set, else `system`: the auth server's id) and `first_party_reason`. It always converges.            |

- A profile needs `token_endpoint_auth_method: "private_key_jwt"` and is refused
  on an agent. `native_backend` also needs `jwks` or `jwks_uri`, the
  `authorization_code` grant and at least one redirect URI for the browser leg:
  `https`, a private-use scheme in reverse domain-name form
  (`com.example.app:/callback`) or an `http` loopback IP literal
  (`http://127.0.0.1/callback`). The seed cannot check that an `https` URI is
  claimed by the app and never served by its backend; that stays the
  operator's to ensure.
- With `pkce_required: false` the seed prints a warning naming the client. PKCE
  stays required on the redirect flow for every client.
- A `--rotate` entry that sets a profile on a client a developer, dynamic
  registration or a CIMD document created is refused by name before a secret
  is issued for it, and that client is left unchanged. The other entries run
  as usual, and the seed exits `1`.
- The system client is provisioned only through `system_client` (or the
  migration runner): a `clients` entry with its id is refused before anything
  is written. The seed takes that id from the manifest's `system_client`, or
  else from `SYSTEM_CLIENT_ID` (default `system`), so set one of them when the
  auth server uses another id.
- The database holds the rules on every path: no profile on a dynamic, CIMD,
  agent or developer-owned client, a profile only with `private_key_jwt`, a
  policy exactly on `native_backend`, `native_backend` only with the
  `authorization_code` grant, and a written reason of at most 1000 characters
  exactly with a profile. Dynamic registration, `POST /api/clients` and a
  CIMD document can never set one.
- The seed skips a client that already exists. Changing or removing a profile
  goes through `--rotate`, which also issues a new secret. Removing it revokes
  every refresh token of the client not already revoked, in every family and
  for every user.
  Each change of the profile, its policy or its reason is recorded as a
  `client.first_party_changed` event (see [Events](/reference/events/)).

### Clients that may start a registration (`hosted_flows`)

A client sends a person to register with `prompt=create` on
`/oauth/authorize` ([Registration](/integrate/oauth-flow/#registration-promptcreate)),
and the person can pick "Create an account" on that client's sign-in
([Creating an account from the sign-in](/integrate/hosted-ui/#creating-an-account-from-the-sign-in)).
Registration is off unless two operators' switches both allow it:

- the realm's `accounts.allowSignUp` policy, seeded by `ALLOW_SIGN_UP` and off
  by default ([Realm policies](/reference/realm-policies/)), the same switch
  that lets an upstream identity create an account; and
- the client's `hosted_flows`, a list on its entry in the
  `db:seed-oauth-clients` manifest. `["register"]` is the only flow it takes
  today.

```json
{
  "realm": "master",
  "clients": [
    {
      "client_id": "notes-web",
      "name": "Notes",
      "grant_types": ["authorization_code", "refresh_token"],
      "redirect_uris": ["https://notes.example.com/callback"],
      "hosted_flows": ["register"]
    }
  ]
}
```

- A client cannot set its own list. Dynamic registration, `POST /api/clients`
  and a CIMD document never write `hosted_flows`, so no client can turn on its
  own sign-up. A client with no list, or an empty one, starts no registration.
- `hosted_flows` needs the `authorization_code` grant: a registration ends in
  an authorization code.
- The seed skips a client that already exists. `--rotate` writes the list the
  manifest names, and clears it when the entry no longer names one.
- Registration runs only on the Interaction API (`INTERACTION_UI_ENABLED`).
  With it off, `prompt=create` is refused whatever the switches say.
- A `native_backend` client's own flows (`first_party_policy.flows`) are for
  the authorization challenge endpoint. On `/oauth/authorize` it registers
  only through `hosted_flows`, like every other client.

### A bot challenge before a client's registrations (`registration_challenge`)

A registration can be made to pass the bot challenge before its address is
asked for: for every client of a realm, with the realm's
`botChallenge.requiredAtSignUp` policy ([Realm policies](/reference/realm-policies/)),
or for one client, with `"registration_challenge": true` on its entry in the
`db:seed-oauth-clients` manifest.

- With the built-in proof of work (`BOT_CHALLENGE_PROVIDER=pow`, the default),
  the page solves a puzzle from the realm origin, so it needs JavaScript; a
  person without it is told so, and the registration is refused, never
  passed.
- A client that cannot serve the `captcha` step is refused the registration
  it requires, never sent to the browser in its place.
- Like `hosted_flows`, only the manifest writes it: dynamic registration,
  `POST /api/clients` and a CIMD document never do, so no client can lift its
  own. `--rotate` clears it when the entry no longer names it.

### Outbound calls and the egress allowlist

The outbound calls the server makes for a configuration value or a request (the
CIMD, client `jwks_uri` and ID-JAG issuer fetches, the SSF push) go through one
SSRF-safe egress client: `https` only, every address of the
host checked, the connection pinned to the checked addresses, redirects checked
the same way, time and size capped
([ADR-019 Decision 8](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)).
It never reaches a private, loopback or link-local address, unless the
deployment allowlist names the host or range **and** the destination was set by
the operator or a realm admin, for a realm the entry names. A destination that a
client, an end user or a fetched document supplies (a CIMD `client_id`, a
client's `jwks_uri`, the `jwks_uri` of an issuer's discovery document) never
uses the allowlist. The wallet status-list fetch keeps its own URI-prefix
allowlist for now, and the OpenTelemetry export and a KEK custody adapter
(`KEK_PROVIDER`) make their own connections: their destinations are
deployment-wide configuration, outside the egress client by ADR-019's
amendments of 2026-10-24 and 2026-10-27.

`EGRESS_ALLOWLIST_PATH` names the allowlist, a JSON file the operator writes:

```json
{
  "entries": [
    { "host": "idp.corp.example", "realms": ["master"] },
    { "cidr": "10.20.0.0/16", "realms": ["master", "acme"], "note": "partner VPN" }
  ]
}
```

- Each entry names one `host` (exact, no wildcard) or one `cidr` range, and the
  realms it applies to, by realm name.
- A `host` entry opens the private (`10.0.0.0/8`, `172.16.0.0/12`,
  `192.168.0.0/16`), shared (`100.64.0.0/10`) and unique-local (`fc00::/7`)
  addresses its name resolves to. Loopback, link-local and other special
  ranges open only through a `cidr` entry that names them.
- A `cidr` entry is not tied to a host: any operator or admin destination of
  the realms it names that resolves into the range is allowed. It may be no
  wider than `/8` (IPv4) or `/32` (IPv6), and may not overlap a range that
  reaches other addresses only through translation (IPv4-mapped
  `::ffff:0:0/96`, NAT64 `64:ff9b::/96` and `64:ff9b:1::/48`, 6to4
  `2002::/16`, Teredo `2001::/32`).
- The server reads the file once, at boot. A file that cannot be read, does
  not validate or others can write stops the boot, naming the variable, the
  file and the mistake; a file its group can write, or that neither root nor
  the server's user owns, gives a warning.
- The list is not in the database, and no API reads or edits it, so a realm
  admin cannot widen it.
- No entry opens an unspecified (`0.0.0.0`) or multicast address, or a cloud
  metadata endpoint (`169.254.169.254`, `169.254.170.0/24`, `100.100.100.200`,
  `fd00:ec2::/32`), and a redirect to another host never uses the entry that
  let the first request through.

With Compose, mount the file read-only and name its path in `.env`:

```yaml
# docker-compose.override.yml
services:
  auth-server:
    volumes:
      - ./egress-allowlist.json:/etc/qauth/egress-allowlist.json:ro
```

```bash
# .env
EGRESS_ALLOWLIST_PATH=/etc/qauth/egress-allowlist.json
```

`CIMD_ALLOW_PRIVATE_ADDRESSES` and `ID_JAG_ALLOW_PRIVATE_ADDRESSES` are gone:
set to a value that is not blank, they stop the boot with a message that names
`EGRESS_ALLOWLIST_PATH`. `docker-compose.yml` still forwards both, blank by
default, only so that a value left in `.env` reaches that check
([the upgrade to 0.2](/operate/upgrades/#the-private-address-switches-are-gone)). Tests reach a local fixture server through the
test-only `createTestEgressClient` instead.

### Wallet federation (OID4VP, T4)

Wallet sign-in is **off by default**. With `WALLET_FEDERATION_ENABLED` unset or
`false` the wallet routes are never registered and the paths 404 — nothing below
has any effect. See the [wallet sign-in guide](/integrate/wallet-login/) for the
full flow and [ADR-009](/reference/records/adr/009-wallet-account-resolution/)
for the resolution model.

| Variable                            | Required          | Default        | Description                                                                                                                                                                              |
| ----------------------------------- | ----------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WALLET_FEDERATION_ENABLED`         | No                | `false`        | Master switch. When off, the wallet-login UI and the `direct_post` endpoint are not registered.                                                                                          |
| `OID4VP_VERIFIER_PROFILE`           | Yes, when enabled | _(unset)_      | `oid4vp-1.0-base` or `haip-1.0`. There is no fallback — an unset or unprovisioned profile refuses every flow. `haip-1.0` awaits #377.                                                    |
| `OID4VP_REQUESTED_VCT`              | Yes, when enabled | _(unset)_      | The credential type to request. Unset means a DCQL query with no type constraint, which is refused.                                                                                      |
| `OID4VP_TRUSTED_ISSUERS`            | Yes, when enabled | _(unset)_      | Per-realm issuer allowlist. An issuer absent here is refused before any claim is read.                                                                                                   |
| `OID4VP_ISSUER_JWKS`                | Yes, when enabled | _(unset)_      | The key each trusted issuer signs with.                                                                                                                                                  |
| `OID4VP_SUBJECT_RESOLUTION`         | No                | _(unset)_      | `asserted-lookup` (the ADR-009 default), `issuer-scoped-claim`, `session-binding`, `key-thumbprint`, or `rp-pseudonym`.                                                                  |
| `OID4VP_SUBJECT_BINDING_CLAIMS`     | Yes, when enabled | _(unset)_      | Comma-separated claims the wallet binding is derived from — the entitlement check of `asserted-lookup`. Missing means every refusal.                                                     |
| `OID4VP_SUBJECT_CLAIM`              | Conditional       | _(unset)_      | The claim carrying the subject, for `issuer-scoped-claim`.                                                                                                                               |
| `OID4VP_SUBJECT_CLAIM_ISSUERS`      | Conditional       | _(unset)_      | Which issuers may assert `OID4VP_SUBJECT_CLAIM`.                                                                                                                                         |
| `OID4VP_EMAIL_VERIFYING_ISSUERS`    | No                | _(unset)_      | Issuers whose wallet `email` counts as verified without a disclosed `email_verified: true`. Unset means none. List only issuers that never issue unverified addresses.                   |
| `OID4VP_ISSUER_ASSURANCE`           | No                | _(unset)_      | Per-issuer eIDAS level of assurance, mapped to the OIDC `acr` claim ([ADR-010](/reference/records/adr/010-acr-assurance-mapping/)). Listing an issuer here does **not** make it trusted. |
| `OID4VP_STATUS_LIST_TRUST_ANCHORS`  | No                | _(empty)_      | Trust anchors for Token Status List revocation checking (or `_PATH` to read them from a file).                                                                                           |
| `OID4VP_STATUS_LIST_URI_ALLOWLIST`  | No                | _(empty)_      | Permitted status-list URIs.                                                                                                                                                              |
| `OID4VP_STATUS_LIST_SIGNERS`        | No                | _(unset)_      | Which status issuer may sign the lists under a URI prefix on another host (a CDN), as JSON. Unset: the signer's certificate must name the list host.                                     |
| `OID4VP_WALLET_INVOCATION_ENDPOINT` | No                | `openid4vp://` | The wallet deep-link / QR target. Script-capable schemes (`javascript:`, `data:`) are refused at boot.                                                                                   |

### Post-quantum hybrid signing (ADR-005)

Also **off by default** — tokens are Ed25519-only and the JWKS is EdDSA-only
unless configured. See the [verifier guide](/operate/pqc-verifier-guide/).

| Variable                 | Required               | Default     | Description                                                                                                                                                                     |
| ------------------------ | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SIGNING_ALGORITHM_MODE` | No                     | `ed25519`   | `ed25519` or `ed25519+ml-dsa-65`. Must be the latter for hybrid.                                                                                                                |
| `HYBRID_SIGNING_ENABLED` | No                     | `false`     | Turns on live hybrid token issuance. Enabling it without an ML-DSA key **throws at startup** — a half-configured deployment fails fast rather than degrading to classical-only. |
| `JWT_MLDSA_PRIVATE_KEY`  | Yes, when hybrid is on | _(unset)_   | ML-DSA-65 private key as a base64url 32-byte seed (or `JWT_MLDSA_PRIVATE_KEY_PATH`).                                                                                            |
| `JWT_MLDSA_KID`          | No                     | _(unset)_   | Stable `kid` for the ML-DSA key published in the `AKP` JWK.                                                                                                                     |
| `PQC_TOKEN_DELIVERY`     | No                     | `reference` | `reference` keeps the bearer a small Ed25519 JWS and serves the PQC signature via introspection. `self-contained` requires `PQC_SELF_CONTAINED_ACK`.                            |
| `PQC_SELF_CONTAINED_ACK` | Conditional            | `false`     | Explicit acknowledgement that `self-contained` ships a ~4.4 KB detached signature exceeding cookie and URL budgets.                                                             |

> Setting `JWT_MLDSA_PRIVATE_KEY` alone publishes the ML-DSA public key in the
> JWKS without issuing any hybrid token — deliberate, so verifiers can fetch the
> key before issuance is switched on.

> **Note:** `.env.docker.example` does not list the wallet-federation or
> post-quantum variables. Both features are off by default, so the stack runs
> without them. The `auth-server` `environment:` map does list them — every
> wallet variable above including the four `OID4VP_SUBJECT_*`, and every
> post-quantum one (`SIGNING_ALGORITHM_MODE`, `HYBRID_SIGNING_ENABLED`,
> `JWT_MLDSA_*`, `PQC_*`) — so all of them can be set from `.env`. Note that
> `OID4VP_SUBJECT_BINDING_CLAIMS` is required once the wallet flag is on: leaving
> it unset refuses every sign-in rather than falling back to a default.

## Troubleshooting

### Port Conflicts

If ports 3000, 5432, or 6379 are in use:

```bash
# Check what's using the port
lsof -i :3000

# Modify port mappings in docker-compose.yml
ports:
  - '3001:3000'  # Map to different host port
```

### Migration Errors

```bash
# Check migration-runner logs
docker-compose logs migration-runner

# Check postgres is ready
docker-compose ps postgres

# List the pending migrations without changing anything
docker-compose run --rm migration-runner --check

# Re-run migrations
docker-compose run --rm migration-runner
```

A failed run names the migration that failed and rolls the whole run back, so
running it again after fixing the cause is safe.

If migration-runner fails specifically on the ADR-002 migration (0011), that
is very likely a required backfill step you skipped — see the
[Upgrades runbook](/operate/upgrades/), not this section.

### JWT Key Errors

Ensure your JWT keys in `.env`:

- Include the `-----BEGIN/END-----` lines
- Are properly quoted with double quotes
- Have no extra whitespace
- Are **PKCS#8** for private keys (`-----BEGIN PRIVATE KEY-----`). The key
  boot step also reads an RSA key in PKCS#1, but a 0.1 release refuses it —
  see the [Keys guide](/operate/keys/#pem-keys-pkcs8-recommended).

### Build Failures

```bash
# Clean Docker build cache
docker builder prune

# Rebuild without cache
docker-compose build --no-cache
```

If the build fails on `Cannot find module '@tailwindcss/vite'` or a similar dev-portal-scoped import while building **auth-server** or **migration-runner**: `apps/developer-portal` is intentionally excluded from those build contexts via the root `.dockerignore`. The exclusion keeps Nx's project-graph processor from trying to parse the portal's configs (which import portal-scoped dev deps) during an auth-server build. This exclusion is load-bearing and should not be removed.

The **developer-portal** image needs its own source, so it ships a sibling `apps/developer-portal/Dockerfile.dockerignore`. BuildKit prefers a `<dockerfile>.dockerignore` over the root `.dockerignore`, so that file applies to the portal build only and deliberately does **not** exclude `apps/developer-portal`. Build the portal image with BuildKit enabled (default on Docker 23+) so this per-Dockerfile ignore is honored.

### Watch: "no space left on device"

When running `docker compose ... up --watch`, Compose uses inotify. The error often means **inotify limits** (not disk space):

1. **Close other watchers** (Nx graph, IDE, etc.):
   ```bash
   pkill -f 'nx graph.*watch'
   ```
2. **Increase inotify instance limit**:
   ```bash
   sudo sysctl fs.inotify.max_user_instances=4096
   echo "fs.inotify.max_user_instances=4096" | sudo tee -a /etc/sysctl.d/99-inotify.conf
   ```
3. **Use watch-free dev** if it still fails:
   ```bash
   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
   # After code changes:
   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build auth-server
   ```

### Container Won't Start

```bash
# Check container logs
docker logs qauth-auth-server

# Check container status
docker inspect qauth-auth-server | jq '.[0].State'
```

## Production Considerations

This Docker setup is designed for **local development**. For production:

1. **Use secrets management** (Vault, AWS Secrets Manager) instead of `.env` files
2. **Use managed databases** (RDS, Cloud SQL) instead of containerized PostgreSQL
3. **Use managed Redis** (ElastiCache, Memorystore) for high availability
4. **Add reverse proxy** (nginx, Traefik) with TLS termination, and set
   `TRUST_PROXY` to the addresses allowed to report the client address. Every
   per-IP rate limit and the failed-login lockout key on the client address.
   Without `TRUST_PROXY`, the auth-server sees every request as coming from the
   proxy, so all users share one bucket and one caller can lock everyone out.
   The developer portal counts as a proxy too: it forwards one address, the
   client of the connection it is serving. List only the addresses of the
   proxies in front of the auth-server and of the developer portal, never a
   range that clients can connect from. A broad private range such as
   `uniquelocal`, or the whole Docker network, also covers the bridge gateway,
   which host-local and published-port clients appear from. In this Compose
   stack the portal has a fixed address, `172.30.80.10`, so
   `TRUST_PROXY=172.30.80.10` names the portal alone; add a reverse proxy's own
   address after a comma. `TRUST_PROXY=true` and hop counts are rejected,
   because they would let any caller choose its own address.
   With a TLS proxy in front of the portal, set `PORTAL_TRUST_PROXY` on the
   portal to that proxy's address, so the portal forwards each visitor's
   address rather than the proxy's, and set `TRUST_PROXY` on the auth-server to
   the portal's fixed address, plus the proxy's if the auth-server is behind it
   too. Every reverse proxy named in `PORTAL_TRUST_PROXY` or `TRUST_PROXY` must
   append the address it accepted the connection from to `X-Forwarded-For`
   (for example, nginx:
   `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`), so the
   last entry is always one it wrote; the portal sets the header itself. The
   first hop, the proxy clients connect to, may instead replace the header
   with that address, as the reference configuration does; a proxy behind
   another trusted hop must append. Use
   single addresses in both, never a client range; on the Compose network,
   give the proxy a fixed address below `<prefix>.128`, such as
   `172.30.80.20`. If `172.30.80.0/24` overlaps a network on your host, set
   `QAUTH_NETWORK_PREFIX` to the first three octets of a free `/24`; the
   portal is then `<prefix>.10`.
   The proxy must also pass the host the client asked for. The auth-server
   answers a request only on the realm host, the host of `JWT_ISSUER`, and on
   the names in `DEFAULT_REALM_ENDPOINT_HOSTS`; any other host gets
   `421 Misdirected Request`, and only `/health` and `/ready` answer on every
   host. Keep
   the client's `Host` header (nginx: `proxy_set_header Host $host;`), or send
   it as `X-Forwarded-Host` from an address listed in `TRUST_PROXY`; from any
   other address that header is ignored. A proxy listed in `TRUST_PROXY` must
   set `X-Forwarded-Host` itself or remove it (nginx:
   `proxy_set_header X-Forwarded-Host $host;`), because the auth-server
   believes the value it forwards, and one passed through from the client
   would let the client pick the realm. An endpoint host answers the API
   routes only: the sign-in pages, `/oauth/authorize` and `/consents` answer
   421 there. [Reverse Proxy](/operate/reverse-proxy/) lists every rule the
   proxy follows, and the reference nginx configuration that implements them.
5. **Configure resource limits** in Docker/Kubernetes. `docker-compose.yml`
   caps the auth-server at 1 GiB and the developer portal at 512 MiB and
   restarts both after a crash (`restart: unless-stopped`); size the limits to
   your load. The portal also reads at most 1 MiB of any request body.
6. **Size the Argon2 thread pool to the host.** Every presented
   `client_secret`, password and API key is checked with Argon2id on Node's
   libuv thread pool, which also verifies and signs every JWT (through
   WebCrypto) and runs the database's SCRAM handshake. The pool has
   `UV_THREADPOOL_SIZE` threads, 4 unless set, and QAuth lets Argon2 use at
   most half of them, so that token checks keep threads during a burst of
   logins or client secrets. With the default, two Argon2 checks run at once
   whatever the host has. **On a host with four or more cores, raise
   `UV_THREADPOOL_SIZE`**, for example to the core count, so that more checks
   run at once. It is Node's setting, not QAuth's: set it in the process
   environment (`docker-compose.yml` forwards it from `.env`). Each
   concurrent check holds `PASSWORD_MEMORY_COST` (64 MiB by default), so raise
   the memory limit with it.

   Checks beyond the running ones wait in a queue. A client-secret check
   (`/oauth/token`, `/oauth/introspect`, `/oauth/revoke`) that would wait
   behind `PASSWORD_HASH_QUEUE_LIMIT` others (32 by default) is refused at
   once, before any hash, with `503 Service Unavailable`,
   `"error": "temporarily_unavailable"` and `Retry-After: 1`, rather than
   waiting until its caller times out. Each refusal is logged at `warn` with
   the client and the queue length, and counted in
   `qauth_client_secret_checks_shed_total` (see
   [Observability](/operate/observability/#metrics-get-internalmetrics)). Sign-ins and
   registrations are not refused: they wait their turn, and count toward the
   queue while they wait. Raise the limit if legitimate clients see these
   refusals while the host has CPU to spare; lower it to fail faster.

7. **Set up monitoring** (Prometheus, Grafana)
8. **Enable logging aggregation** (ELK, Loki)

See [ADR-001: JWT Key Management](/reference/records/adr/001-jwt-key-management/) for production key management strategy, and the [Keys guide](/operate/keys/) for how to generate each key type today.

## Testing the Setup

A comprehensive test script is available:

```bash
./scripts/test-docker.sh
```

This verifies:

- Environment configuration
- Docker image builds
- Service startup and health
- Database migrations
- API endpoint functionality
- Data persistence

## See also

- [Keys](/operate/keys/) — generating EdDSA, RS256, and ML-DSA key material, and the PKCS#8 pitfall.
- [Upgrades](/operate/upgrades/) — the upgrade procedure (back up, run `migration-runner`, start the new version) and the runbook of the destructive ADR-002 migration 0011.
- [Observability](/operate/observability/) — logging, metrics, and alerting once the stack is up.
- [Environment-Aware Authorization](/operate/environment-authorization/) — the `environment` policy dimension referenced throughout this stack.

---

# Topology

URL: https://docs.qauth.dev/operate/topology/

This page describes the layout of a QAuth deployment, as
[ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)
fixes it. It says what this release does, and marks what a later release adds.
The pages it links to have the details.

A deployment in its simplest form, which this release runs by default:

```text
browser ──https──▶ reverse proxy ──▶ auth server (SERVICE_ROLES=all) ──▶ Postgres, Redis
                   auth.example.com     │
                                        └─ internal listener, 127.0.0.1:3443: /internal/metrics
developer portal ──http://auth-server:3000──▶ auth server   (an endpoint host)
```

## One host and one issuer per realm

Each realm has its own host and its own issuer. The issuer's host is the
realm's **primary host**. Every URL the realm publishes is built from its row
in the database, never from the request: the issuer, the discovery and JWKS
URLs, every endpoint URL, the links in mail, redirect targets, and the cookie
and passkey settings.

- **The default realm** takes its issuer from `JWT_ISSUER` at its first boot,
  and its name from `DEFAULT_REALM_NAME` (`master` by default).
- **The issuer and the primary host are permanent.** Tokens, registered
  clients, enrolled passkeys and federation partners depend on them. A
  database trigger refuses to change them, and a boot whose `JWT_ISSUER`
  differs from the stored issuer refuses to start. Choose the host with care:
  it cannot be fixed later.
- **A host belongs to one realm.** A host is the primary host or an endpoint
  host of exactly one realm. The `realm_hosts` table keeps it, unique across
  every realm and both kinds. A wildcard host is refused.
- **The host is a name.** An IP address cannot be a primary host, because a
  passkey RP ID cannot be one. Plain `http` is accepted for `localhost` and
  `*.localhost` only.

This release runs one realm, the default realm. No route or command adds a
second one yet; the admin API's realm lifecycle operations
([#694](https://github.com/qauth-labs/qauth/issues/694)) will.

## A dedicated host, never a path

QAuth needs a host of its own. It never runs under a path of a shared host,
such as `https://example.com/auth`:

- the browser session lives in a `__Host-` cookie, which must carry `Path=/`
  and no `Domain`, so it belongs to the whole host;
- a passkey is bound to its relying party ID, which is a host, not a path.

Two realms on one host would share one session cookie and one RP ID, so
path-based realms are refused. A deployment upgraded from 0.1 whose
`JWT_ISSUER` has a path keeps working, with a warning at every boot: only the
host routes requests. A new realm's issuer is an origin with no path.

## DNS and TLS per realm

The operator provisions a DNS name and a TLS certificate for every realm host.
QAuth requests no certificate itself: automatic certificates (ACME) are not
part of 1.0. The reverse proxy terminates TLS and reads the certificate and
its key from files. One certificate may cover several realm hosts, or each
host may have its own ([Reverse proxy](/operate/reverse-proxy/#the-reference-configuration)).

Plan the hosts before the first boot. The default realm's host is permanent,
and the operator realm gets a host of its own when a second realm is added
([below](#the-operator-realm)).

## How a request finds its realm

A request belongs to the realm whose primary host or endpoint host equals the
request's host:

- The host comes from `Host` (`:authority` in HTTP/2). `X-Forwarded-Host`
  counts only when the hop that sent it is listed in `TRUST_PROXY`.
- The match is exact, ignores letter case and drops the port.
- A request for any other host gets `421 Misdirected Request`, before any
  route runs: no cookie, no realm data and no fallback to the default realm.
  The body is a problem document, or the OAuth error shape on an OAuth
  endpoint, with the detail `This server does not answer for the requested host`.
- `/health` and `/ready` answer on every host. They carry no realm data.

## Endpoint hosts

A server-side caller often reaches the auth server by another name than the
issuer's host: a container name, an internal load balancer, an IP address. The
operator lists such names as **endpoint hosts** of the realm. For the default
realm that is `DEFAULT_REALM_ENDPOINT_HOSTS`, a comma-separated list:

```bash
# The developer portal's AUTH_SERVER_URL is http://auth-server:3000.
DEFAULT_REALM_ENDPOINT_HOSTS=auth-server
```

- Each boot adds every listed host the realm lacks, and never removes one.
- A host already used by a realm, the issuer's own host included, refuses the
  boot.
- An endpoint host may be an IP address. A port is dropped; a scheme, path or
  wildcard refuses the boot.

An endpoint host answers the API endpoints: token, introspection, revocation,
userinfo, registration, discovery, JWKS, the `/auth/*` API routes, and the
account and developer APIs. It refuses the browser-session endpoints with
`421`: `/oauth/authorize`, `/ui/*`, the Interaction API, `/consents`,
`/auth/link/wallet` and the email verification page. A browser session lives
only on the realm's primary host.

Keep endpoint hosts on the internal network: the reference proxy configuration
answers `421` for them. No route removes an endpoint host yet. To remove one:

1. Take it out of `DEFAULT_REALM_ENDPOINT_HOSTS` on every node and restart
   them. Every boot adds the listed hosts again, so this comes first.
2. Delete its row. Each node may answer it for 30 seconds more, from its host
   cache:

   ```sql
   DELETE FROM realm_hosts WHERE host = 'auth.internal.example' AND kind = 'endpoint';
   ```

## Service roles and mutual TLS

The auth server is one codebase that starts as one or more service roles,
picked by `SERVICE_ROLES`:

| Role       | Serves                                                                                                        |
| ---------- | ------------------------------------------------------------------------------------------------------------- |
| `web`      | The browser-session endpoints: authorize, the sign-in, consent and wallet pages.                              |
| `api`      | Token, introspection, revocation, userinfo, registration, discovery, JWKS and the account and developer APIs. |
| `admin`    | The admin API, on its own listener.                                                                           |
| `signer`   | The KEK, every private key and the signer.                                                                    |
| `delivery` | Event delivery: the SSF streams.                                                                              |

The default, `all`, runs every role in one process. That is one trust domain:
the key separation below protects keys only once the roles run on separate
nodes, and guards against forged tokens only once each role has its own
[database user](#database-users). [Service roles](/operate/service-roles/)
gives the details.

- **Keys stay on the signer.** Only a process that holds `signer` receives the
  KEK and the private key variables; any other process refuses to boot with
  one. A process without the signer verifies tokens with each realm's published
  keys, which it reads without a KEK.
- **The internal listener.** A second HTTP server of each process, on
  `INTERNAL_HOST` and `INTERNAL_PORT` (`127.0.0.1` and `3443` by default),
  serves what only other parts of the deployment call: today the metrics, to
  a scraper, and once the signer service below ships, signing, to the other
  roles. It is not routed by host, and the public port serves none of its
  paths.
- **Mutual TLS.** While the roles are split, the internal listener speaks
  mutual TLS 1.3 only, with the certificates in `INTERNAL_TLS_CERT_PATH`,
  `INTERNAL_TLS_KEY_PATH` and `INTERNAL_TLS_CA_PATH`. `INTERNAL_PEER_ROLES`
  maps a peer certificate's SAN, such as a SPIFFE ID, to the role it calls as,
  or to `metrics` for a scraper. A peer without a mapped SAN gets `403`.
- **The signer service.** A process without the signer reaches it at
  `SIGNER_URL`, over mutual TLS. The signer service itself ships with
  [#497](https://github.com/qauth-labs/qauth/issues/497): until then such a
  process answers `503` wherever it would sign, and the browser-facing role
  must sit with the signer.
  [What a split deployment can do today](/operate/service-roles/#what-a-split-deployment-can-do-today)
  gives the split that works now.

Every role shares one Postgres database and one Redis. Refresh-token rotation,
single-use codes and consent revocation never split across databases.

## Database users

ADR-019 gives each role its own Postgres user with only the grants it needs.
Only the signer's user reads the private keys in `realm_keys`, and only the
signer's user writes the published keys in `realm_public_keys`.

A single deployment keeps one user. Every role connects with the one
`DATABASE_URL`, as the owner of the tables, so every process can read and
write every table, the key tables included. The KEK, which only signer
processes hold, keeps the private keys in `realm_keys` secret from the
others: they are wrapped under it. It does not keep a process from writing a
key. Any process can store a public key of its own in `realm_public_keys`,
and every process then verifies tokens with it and publishes it in the JWKS.
While every role connects as that one user, a compromised node of any role can
sign tokens that verify, split or not.

### One user per role

A split deployment gives each role a user of its own
([#498](https://github.com/qauth-labs/qauth/issues/498)):

1. Create a login user for each role, and keep the owner of the tables for the
   migration runner. QAuth creates no user and sets no password. Roles that run
   in one process share one user.

   ```sql
   CREATE ROLE qauth_web LOGIN PASSWORD '…';
   CREATE ROLE qauth_api LOGIN PASSWORD '…';
   CREATE ROLE qauth_admin LOGIN PASSWORD '…';
   CREATE ROLE qauth_signer LOGIN PASSWORD '…';
   CREATE ROLE qauth_delivery LOGIN PASSWORD '…';
   ```

2. Name them to the migration runner, beside its `DATABASE_URL`, which stays
   the owner's: `DB_USER_WEB`, `DB_USER_API`, `DB_USER_ADMIN`,
   `DB_USER_SIGNER` and `DB_USER_DELIVERY`. Name the same user for the roles
   that share one. After its migrations, each run gives every user exactly the
   grants of its roles, so a table a release adds reaches the roles that use it
   before they start (see [the migration runner](/operate/docker/#migration-runner)).
   `pnpm nx run infra-db:db:grants` does the same from a checkout; `--check`
   reports how the users differ from their grants and changes nothing, and
   `--print` prints the statements.

3. Give each role's processes a `DATABASE_URL` that connects as its user:

   ```bash
   # The web nodes
   SERVICE_ROLES=web
   DATABASE_URL=postgresql://qauth_web:…@db.internal:5432/qauth
   # The signer nodes
   SERVICE_ROLES=signer
   DATABASE_URL=postgresql://qauth_signer:…@db.internal:5432/qauth
   ```

With none of the `DB_USER_*` variables set, nothing is granted: that is the
single deployment above. Once one is set, all five must be.

What the grants give, from the map in
`libs/infra/db/src/lib/database-users/grants-map.ts`:

| Table                    | Who                                                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `realm_keys`             | `signer` alone reads and writes it.                                                                           |
| `realm_public_keys`      | Every role reads it; only `signer` writes it.                                                                 |
| `events`                 | `web`, `api` and `admin` only insert, and read their own rows through functions; `delivery` reads and prunes. |
| `audit_logs`             | No role: it has no writer since #458.                                                                         |
| `admin_grants`           | `web`, `api` and `admin` read it; no role writes it.                                                          |
| The outbox and its queue | `delivery`, with only the columns of `realms`, `oauth_clients` and the stream subjects it reads.              |

No role user holds `TRUNCATE`, `REFERENCES` or `TRIGGER`, owns a table, or can
create one in the schema (a temporary table, which lasts as long as its own
session, is Postgres's default for every user): only the owner, the migration
runner's user, changes the schema.

The run refuses, and changes nothing, when a user:

- does not exist, is a superuser, owns the tables or is a member of their
  owner;
- has `REPLICATION`, `CREATEROLE` or `BYPASSRLS`, is a member of
  `pg_read_all_data`, `pg_write_all_data` or a predefined role that reads,
  writes or runs the server's files, or may create schemas in the database;
- would hold other privileges than the map gives it, a sequence included,
  through `PUBLIC` or through any role it is a member of, one it can only
  `SET ROLE` to included.

It also refuses while `PUBLIC` may execute a `SECURITY DEFINER` function in the
schema. It never revokes what `PUBLIC` holds: a grant to `PUBLIC` the map does
not give is yours to revoke, and the run names it.

A process whose only role is `delivery` skips the default realm's boot step,
which writes `realms`: on a new database, start another role's process first.
A process without the signer still cannot sign or set a signed cookie (#497):
[Service roles](/operate/service-roles/) says which splits work in this
release.

The statements for some roles are also in `@qauth-labs/infra-db`, for an
operator who grants by hand; the map gives each role these and more:

| Helper                               | For                                                        |
| ------------------------------------ | ---------------------------------------------------------- |
| `eventsWriterGrantStatements`        | A role that writes events, with no read of the event table |
| `eventDeliveryGrantStatements`       | The `delivery` role                                        |
| `eventRetentionGrantStatements`      | The event retention job                                    |
| `adminAuditLogWriterGrantStatements` | A role that writes the admin audit log                     |

## The reverse proxy

QAuth runs behind a reverse proxy, which terminates TLS and enforces the host
and path rules. [Reverse proxy](/operate/reverse-proxy/) states the ten rules
and ships a reference nginx configuration. In short:

- Send each realm's primary host to the auth server, with the realm host as
  `Host`, and answer `421` for any other host. Only `/health` and `/ready`
  answer on every host.
- Route on the normalised path, and refuse encoded separators and `/ui`
  variants with `404`.
- Send `/ui/*` to the ceremony app, strip QAuth's cookies from it both ways,
  and set its security headers.
- At the first hop, overwrite `X-Forwarded-For`, `X-Forwarded-Host` and
  `X-Forwarded-Proto`, and set `TRUST_PROXY` on the auth server to the proxy's
  address.
- Answer `404` on the public side for `/metrics` and `/internal/*`.
- Make the auth server reachable only through the proxy.
- List the ceremony app server's egress addresses in `CEREMONY_APP_PEERS`,
  with `CEREMONY_APP_PEER_RATE_LIMIT`, when that server reads the current step
  of the Interaction API for every browser. The step read counts per address,
  so without the list everyone signing in shares the server's one address
  bucket. A listed address's reads count per interaction instead. The auth
  server takes the address from `request.ip`, as `TRUST_PROXY` resolves it.
  Never list the proxy's address or a range browsers reach the auth server
  from: every caller from a listed address counts per interaction. The
  auth server cannot tell apart the browsers behind a listed address, so the
  ceremony app's server must itself limit the step reads it makes for each
  browser.

The reference ceremony app has not shipped: until it does, the auth server
renders `/ui/*` itself and needs its session cookie there, so the reference
configuration is not yet a working front for browser sign-in.

## The operator realm

The operator realm is the realm whose admins administer the deployment: its
admins manage every realm, by grant, its service accounts automate the admin
API, and the admin console, once it ships, will be its client.

In **simple mode**, one realm on one host, the default realm is also the
operator realm. Its first boot marks it so (`realms.is_operator`), and a
one-host deployment needs no second realm, host or issuer for administration.

Adding a second realm splits the two, in the **operator-realm split**. The
default realm keeps its host and its issuer, which are permanent. The operator
realm becomes a realm of its own, on a host of its own, and the operator's
admins sign in there, as the admin console will. Since no second realm can be
added in this release, the split cannot happen yet; the
[upgrade guide](/operate/upgrades/#the-operator-realm) will give its steps
with the realm lifecycle operations. Keep a host free for the operator realm,
so that it can get its DNS name and certificate then.

## See also

- [Upgrades](/operate/upgrades/#upgrading-from-01-to-02) — moving a 0.1
  deployment onto this topology.
- [Service roles](/operate/service-roles/) — the roles, the internal listener
  and the admin listener.
- [Keys](/operate/keys/) — the key store and the KEK.
- [Reverse proxy](/operate/reverse-proxy/) — the proxy rules and the reference
  configuration.
- [Docker](/operate/docker/) — the Compose stack, which runs one process with
  every role.

---

# Keys

URL: https://docs.qauth.dev/operate/keys/

Every realm keeps its keys in its own encrypted key store in Postgres, one set
per purpose
([ADR-019 Decision 9](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)).
A key-encryption key (KEK) wraps every stored key. Only the signer role holds
the KEK and the private keys. This page says what the store holds, how keys
get into it, how they are replaced, and what relying parties do with the
published keys. What QAuth imports is verified against
`libs/server/keys/src/lib/environment-keys.ts`.

QAuth signs tokens with up to three key types:

| Key             | Variable needed?                                              | Signs                                                           |
| --------------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| EdDSA (Ed25519) | No — generated for a fresh realm                              | Access tokens always; ID tokens when the realm has no RS256 key |
| RS256           | No — generated for a fresh realm; import one to keep yours    | ID tokens, when the realm has one (access tokens stay EdDSA)    |
| ML-DSA-65 seed  | No — generated with the Ed25519 key when hybrid signing is on | The post-quantum half of a hybrid access token                  |

## The key store

The store has two tables. `realm_keys` holds each key's private material,
wrapped under the KEK; only the signer reads it. `realm_public_keys` holds the
public halves, which every process reads to verify tokens and to serve the
JWKS, without a KEK.

A key has one of four statuses:

| Status        | Signs | Verifies | In the JWKS                   |
| ------------- | ----- | -------- | ----------------------------- |
| `next`        | No    | No       | Yes, before it signs          |
| `active`      | Yes   | Yes      | Yes                           |
| `retired`     | No    | Yes      | Yes, until its retention ends |
| `compromised` | No    | No       | No                            |

A realm has one active key per purpose and algorithm. A fresh default realm
gets these keys at its first boot:

| Purpose         | Algorithm | When                   | Published at                                     |
| --------------- | --------- | ---------------------- | ------------------------------------------------ |
| `token_signing` | EdDSA     | Always                 | `/.well-known/jwks.json`                         |
| `token_signing` | RS256     | A fresh realm only     | `/.well-known/jwks.json`                         |
| `token_signing` | ML-DSA-65 | With hybrid signing on | `/.well-known/jwks.json`                         |
| `event_signing` | EdDSA     | Always                 | `/ssf/jwks.json`, for the SSF transmitter's SETs |
| `cookie_hmac`   | HS256     | Always                 | Never: it signs the browser cookies              |
| `data_at_rest`  | A256GCM   | Always                 | Never: it encrypts the realm's secrets           |

The OID4VP request-signing key exists only when the key boot step imports it
from `OID4VP_VERIFIER_SIGNING_KEY`. A key a realm lacks, such as an RS256 key
for an upgraded realm, is added with
[`auth-server:keys:create`](#adding-a-key-auth-serverkeyscreate).

## The KEK

Every stored key is wrapped with the KEK. `KEK_PROVIDER` picks where the KEK
lives. The default, `local`, reads `KEK` or `KEK_PATH`.

**Make one.** The KEK is the standard base64 of exactly 32 random bytes:

```bash
mkdir -p -m 700 ~/qauth-secrets
(umask 077 && openssl rand -base64 32 > ~/qauth-secrets/qauth-kek)
```

Set `KEK_PATH` to the file, or `KEK` to its content. `KEK_PATH` wins when both
are set. The server warns when group or others can read or write the file.
Hex and base64url values are refused.

`umask 077` keeps the file its owner's alone from the start. Keep it in a
directory of its own, outside any git checkout and apart from the database
backups. In a container the server reads the file as its own user, uid `1001`
in QAuth's image. A Compose secret from a file is the host file, with its
owner and mode, so give it to that user:
`sudo chown 1001 ~/qauth-secrets/qauth-kek`.

**Where it goes.** Only a process whose `SERVICE_ROLES` holds `signer`, or is
`all`, receives the KEK. Any other process refuses to boot when it finds one
([Service roles](/operate/service-roles/#keys-stay-on-the-signer)).

**Keep it apart from the database.** The database, and every backup of it,
holds the stored keys, wrapped. Whoever has a backup and the KEK has every
key. Never store the KEK in the database backup. Back it up on its own, for
example in a secret manager and once more offline. Restoring a backup needs the
KEK it was taken under.

**Losing it loses every stored key.** Nothing opens a stored key without the
KEK that wrapped it, and nothing recovers one. The signing keys, the cookie
key and the data-at-rest key are lost, and with the last one the realm's
encrypted secrets, such as the mail password. The server cannot sign a token
or a cookie any more, and `/ready` fails its `kek` check.

**Without a KEK.** `NODE_ENV=production` refuses to start without one, and
refuses the published development KEK. Outside production the server falls
back to that development KEK and warns. It refuses to import a key variable
under it in every environment: the development KEK would protect nothing.

**A previous KEK.** `KEK_PREVIOUS` (or `KEK_PREVIOUS_PATH`) holds the KEK in
use before a change of KEK. Keys wrapped under it still open; every new key is
wrapped under `KEK`. Nothing re-wraps a stored key yet: the KEK rotation
([#545](https://github.com/qauth-labs/qauth/issues/545)) will. Until then a
key wrapped under the previous KEK opens only while `KEK_PREVIOUS` holds it.

**A key management service.** An optional adapter package can keep the KEK
in a key service instead. Two ship. For example, `KEK_PROVIDER=aws-kms` with
`@qauth-labs/keys-aws-kms`, which sends data keys to AWS KMS to be wrapped and
unwrapped, while signing stays in QAuth. Its
[guide](https://github.com/qauth-labs/qauth/blob/main/libs/keys/aws-kms/README.md)
gives the settings, the IAM policy of the signer role and what happens when
KMS is unavailable. `KEK_PROVIDER=vault` with `@qauth-labs/keys-vault` keeps it
in a Vault Transit key, logging in with a token file or AppRole; its
[guide](https://github.com/qauth-labs/qauth/blob/main/libs/keys/vault/README.md)
gives the settings, the Vault policy of the signer role and the token renewal.
The auth-server image holds neither package: install the one you need into
your image. Choose the provider before the first boot that stores keys: a key
wrapped under one KEK does not open under another.

## The key boot step

At every boot the server runs a key step for the default realm, on every
process that holds the signer, after the realm's own step and under an
advisory lock, so nodes that start together do it once:

1. It imports each key variable the realm's store does not hold yet:
   `JWT_PRIVATE_KEY` as the Ed25519 signing key, `JWT_RS256_PRIVATE_KEY` as the
   RS256 one, `JWT_MLDSA_PRIVATE_KEY` (with `HYBRID_SIGNING_ENABLED` on) as the
   ML-DSA-65 key of the hybrid pair, `SESSION_COOKIE_SECRET`, when you set it,
   as the cookie key, and `OID4VP_VERIFIER_SIGNING_KEY` as the wallet
   verifier's request-signing key. A `_PATH` variable counts as its variable.
   A key variable that holds a key the store lacks replaces the store's active
   key of its kind (see [Replacing a signing key](#replacing-a-signing-key) and
   [Replacing the cookie key](#replacing-the-cookie-key)).
2. It creates the keys the realm still lacks: the event-signing and
   data-at-rest keys, and the cookie key when `SESSION_COOKIE_SECRET` is unset.
   A realm that neither holds nor imports a signing key gets an Ed25519 and an
   RS256 signing key (and, with hybrid signing on, the ML-DSA-65 key of the
   pair), so a fresh deployment needs no key variable at all.
3. It logs `realm keys ready`, naming each key it imported or created by
   purpose, algorithm and `kid`.
4. It warns once for each key variable that is still set, naming it.

Each imported key keeps `JWT_RS256_KID` or `JWT_MLDSA_KID` as its `kid` when
set, and otherwise gets the RFC 7638 thumbprint of its public key. The cookie
key gets a random `kid`. The keys themselves do not change, so tokens signed
before the upgrade still verify.

The boot stops, and names the variable, when:

- a key must be imported and no KEK is set;
- `JWT_PUBLIC_KEY` or `JWT_RS256_PUBLIC_KEY` is not the public half of its
  private key;
- `JWT_RS256_PRIVATE_KEY` is shorter than 2048 bits (RFC 7518 §3.3);
- a new key comes with a `JWT_RS256_KID` or `JWT_MLDSA_KID` that already
  names a stored key: a new key needs a new `kid`;
- with hybrid signing on, only one of `JWT_PRIVATE_KEY` and
  `JWT_MLDSA_PRIVATE_KEY` holds a new key: the two keys of a pair are stored,
  and replaced, together;
- with hybrid signing on, the realm's active Ed25519 signing key has no
  ML-DSA-65 key beside it: tokens would be signed classical-only. Set
  `JWT_PRIVATE_KEY` and `JWT_MLDSA_PRIVATE_KEY` to a new pair, or turn hybrid
  signing off.

A key variable never holds a key another realm stores: the step refuses to
import one, naming the variable, so a token signed by one realm's key never
verifies as another realm's.

The key variables are read only by this step. Once the store holds a key, the
variable signs nothing, and a new key in it is how you replace the stored one.
The server boots without them. Each boot warns about every one still set:

```text
JWT_PRIVATE_KEY is in the realm's key store, which signs the tokens: the variable is read only at boot, where a new key in it replaces the stored key and unpublishes the old one at once. Remove it unless you may roll back to a release that signs with it.
```

Remove them once you no longer need to roll back to a release that signs with
them. [Remove the key variables](/operate/upgrades/#remove-the-key-variables)
says when, and which public key to keep a little longer. Production refuses
every `SESSION_COOKIE_SECRET` value QAuth's examples published
([Replacing the cookie key](#replacing-the-cookie-key)).

### Tokens are signed through the key store

Every access token, ID token and hybrid token is signed with the keys of the
realm it is issued in, by the signer. The token's `iss` is the realm's issuer,
and its protected header names the key that signed it in `kid` (a hybrid token
also names its ML-DSA-65 key in `pqc_kid`). Each realm publishes its own keys
at its own `/.well-known/jwks.json`, and the server verifies a token only with
the keys of the realm the request is for, so a token one realm issued is
refused by another.

The server picks the key by the token's `kid` and `alg` together, from the
realm's verification set: its active keys, and its retired keys until their
retention ends. A `next` key and a `compromised` key verify nothing. A hybrid
token's ML-DSA-65 key is found the same way, by its `pqc_kid`. Every process
reads a realm's key list again at most every 60 seconds.

A token issued before the upgrade to 0.2 carries no `kid`. It still verifies,
but only against the Ed25519 key that `JWT_PRIVATE_KEY` or `JWT_PUBLIC_KEY`
holds, never against a key the store generated. Keep one of them set until the
tokens issued before the upgrade have expired (the longest access token
lifetime of any realm, a development client's included): the next release
refuses every token without a `kid`.

If `JWT_ISSUER` ends with a slash, the tokens now name the issuer without it,
as discovery does, while 0.1 named it with the slash. Upgrade such a
deployment all at once rather than node by node: in a mixed fleet each release
refuses the other's access tokens until they expire. A relying party that
compares `iss` with the slashed form must drop the slash.

## Rotation

### The rotation windows

ADR-019 fixes how a scheduled or manual rotation overlaps the old and the new
key, so that a relying party's JWKS cache never meets a token signed by a key
it has not seen, and nobody signs in again:

| When                       | The old key                          | The new key                                     |
| -------------------------- | ------------------------------------ | ----------------------------------------------- |
| 7 days before the rotation | `active`: signs                      | `next`: in the JWKS, signs and verifies nothing |
| The rotation               | `retired`: in the JWKS, verifies     | `active`: signs                                 |
| 14 days after the rotation | Leaves the JWKS and verifies nothing | `active`                                        |

- The next key is published **7 days** before it starts signing.
- A retired key stays published **14 days** after the rotation, and never for
  less than the longest lifetime of a token it signed. An access token lives at
  most a day (`ACCESS_TOKEN_LIFESPAN` is capped at 86400 seconds), so 14 days
  covers every token.
- A key rotates every **90 days**.
- Both keys of a hybrid pair rotate together. The cookie key and the
  data-at-rest key rotate the same way: the new key signs or encrypts, and the
  old one only verifies or decrypts until it is retired.

The key library carries these defaults (`DEFAULT_KEY_PREPUBLISH_DAYS`,
`DEFAULT_KEY_RETIRED_RETENTION_DAYS` and `DEFAULT_KEY_ROTATION_PERIOD_DAYS` in
`libs/server/keys/src/lib/key-purposes.ts`). In this release nothing rotates a
token signing key on a schedule: automatic rotation is
[#542](https://github.com/qauth-labs/qauth/issues/542). Until it ships, a key
changes only when you [replace it through its variable](#replacing-a-signing-key),
which is not a rotation: the new key signs at once, and the old key leaves the
JWKS at once.

### Manual rotation

A manual rotation will be an admin API security operation
([#544](https://github.com/qauth-labs/qauth/issues/544)): it needs the
`qauth:admin:security` scope and a fresh passkey approval, and it follows the
windows above. The admin API has no key operation in this release.
`auth-server:keys:create --status next` publishes a next key, but nothing makes
a next key active yet.

### Emergency retirement

An emergency retirement will retire a key that may be compromised as soon as
the retirement is approved, without the overlap
([#551](https://github.com/qauth-labs/qauth/issues/551)):

- the key leaves the JWKS at once, and a new key starts signing;
- its `kid` goes on a denylist that every verifier inside the auth server
  checks, whatever a JWKS cache holds, and introspection answers
  `active: false` for a token it signed;
- every session and refresh-token family issued under the key is revoked, with
  back-channel logout;
- a critical admin event and a security event naming the `kid` go out on every
  event route;
- it needs `qauth:admin:security`, a fresh passkey and the second admin where
  the realm requires one. When no second admin can approve in time, the
  break-glass CLI on a host that holds the database credentials and the KEK
  does it.

None of this is in this release. To cut off a signing key that may be
compromised today, replace it through its variable
([below](#replacing-a-signing-key)) and restart **every** node: the old key
leaves the JWKS and stops verifying at once on a restarted node, and within a
minute on one that keeps running. Tokens it signed stop verifying at QAuth's
endpoints. A relying party stops trusting it once its own JWKS cache expires,
at most 5 minutes later if it follows [the JWKS rule](#what-relying-parties-do-with-the-jwks).
Refresh tokens are not signed, so the replacement does not end them. For a
leaked cookie secret, see [Replacing the cookie key](#replacing-the-cookie-key).

### Replacing a signing key

Until rotation through the key store ships, you replace a signing key as
before the key store: put the new key in its variable and restart. At boot, a
key variable that holds a key the store lacks replaces the store's active key
of that algorithm. The old key is retired and leaves the JWKS at once, so
tokens it signed stop verifying. Each node logs a warning with the new and the
retired `kid`.

- Give a new RS256 or ML-DSA-65 key a new `JWT_RS256_KID` or `JWT_MLDSA_KID`,
  or unset the variable to use the key's thumbprint.
- With hybrid signing on, change `JWT_PRIVATE_KEY` and `JWT_MLDSA_PRIVATE_KEY`
  together. Turning hybrid signing on after the upgrade is such a replacement:
  set a new `JWT_PRIVATE_KEY` along with the ML-DSA-65 key.
- A variable that holds a key the store retired changes nothing in the store,
  and each boot warns about it: the store keeps its active key, which signs. So
  a node that still has the old value during a rolling restart boots, and
  warns.

### The browser cookies

The session cookie, the login-CSRF cookie and the wallet-flow cookie are signed
with the realm's `cookie_hmac` key, which the signer hands the browser-facing
role. Each value is `<kid>.<payload>.<mac>`: it names the key that signed it,
and its HMAC-SHA256 covers the cookie's name, the realm id, the `kid` and the
payload, so a value never passes for another cookie or for a cookie of another
realm, even if two realms held the same key. A new cookie is signed with the
realm's current key. A cookie of the previous key, the one the last
replacement retired, still verifies until the next replacement. A cookie that
does not verify is cleared; one that names a key the process has not read yet
is left for the next request.

Each process reads a realm's cookie keys from the signer at most once a minute,
and once more, at most every five seconds, when a cookie names a key it has not
read yet. The session cookie's `Max-Age` is the time left until the session's
absolute end. A cookie 0.1 signed with `SESSION_COOKIE_SECRET` does not
verify: its user signs in again
([the upgrade guide](/operate/upgrades/#users-sign-in-once-more-after-the-upgrade-to-v02)).

A process without the signer role gets the cookie keys from the signer service,
which this release cannot call
([#497](https://github.com/qauth-labs/qauth/issues/497)): its browser routes
that read or set a signed cookie answer 503, and `/auth/logout` there ends the
sessions and tokens but leaves the cookie for the next page to clear.

### Replacing the cookie key

You replace the cookie key through `SESSION_COOKIE_SECRET`, as for a signing
key: set a new secret, at least 32 characters, and restart. At boot, each
stored cookie key is opened with the KEK and compared with the variable in
constant time. A secret the store lacks becomes the active cookie key, and the
one it replaces is retired: unlike a replaced signing key, it stays the realm's
previous cookie key and keeps verifying the cookies it signed until the next
replacement, so nobody is signed out. The node that replaces it logs a warning
with the new and the retired `kid`. A variable that holds a cookie key the
store retired changes nothing, and each boot warns about it, so a node that
still has the old value during a rolling restart boots. To tell a new secret
from a retired key, the boot opens every stored cookie key, so a retired one
sealed under a KEK that is no longer configured refuses the boot of any node
whose secret differs from the active key: keep `KEK_PREVIOUS` set after a
change of KEK.

To cut off a leaked cookie secret, replace it twice, restarting after each new
secret: the second replacement drops the leaked key from the previous slot. A
restarted node refuses the cookies it signed at once. A node that keeps
running can accept them for up to about two minutes after the replacement, as
it keeps a realm's cookie keys for up to a minute and the signer it reads them
from keeps its own list for up to a minute too; restart every node to cut that
window.

If `SESSION_COOKIE_SECRET` holds a value from QAuth's own examples
(`.env.example`, or the `.env.docker.example` of earlier releases), anyone can
sign cookies with it: production refuses to start with it. Set a new secret
first, so the boot step replaces the stored key, and only then remove the
variable; removing it alone leaves the stored key as it is.

## Adding a key: `auth-server:keys:create`

On a host that holds the KEK, with the server's environment, one command
creates a key for a realm, purpose and algorithm. The usual case is an RS256
key for a realm that has none. A deployment upgraded from 0.1 without
`JWT_RS256_PRIVATE_KEY` is one: it signs its ID tokens with EdDSA, which the
OpenID Foundation's certification refuses.

```bash
# From a checkout, with the server's environment:
pnpm nx run auth-server:keys:create --purpose=token_signing --algorithm=RS256

# In the auth-server image, from /app:
tsx src/keys-create.ts --purpose token_signing --algorithm RS256

# With Docker Compose:
docker compose exec auth-server tsx src/keys-create.ts --purpose token_signing --algorithm RS256
```

| Flag          | Default               | Meaning                                                                                                                                            |
| ------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--purpose`   | required              | The key's purpose, such as `token_signing`, `event_signing` or `cookie_hmac`. `trust_anchor` is refused.                                           |
| `--algorithm` | the purpose's default | The algorithm, such as `EdDSA` or `RS256` for `token_signing`. ML-DSA-65 is never created alone: with hybrid signing on, `EdDSA` creates the pair. |
| `--realm`     | `DEFAULT_REALM_NAME`  | The realm that gets the key.                                                                                                                       |
| `--status`    | `active`              | `active`, or `next` for a key that is published before it signs.                                                                                   |
| `--scope`     | none                  | The scope of a purpose that has one per subscription or upstream, such as `webhook_signing`; refused for any other purpose.                        |

It prints each new key as one JSON line, with its `kid`, status and public JWK,
and exits `0`. A usage error exits `2`, and any other error, such as a realm
that already has an active key of that purpose and algorithm, exits `1` with a
message on stderr. It takes the realm's advisory lock, so it does not race a
booting node.

A new active RS256 key signs the realm's ID tokens as soon as each process
reads the realm's key list again, within a minute, and discovery lists `RS256`
in `id_token_signing_alg_values_supported`. Leave `JWT_RS256_PRIVATE_KEY` unset
afterwards: a key in it would replace the one you created at the next boot.

A realm has one active key per purpose and algorithm, so the command cannot
replace one: a second active key is refused, and a `next` key is published but
never made active until rotation ships (#542). Replace a signing key through its
variable meanwhile.

## What relying parties do with the JWKS

A relying party or resource server that verifies QAuth's tokens itself follows
one rule (ADR-019 Decision 9):

- **Cache the JWKS for at most 5 minutes.** `/.well-known/jwks.json` answers
  `Cache-Control: public, max-age=300`.
- **Fetch it again when a token names a `kid` the cached set lacks, at most
  once a minute.** A token whose `kid` is still unknown after that fetch is
  refused, not retried.
- **Drop every key the JWKS no longer lists.** A key leaves the JWKS when its
  retention ends, or when it is replaced or retired as compromised. A token it
  signed must stop verifying then.

Pick the key by `kid` and `alg` together, never by `kid` alone.
`@qauth-labs/resource-guard` follows the rule by default: its `jwksCacheTtlMs`
is 5 minutes, which is also the least time between two fetches, and each fetch
replaces the whole cached set. The
[OAuth 2.1 flow](/integrate/oauth-flow/#caching-the-jwks) page has the
details.

The 7-day pre-publication and the 14-day retention are far longer than this
cache, so a rotation through the store will change nothing for a relying party
that follows the rule. A key replaced through its variable leaves the JWKS at
once: such a relying party refuses the old key's tokens within 5 minutes.

The token keys sign
[back-channel logout tokens](/integrate/oauth-flow/#back-channel-logout) too,
in the algorithm of the realm's ID tokens, as OpenID Connect Back-Channel
Logout 1.0 §2.4 asks: a relying party verifies them at this JWKS, as it
verifies ID tokens.

## Key formats

### PEM keys: PKCS#8 recommended

Generate every private key with `openssl genpkey`, which writes **PKCS#8** PEM
(first line `-----BEGIN PRIVATE KEY-----`) on every OpenSSL version. The key
boot step reads PKCS#8, and for RSA also **PKCS#1**
(`-----BEGIN RSA PRIVATE KEY-----`), and stores either as PKCS#8. 0.1 reads
PKCS#8 only and refuses a PKCS#1 key at boot, so keep the variable in PKCS#8
for as long as you may roll back to it. To convert a PKCS#1 key:

```bash
openssl pkcs8 -topk8 -nocrypt -in old-rsa-key.pem -out jwt-rs256-private.pem
```

Which format `openssl genrsa` writes depends on your OpenSSL: since 3.0 it
writes PKCS#8 unless you pass `-traditional`; 1.1.x and earlier write PKCS#1.

Public keys, where you supply one, must be **SPKI PEM**
(`-----BEGIN PUBLIC KEY-----`). `openssl pkey -pubout` (used below) always
writes this format.

### EdDSA (Ed25519)

Signs access tokens unconditionally, and ID tokens whenever the realm has no
RS256 key. A fresh realm gets one generated; set a variable only to bring the
key a deployment already signs with, or to replace the stored key.

```bash
openssl genpkey -algorithm Ed25519 -out jwt-ed25519-private.pem
openssl pkey -in jwt-ed25519-private.pem -pubout -out jwt-ed25519-public.pem
```

Set `JWT_PRIVATE_KEY` (or `JWT_PRIVATE_KEY_PATH`) to the private key. The key
step derives the public half itself, with `node:crypto`; `JWT_PUBLIC_KEY` (or
`JWT_PUBLIC_KEY_PATH`) is optional, and the boot stops when it is set and is
not the private key's public half.

Before tokens were signed through the key store, the JWT plugin also imported
the key and could not derive its public half, so a boot without
`JWT_PUBLIC_KEY` failed ([issue #359](https://github.com/qauth-labs/qauth/issues/359)).
The plugin no longer holds a key, so that failure no longer happens.

### RS256 — optional, for OIDF certification

OpenID Foundation Basic/Config OP certification hard-fails an EdDSA-only OP on
its `id_token` signature test, so a realm with an RS256 key signs its ID tokens
with RS256; access tokens are unaffected (always EdDSA). A fresh realm gets one
generated. A deployment that upgraded without `JWT_RS256_PRIVATE_KEY` has none
and keeps signing ID tokens with EdDSA, until you import one with the variable
or [create one](#adding-a-key-auth-serverkeyscreate).

**It must be at least 2048 bits, and the boot checks it.** The key boot step
refuses a shorter `JWT_RS256_PRIVATE_KEY` (RFC 7518 §3.3): the server stops at
startup with an `InvalidConfigurationError` that names the variable and gives
the key's length in its details, and it stores nothing.

```bash
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out jwt-rs256-private.pem
openssl pkey -in jwt-rs256-private.pem -pubout -out jwt-rs256-public.pem

# The size, if you want to see it:
openssl rsa -in jwt-rs256-private.pem -noout -text | head -1
# → "Private-Key: (2048 bit, 2 primes)" (or larger)
```

Set `JWT_RS256_PRIVATE_KEY` (or `_PATH`); `JWT_RS256_PUBLIC_KEY` (or `_PATH`)
is optional, as for EdDSA: the key step derives the public half itself. An
optional `JWT_RS256_KID` gives the published RSA JWK a stable `kid`; without
it the key's `kid` is its RFC 7638 thumbprint.

For the full certification flow — deploying, driving the conformance suite,
and the residual-uncertainty checklist — see the
[OIDF OP Certification Runbook](https://github.com/qauth-labs/qauth/blob/main/docs/oidf-op-certification-runbook.md).

### ML-DSA-65 seed — only with hybrid signing

Only used when `HYBRID_SIGNING_ENABLED=true` (default `false` — post-quantum
hybrid signing is opt-in). A fresh realm with hybrid signing on gets the pair
generated; set the variable to import a seed you already have, together with
`JWT_PRIVATE_KEY`. Unlike EdDSA/RS256, this is not a PEM key: QAuth's
canonical private form is the raw **32-byte seed**, base64url-encoded,
unpadded (`libs/server/config/src/lib/schemas/crypto.ts` validates exactly
this shape at startup — wrong length or alphabet fails fast with a clear
message, without printing the seed).

Generate 32 CSPRNG bytes and encode them as unpadded base64url:

```bash
openssl rand 32 | base64 | tr '+/' '-_' | tr -d '=\n'
```

Set the result as `JWT_MLDSA_PRIVATE_KEY` (or point
`JWT_MLDSA_PRIVATE_KEY_PATH` at a file containing it). Hybrid signing also
needs `SIGNING_ALGORITHM_MODE=ed25519+ml-dsa-65`, or the boot fails fast, and a
realm whose active Ed25519 key has no ML-DSA-65 key beside it refuses to boot.
An optional `JWT_MLDSA_KID` names the key in the published JWKS.

**Treat the seed like a private key** — anyone with it can forge the
post-quantum component of a hybrid token.

See the [PQC Verifier Guide](/operate/pqc-verifier-guide/) for what changes
for token verifiers once this is on, and the
[Security Gate Review](/reference/records/security/005-pqc-hybrid-signing-review/) for
the reviewed behavior and the pre-default-on checklist.

## Environment variables

Verified against `libs/server/config/src/lib/schemas/jwt.ts`,
`libs/server/config/src/lib/schemas/crypto.ts`, the KEK keys of the
configuration registry and the two adapters' settings.

| Variable                          | Default                                               | What it is                                                                       |
| --------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
| `KEK_PROVIDER`                    | `local`                                               | Where the KEK lives: `local`, or an adapter's name, such as `aws-kms` or `vault` |
| `KEK` / `KEK_PATH`                | none; outside production, a published development KEK | The KEK of the `local` provider, as base64 of 32 bytes; the file wins            |
| `KEK_PREVIOUS` / `_PATH`          | none                                                  | The KEK in use before a change of KEK; only opens keys                           |
| `KEK_AWS_KMS_KEY_ID`              | none; required with `aws-kms`                         | The key ARN of a symmetric KMS key                                               |
| `KEK_AWS_REGION`                  | the region the ARN names                              | The key's region; must agree with the ARN                                        |
| `KEK_VAULT_ADDR`                  | none; required with `vault`                           | The `https://` origin of the Vault server                                        |
| `KEK_VAULT_TRANSIT_KEY`           | none; required with `vault`                           | The name of the Transit key that is the KEK                                      |
| `KEK_VAULT_TRANSIT_MOUNT`         | `transit`                                             | The path the Transit engine is mounted at                                        |
| `KEK_VAULT_NAMESPACE`             | none                                                  | The Vault namespace, sent as `X-Vault-Namespace`                                 |
| `KEK_VAULT_CA_CERT_FILE`          | none; Node's own CA certificates                      | A PEM file of the CAs that sign Vault's certificate                              |
| `KEK_VAULT_TOKEN_FILE`            | none                                                  | Token login: a file holding a Vault token                                        |
| `KEK_VAULT_ROLE_ID`               | none                                                  | AppRole login: the role ID                                                       |
| `KEK_VAULT_SECRET_ID_FILE`        | none                                                  | AppRole login: a file holding a secret ID                                        |
| `KEK_VAULT_APPROLE_MOUNT`         | `approle`                                             | The path the AppRole auth method is mounted at                                   |
| `JWT_PRIVATE_KEY` / `_PATH`       | none                                                  | EdDSA: imported into the key store when set                                      |
| `JWT_PUBLIC_KEY` / `_PATH`        | derived from the private key                          | EdDSA: checked when set; verifies tokens without a `kid`                         |
| `JWT_RS256_PRIVATE_KEY` / `_PATH` | none                                                  | RS256: imported when set                                                         |
| `JWT_RS256_PUBLIC_KEY` / `_PATH`  | derived from the private key                          | RS256: checked when set                                                          |
| `JWT_RS256_KID`                   | the key's thumbprint                                  | RS256: the imported key's `kid`                                                  |
| `JWT_MLDSA_PRIVATE_KEY` / `_PATH` | none                                                  | ML-DSA: imported with `JWT_PRIVATE_KEY` as a hybrid pair when set                |
| `JWT_MLDSA_KID`                   | the key's thumbprint                                  | ML-DSA: the imported key's `kid`                                                 |
| `HYBRID_SIGNING_ENABLED`          | `false`                                               | Signs hybrid access tokens                                                       |
| `SIGNING_ALGORITHM_MODE`          | `ed25519`                                             | Must be `ed25519+ml-dsa-65` for hybrid signing                                   |

## See also

- [Upgrades](/operate/upgrades/#upgrading-from-01-to-02) — the upgrade to 0.2
  that imports the key variables, and when to remove them.
- [Topology](/operate/topology/) — where the signer and the KEK sit in a
  deployment.
- [Docker](/operate/docker/) — where these keys get mounted into the stack.
- [Service roles](/operate/service-roles/) — which processes may hold these
  keys once the roles run apart.
- [PQC Verifier Guide](/operate/pqc-verifier-guide/) — the ML-DSA key from a
  verifier's perspective.

---

# Observability Guide

URL: https://docs.qauth.dev/operate/observability/

This guide covers QAuth's observability surface: structured logging, request-id
tracking, auth-event logging, failed-login tracking/lockout, health and
readiness, Prometheus metrics, events exported as OpenTelemetry logs, and
recommended alerting.

## Overview

| Capability                | Mechanism                                                         |
| ------------------------- | ----------------------------------------------------------------- |
| **Structured logging**    | pino (built into Fastify) with secret redaction                   |
| **Request-id tracking**   | `genReqId` + `REQUEST_ID_HEADER`, echoed on responses             |
| **Auth-event logging**    | Structured `authEvent` log lines for login/register/logout/token  |
| **Failed-login tracking** | Redis-backed per-identifier counters with temporary lockout       |
| **Health and readiness**  | `GET /health` (liveness) and `GET /ready` (per-role checks)       |
| **Metrics**               | `GET /internal/metrics` on the internal listener, Prometheus text |
| **Event export**          | Every event as an OpenTelemetry log record, off by default        |
| **Background jobs**       | Periodic jobs, one node at a time under a Postgres advisory lock  |
| **Event delivery**        | Each event to each delivery destination, at least once            |
| **Alerting**              | Prometheus Alertmanager rules (see below)                         |

## Structured Logging

QAuth logs through Fastify's built-in [pino](https://getpino.io) logger. Output
is JSON by default — suitable for log shippers (Loki, Elasticsearch, Datadog,
CloudWatch, ...).

- `LOG_LEVEL` — `fatal | error | warn | info | debug | trace` (default `info`).
- `LOG_PRETTY` — when `true` **and** `NODE_ENV != production`, output is routed
  through [`pino-pretty`](https://github.com/pinojs/pino-pretty) for colourised,
  human-readable local development. Production always emits JSON.

### Secret redaction

The logger is configured with a pino `redact` allowlist that replaces sensitive
values with `[Redacted]`. The paths are `LOG_REDACT_PATHS` in
`apps/auth-server/src/config/logger.ts`, and they fall into three groups:

- **Credential-bearing headers** — `req.headers.authorization`,
  `req.headers.cookie`, `res.headers["set-cookie"]`.
- **Top-level plus one level of nesting** (each field also has a `*.field`
  twin) — `password`, `token`, `access_token`, `refresh_token`, `id_token`,
  `client_secret`, `secret`.
- **Top-level only** (no `*.` twin) — `newPassword`, `currentPassword`,
  `subject_token`, `actor_token`, `code`, `code_verifier`, `authorization`.

Two limits follow from that shape. A field in the last group is redacted only at
the root of a logged object: `log.info({ code_verifier })` is redacted,
`log.info({ body: { code_verifier } })` is not. And pino's `*` matches exactly
**one** level, so even a field with a `*.` twin is missed deeper down
(`{ a: { b: { password } } }`). No route logs a request body, so nothing reaches
a log sink today — read the list as the shape of the backstop, not as
full-depth coverage. A regression test (`logger.test.ts`) drives the real pino
config end to end and asserts that a payload carrying these fields (including
one nested level) is serialised with `[Redacted]` in their place.

> Callers must still avoid passing secrets into log payloads; redaction is a
> defence-in-depth backstop, not a license to log credentials.

## Request-ID Tracking

Every request gets a request id, surfaced as `reqId` on all of its log lines:

- An inbound `REQUEST_ID_HEADER` (default `x-request-id`) is honoured for
  distributed tracing/propagation.
- When absent, a UUID is generated (`genReqId`).
- The id is **echoed back** on the response's `REQUEST_ID_HEADER` by the
  request-id plugin (`apps/auth-server/src/app/plugins/request-id.ts`), so a
  caller can correlate a response — and its server logs — with the request.

## Auth-Event Logging

Login, logout and registration emit structured log lines via `logAuthEvent`
(`apps/auth-server/src/app/helpers/auth-events.ts`) on both success and
failure. A registration of an address that already has an account logs
`user.register.failure` with `reason` `address_in_use`, or
`address_in_use_mail_capped` when the per-address mail caps held back the
notice. The caller got the same `202` either way; only this line tells them
apart.

> ⚠️ **Token-exchange events are not log lines.** `logAuthEvent` is called only
> from `routes/auth/login.ts`, `routes/auth/logout.ts` and
> `routes/auth/register.ts`. The `oauth.token.exchange.*` names exist as members
> of the event type union, but the token endpoint records them **only as events**
> (`token.issued`, `token.request_failed`) in the event store, never through the
> logger. An alert built on an `oauth.token.exchange.success` log line will never
> fire — read the event store for those instead. Since 0.2.0 nothing writes the
> `audit_logs` table; it stays read-only until a later release drops it.

Each emitted line carries:

- `authEvent` — e.g. `user.login.success`, `user.login.failure`.
- `success`, `userId`/`clientId` (when known), `ip`, ISO `timestamp`, and
  `reqId`.
- On **failure** paths, the email is logged as a SHA-256 `emailHash` rather than
  the raw address, to avoid account enumeration. Passwords/tokens are never
  logged.

These structured logs complement the durable `audit_logs` database trail.

## Failed-Login Tracking & Lockout

Failed logins are tracked per realm and identifier (email **hash** and source IP)
in Redis (`apps/auth-server/src/app/helpers/failed-login.ts`). Each realm counts
its own: the same address in two realms is two accounts, and a source address
locked out in one realm is not locked out in another. The rate limits keep a
bucket per realm and address the same way. Each realm also sets its own
thresholds, in its `bruteForce` policies on the realm row
([Realm policies](/reference/realm-policies/)): after `maxAttempts` failures
inside `windowSeconds`, the identifier is locked out for `lockoutSeconds`;
further login attempts return `429 Too Many Requests` with a `Retry-After`
header before any credential verification. A realm whose `bruteForce.enabled`
is off counts nothing and never locks out.

- An attempt is counted **before** its password is verified, so guesses sent
  concurrently cannot outrun the counter. A login that ends in a server error
  therefore stays counted too. While the attempt that reaches the limit is
  being verified, other attempts for the same identifier are refused.
- The attempt counter has a TTL equal to the window, so it **decays** naturally.
- A **successful** login clears both the counter and any lockout of its email.
  The source address's counter keeps the failures other attempts left on it
  until they decay; the success gives back only its own count. Users behind
  one shared address (an office NAT, or one IPv6 `/64`) therefore share its
  `maxAttempts` failures per window, and signing in does not clear them.
- All cache operations are **best-effort / fail-open**: if Redis is unavailable,
  logins are never blocked by the tracker — though an instance-wide Redis outage
  still fails the request earlier, at the app-wide rate-limiter's `onRequest`
  hook (see
  [Hosted UI](/integrate/hosted-ui/#what-the-stash-adds-to-the-pre-authentication-path)),
  so "the tracker never blocks" is not the same as "a Redis outage is invisible
  on `POST /auth/login`".

### Configuration

The four keys seed the `bruteForce` policies of a new realm, and of a realm that
had no policies at the first boot after the upgrade that put them on the row.
Once a realm has its policies, a change of a key leaves it as it is: change the
realm's stored policy instead.

| Variable                        | Seeds                       | Default | Description                            |
| ------------------------------- | --------------------------- | ------- | -------------------------------------- |
| `FAILED_LOGIN_TRACKING_ENABLED` | `bruteForce.enabled`        | `true`  | Master switch for throttling/lockout.  |
| `FAILED_LOGIN_MAX_ATTEMPTS`     | `bruteForce.maxAttempts`    | `5`     | Failures in the window before lockout. |
| `FAILED_LOGIN_WINDOW`           | `bruteForce.windowSeconds`  | `900`   | Sliding window in seconds (15 min).    |
| `FAILED_LOGIN_LOCKOUT_DURATION` | `bruteForce.lockoutSeconds` | `900`   | Lockout duration in seconds (15 min).  |

Under Docker Compose they reach the container only because they are listed — see
the Compose caveat below.

### Per-account failure ladder

Beside that lock, every password attempt at `POST /auth/login` and
`POST /ui/login`, and every password the email verification checks
(`POST /auth/verify`, `POST /ui/verify`), is reserved on the per-account
failure ladder (ADR-017 Decision 7), the one the sign-in engine uses too. It is not configurable and
does not depend on the realm's `bruteForce` policy: a realm whose lock is off
(`bruteForce.enabled` false) still counts on the ladder.

- **Counted before the check.** One Redis script reads the account's wait,
  refuses an attempt inside it, and otherwise counts the attempt as a failure
  and sets the next wait, so parallel guesses meet the same ladder as guesses
  sent one at a time. A correct password clears the count.
- **The wait.** From 5 consecutive failures the next attempt waits
  2^(n−5) seconds, capped at 15 minutes. An attempt inside the wait gets
  `429 Too Many Requests` with `Retry-After`, like a locked one, and is neither
  verified nor counted; it counts as `reason="locked_out"` on
  `qauth_login_attempts_total`.
- **Known IPs.** An end-user IP with a successful sign-in to the account in
  the last 30 days (the 16 most recent per account) skips the wait while
  fewer than 20 of the run's counted failures came from such known IPs.
  Once 20 have, its next attempt waits as any other address's does, so a
  shared address (a carrier or office NAT, a VPN exit, or a reverse proxy's
  own address while `TRUST_PROXY` is unset) cannot run free to the hard
  action: alone, it reaches the 100th failure only through the waits, in
  about 20 hours. Failures from other addresses never use the 20 up, so a
  guesser elsewhere cannot keep the owner out. Its attempts still count
  toward the hard action, and a correct password still ends the run.
- **No address in Redis.** The keys are
  `sign-in-ladder:{<realm id>:<identifier HMAC>}:password` and
  `…:known-ips`: the identifier and each known IP are kept as keyed HMACs,
  derived from the realm's cookie HMAC secret. A rotation of that secret
  starts every account's count afresh within a minute. A run of failures is
  kept 2 days after its last counted failure while it has fewer than 5, and
  30 days after its last counted failure once it has reached a wait; a
  correct password ends it sooner. Both follow the count alone, the same
  whether or not an account holds the identifier.
- **Redis memory.** Every address tried, held by an account or not, keeps a
  small hash: 2 days after its last failure while it has fewer than 5, 30
  days after its last failure once it has reached a wait. Let `R` be a
  sustained rate of failed attempts a second at made-up addresses. If each
  address is tried fewer than 5 times, Redis holds about `R × 172,800`
  counters. If each is tried 5 times, so that its counter reaches a wait, it
  holds about `R × 518,400`: 30 days of a fifth of them. A campaign that also
  comes back to each such address before its 30 days run out keeps those
  counters alive. Over months it nears `R × 2,592,000`, the 30 days of
  attempts that a single 30-day retention held. The per-IP rate limits bound
  each client address's share of `R`. Size Redis for the campaign you expect,
  and alert on its memory use.
- **Run Redis with `maxmemory-policy noeviction`.** When Redis is full it
  then refuses new counts, and so every password sign-in (fail closed). An
  evicting policy (`volatile-*`, `allkeys-*`) would drop counts instead,
  which gives those accounts their free tries again. It would also drop the
  access-token revocation list and the client-assertion replay markers, which
  live in the same Redis.
- **Fail closed.** Unlike the lock above, a Redis error, or a call slower than
  2 s, refuses the attempt with `503` and `Retry-After: 5` before any
  credential is checked, and logs `sign-in failure ladder unavailable` at
  `error`.
- **The hard action.** At 100 consecutive counted failures the password is
  disabled (`user_credentials.disabled_at`), the owner is notified and the
  operator alerted with the `error` log `password disabled by the failure
  ladder`. It is armed only while the realm's hosted password reset is on and
  the deployment can send the password-disabled notice; the hosted reset does
  not ship yet, so today every
  failure from the 100th on only logs the warning `password failure ladder reached its hard
  ceiling; the hard action is unarmed, so the password stays usable`, with the
  realm and the user. A mark found while the hard action is unarmed is
  ignored, and the next successful sign-in clears it and logs a warning.
- **Recovery codes.** Wrong recovery codes have a counter of their own, keyed
  on the account (`sign-in-ladder:{<realm id>:user:<user id>}:recovery_code`),
  so every transaction and address shares it and a right password does not
  clear it. From 5 failures each attempt waits as above, with no known-IP
  exemption. At 100 in a row the operator is alerted with the `error` log
  `an account's wrong recovery codes reached the ceiling`, with the realm and
  the user, the account is mailed and `user.recovery_codes_failed` is
  recorded, once a day per account; nothing is disabled.

### Per-address send caps

Every code the sign-in engine mails (a verification, confirmation or
recovery code) is counted in Redis before it is sent (ADR-017 Decision 5).
The tiers are fixed, not configurable, and count unknown addresses too:

| Tier                          | Limit             | At the limit                                   |
| ----------------------------- | ----------------- | ---------------------------------------------- |
| Address and end-user IP       | 3/15 min, 10/24 h | the same answer; the mail quietly dropped      |
| Address and FiPA client       | 10/24 h           | `429` with `Retry-After`                       |
| Address (the ceiling)         | 30/24 h           | `429` with `Retry-After`, the operator alerted |
| Address, after a first factor | 30/24 h           | `429` with `Retry-After`                       |
| End-user IP                   | 10/h              | `429` with `Retry-After`                       |
| FiPA client                   | 1,000/h           | `429` with `Retry-After`                       |

- **Known IPs.** An end-user IP the failure ladder knows for a verified
  account skips every per-address tier. A code mailed after a correct first
  factor skips the ceiling and counts on its own 30 per 24 hours.
- **The ceiling.** The first refusal at an address's ceiling logs
  `an address met the per-address send ceiling` at `error`, with the realm
  and the address's keyed HMAC (never the address), once per address per
  24 hours. It also mails the account, at most once a day, a notice with a
  single-use link (`GET /auth/pass`), valid 24 hours, that takes one reset
  past the per-address tiers; a registration start at an address with no
  account mails that address a registration link instead. The mailed code is
  still required. A realm cannot switch the notice off.
- **No address in Redis.** The keys start `send-caps:{<realm id>}:` and hold
  the address and the end-user IP as the same keyed HMACs as the ladder's.
  A pass is kept only as its SHA-256 hash.
- **Fail closed.** A Redis error, or a call slower than 2 s, fails the start
  rather than mailing uncounted.

### Round limits

Around the per-account ladder, the sign-in engine counts every round per
end-user IP and per network bucket in Redis (ADR-017 Decision 7). A
credential round (a password, a code, a recovery code or a WebAuthn response)
is counted as failed before its credential is checked, and taken back when
it was right. The Interaction API keys the end-user IP as its rate limits
do: an IPv6 client by its /64. The bucket is the IP's /24, or an IPv6
client's /48.

| Row         | At the soft threshold                                                                                         | At the hard limit                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| End-user IP | 10 failed rounds in 15 min: one credential round per 30 s, others `429`                                       | 30 failed rounds: every round `429` for 15 min, alerts |
| Bucket      | failures for more than 20 distinct identifiers in 15 min: each IP of it one credential round per 30 s, alerts |                                                        |

- **Alerts.** Crossing a row's threshold logs
  `a sign-in round limit was crossed` at `error`, once per key per window,
  with the realm, the alert (`end_user_ip_blocked`, `ip_bucket_identifiers`)
  and the IP's or the bucket's keyed HMAC, never an address. A client row
  for the first-party login endpoint adds `client_failure_ratio`,
  `client_failure_budget` and `client_rounds` with the client id, once that
  endpoint ships.
- **Development.** A client whose effective environment (the stricter of the
  client's and the realm's ceiling) is `development` meets ten times the
  counts and a tenth of the delays. `staging` keeps the production numbers.
- **No address in Redis.** The keys start `round-limits:{<realm id>}:` and
  hold the end-user IP and its bucket as keyed HMACs under the ladder's
  label. Every key expires with its window.
- **Fail closed.** A Redis error, or a call slower than 2 s, refuses the
  round with `503` and `Retry-After: 5` before any credential is checked.
- **Peer caps stay.** The engine's routes keep their `@fastify/rate-limit`
  caps on the TCP peer.

## Health and Readiness

Every process answers two probes on its public port, whatever its service
roles. Both answer on any host and carry no realm data, and each is
rate-limited per client address to `HEALTH_RATE_LIMIT_MAX` requests per
`HEALTH_RATE_LIMIT_WINDOW` seconds (1000 per 60 by default) unless
`RATE_LIMIT_ENABLED=false`. The counters are kept in the process's memory
rather than in Redis, so the probes answer while Redis does not.

- **`GET /health` is liveness.** It answers `200` while the process serves, with
  the service roles it runs, and checks no dependency:

  ```json
  {
    "status": "ok",
    "timestamp": "2026-11-02T09:00:00.000Z",
    "roles": ["web", "api", "admin", "signer", "delivery"]
  }
  ```

  Point a liveness probe at it. A process whose database is down is still
  alive, and restarting it would not bring the database back.

- **`GET /ready` is readiness.** It runs the checks of the process's roles at
  once, each within 2 seconds, and answers `200` when every one passes, with
  `"status": "ok"`, the roles and each check's result. When one fails it
  answers `503` with a problem document, as every route outside the OAuth
  protocol endpoints answers an error, whose `roles` and `checks` members say
  the same:

  ```json
  {
    "type": "https://docs.qauth.dev/reference/problem-types/#service-unavailable",
    "title": "Service unavailable",
    "status": 503,
    "detail": "A readiness check failed: redis.",
    "instance": "/ready",
    "code": "service_unavailable",
    "trace_id": "req-1a2b3c",
    "roles": ["api"],
    "checks": {
      "database": { "status": "ok" },
      "redis": { "status": "fail", "reason": "timeout" }
    }
  }
  ```

  Point a readiness probe, a load balancer's health check or a Compose
  `healthcheck` at it. The Compose file's `auth-server` service does.

| Check      | Runs on               | Passes when                                                                                                                                                                             |
| ---------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `database` | every role            | Postgres answers `SELECT 1`.                                                                                                                                                            |
| `redis`    | `web`, `api`, `admin` | Redis answers `PING`. It still holds the rate limits and the single-use stores those roles use.                                                                                         |
| `kek`      | `signer`              | The KEK provider reports itself usable and unwraps one stored key for each KEK reference in use. A pass stands for 30 seconds and a failure for 5, as an unwrap may be a call to a KMS. |
| `outbox`   | `delivery`            | The event delivery queue can be read.                                                                                                                                                   |

A failed check gives a `reason`: `error` when the dependency refused or failed,
`timeout` when it gave no answer within 2 seconds. The error itself goes to the
log, never to the answer, which any caller can read: the warning
`A readiness check fails: GET /ready answers 503 until it passes` once when a
check starts failing, with the check's name and the error, and an info line
when it passes again. Requests that arrive while a check runs share its run,
and a request that stops waiting at the timeout leaves the run going: a check
runs again only once its last run settled, so a stalled dependency holds one
run of each check, whoever calls `/ready`.

Later releases add checks of their own: the configuration digest on every
role, and the signer service on a process that reaches a remote signer.

> ℹ️ **Changed in 0.2.** `/health` used to check Postgres and Redis and answer
> `503` when one was down. It is liveness now and always answers `200` while
> the process serves: move a probe that should take a process out of rotation
> to `/ready`.

## Metrics (`GET /internal/metrics`)

QAuth exposes Prometheus metrics in text exposition format at
`GET /internal/metrics` on the internal listener
(`apps/auth-server/src/app/internal/routes/metrics.ts`), never on the public
port. The endpoint includes default process/runtime metrics plus QAuth counters
and gauges:

| Metric                                             | Type    | Labels                       | Meaning                                                                  |
| -------------------------------------------------- | ------- | ---------------------------- | ------------------------------------------------------------------------ |
| `qauth_login_attempts_total`                       | counter | `result`, `reason`           | Login outcomes (success/failure).                                        |
| `qauth_tokens_issued_total`                        | counter | `type`, `grant_type`         | Tokens issued by type and grant.                                         |
| `qauth_client_secret_checks_shed_total`            | counter | none                         | Client-secret checks refused with 503 because the Argon2 queue was full. |
| `qauth_job_runs_total`                             | counter | `job`, `result`              | Background job runs by outcome.                                          |
| `qauth_events_oldest_unread_age_seconds`           | gauge   | none                         | Seconds the oldest committed event has been held back from readers.      |
| `qauth_events_telemetry_dropped_total`             | counter | `reason`                     | Event log records not exported; present only when the export is on.      |
| `qauth_events_pending`                             | gauge   | `kind`                       | Event deliveries not finished yet, by delivery route.                    |
| `qauth_events_delivery_lag_seconds`                | gauge   | none                         | Seconds the oldest event that waits for a delivery has waited.           |
| `qauth_events_delivery_attempts_total`             | counter | `kind`, `result`             | Event delivery attempts by route and result.                             |
| `qauth_events_delivery_signer_held`                | gauge   | none                         | Deliveries this node holds because the signer is unavailable.            |
| `qauth_events_delivery_signer_held_oldest_seconds` | gauge   | none                         | Seconds since this node first held the oldest of them.                   |
| `qauth_events_retention_deleted_total`             | counter | `category`                   | Events the retention job deleted, by category.                           |
| `qauth_events_oldest_age_seconds`                  | gauge   | `category`                   | Seconds since each category's oldest stored event was written.           |
| `qauth_session_cache_lookups_total`                | counter | `result`                     | Browser session cache reads; `hit` over all is the cache hit rate.       |
| `qauth_session_postgres_reads_total`               | counter | `result`                     | Postgres reads of a browser session.                                     |
| `qauth_session_last_seen_writes_total`             | counter | `result`                     | Conditional writes of a browser session's last-seen time.                |
| `qauth_breached_password_checks_total`             | counter | `source`, `result`, `reason` | Breach-list checks of a password: hits, misses and failed checks.        |

Label values, as emitted today. The plugin
(`apps/auth-server/src/app/plugins/metrics.ts`) does not constrain them, so treat
each list as **open** — a new call site can add a value without a schema change.

- `result` is `success` or `failure`. `reason` is set on failures only, e.g.
  `invalid_credentials`, `locked_out`, `error`. A login refused because the
  account is not verified yet counts as `invalid_credentials`: a label of its
  own would tell whoever reads the metrics whether an address someone just
  registered was free. The `user.login.failure` log line and the
  `user.sign_in_failed` event keep the reason `account_not_verified`.
- `type` is e.g. `access`, `refresh`, or `id_jag` (the ID-JAG assertion minted by
  the token-exchange grant). `grant_type` is e.g. `password`,
  `authorization_code`, `refresh_token`, `client_credentials`, `token-exchange`,
  or `jwt-bearer`.
- `qauth_client_secret_checks_shed_total` counts the client-secret checks at
  `/oauth/token`, `/oauth/introspect` and `/oauth/revoke` that were answered
  `503` with `Retry-After` before any hash, because `PASSWORD_HASH_QUEUE_LIMIT`
  Argon2id checks were already waiting. A steady rise means the host checks
  secrets more slowly than clients present them; see
  [Production considerations](/operate/docker/#production-considerations)
  for `UV_THREADPOOL_SIZE` and the limit.
- `job` is a job's name, e.g. `purge-expired`. `result` is `success`, `failure`
  or `timeout`; see [Background jobs](#background-jobs).
- `reason` on `qauth_events_telemetry_dropped_total` is `queue_full` or
  `export_failed`; see
  [Events as OpenTelemetry logs](#events-as-opentelemetry-logs).
- `kind` is a delivery route, such as `webhook` or `ssf`. `result` on
  `qauth_events_delivery_attempts_total` is `delivered`, `retry` (failed, tried
  again later) or `failed` (failed for good); see
  [Event delivery](#event-delivery).
- `result` on `qauth_session_cache_lookups_total` is `hit`, `miss`, `revoked`
  (a recently ended session's tombstone) or `error` (Redis did not answer, and
  Postgres was read instead). On `qauth_session_postgres_reads_total` it is `ok`
  or `error`; with Postgres not answering, the session counts as absent. On
  `qauth_session_last_seen_writes_total` it is `written`, `skipped` (the stored
  time was recent, usually because another node wrote it first) or `error`.
  `last_seen_at` is written at most once per `SESSION_LAST_SEEN_INTERVAL`
  (60 seconds by default) per session. The session service that counts these
  is in place, but the hosted pages do not use it yet, so they stay at zero for
  now.
- `source` on `qauth_breached_password_checks_total` is the realm's
  `password.breachListSource`, `local` or `k_anonymity` (a realm set to `off`
  checks nothing and counts nothing). `result` is `listed`, `not_listed` or
  `failed`; `reason` is empty but on a failure, where it is `not_configured`
  (the deployment did not set up the realm's source), `list_not_loaded` (the
  local list has not loaded), `lookup_blocked` (the egress client refused the
  range host), `lookup_failed` or `bad_response`. A failed check never blocks a
  sign-in, a password update or a registration; each one is also written as the
  `user.password_breach_check_failed` event.

### Who can read the metrics

The public port does not serve them: `GET /metrics` there answers `404`, on
every host. Each process serves its own metrics on its internal listener, which
runs on every process while `METRICS_ENABLED` is on (the default), on
`INTERNAL_HOST` and `INTERNAL_PORT` (`127.0.0.1`, port `3443`, by default). The
listener is not routed by host, so a scraper reaches each process by its
address and needs no realm host.

- **With the internal TLS files** (`INTERNAL_TLS_CERT_PATH`,
  `INTERNAL_TLS_KEY_PATH`, `INTERNAL_TLS_CA_PATH`), the listener serves mutual
  TLS only. Issue the scraper a client certificate from the internal CA and map
  its SAN to `metrics` in `INTERNAL_PEER_ROLES`, for example
  `{"spiffe://example.org/prometheus":"metrics"}`. A `metrics` peer may read
  the metrics and nothing else, and a peer with another role gets `403` there.
  A process whose service roles are split must have the files, and refuses to
  boot without a peer to admit: map a scraper, or set `METRICS_ENABLED=false`
  where no scraper reads that process.
- **Without them**, a single process (every role, the default) serves plain
  HTTP, and only on a loopback address. A request from a loopback address reads
  the metrics, and any other request is refused. A scraper on the same host, or
  in the same network namespace such as a sidecar, reads
  `http://127.0.0.1:3443/internal/metrics`. With `INTERNAL_HOST` set to any
  other address and no TLS files, the process refuses to boot. Loopback is the
  only proof of who calls here: a proxy on the host or in the pod that forwards
  outside traffic to a loopback address, as some service-mesh sidecars do, makes
  every caller it forwards a local one. Behind such a proxy, give the listener
  the TLS files and a `metrics` peer.

The route has no rate limit. The listener refuses every caller without a role
before any route, and a scraper polls at its own interval.
`METRICS_ENABLED=false` removes the route, and on a process that has no other
use for the internal listener, the listener too.

> ℹ️ **Under Docker Compose these reach the container, but only because they are
> listed.** The `auth-server` service in `docker-compose.yml` declares an
> explicit `environment:` map and no `env_file:`, so that map is an
> **allowlist**: only the variables named in it are forwarded. Every variable on
> this page but the internal listener's is on it — `METRICS_ENABLED`,
> `LOG_PRETTY`, `LOG_REDACT_PATHS`, `REQUEST_ID_HEADER` and the four
> `FAILED_LOGIN_*` settings are forwarded as bare `VAR:` entries, a null value
> that Compose resolves from `.env` (or the shell) and omits entirely when
> unset, so an unset variable still falls through to its schema default.
> `METRICS_ENABLED=false` in `.env` therefore does unregister
> `GET /internal/metrics`.
>
> The internal listener's settings (`INTERNAL_HOST`, `INTERNAL_PORT`, the three
> `INTERNAL_TLS_*` files and `INTERNAL_PEER_ROLES`) are not on it, so under
> Compose the metrics answer on `http://127.0.0.1:3443/internal/metrics` inside
> the container only. A scraper in another container needs an override file that
> adds them to the map and mounts the TLS files.
>
> The allowlist itself is the thing to remember: a variable you add to `.env`
> later is **not** reachable from Compose until you also add it to that map.
> See [Docker](/operate/docker/#environment-variables).

### Event store lag

The event store hands an event to its readers only once every transaction
older than the event has ended, so a reader never skips an event that commits
late. The price is lag: a transaction left open holds back every event written
after it began, until it ends. That holds for any transaction that has written
something, on any database of the same Postgres server.

`qauth_events_oldest_unread_age_seconds` is how long the oldest event held back
this way has waited. It is read from the database at each scrape and is 0 in
normal operation. If the read fails, the gauge shows `NaN` and the auth server
logs a warning. A value that keeps growing points at a long-running
transaction; this query lists the open ones that hold readers back, oldest
first:

```sql
SELECT pid, datname, xact_start, state, query
FROM pg_stat_activity
WHERE backend_xid IS NOT NULL
ORDER BY xact_start;
```

### Event delivery

The delivery role hands every event to every destination of a delivery route,
such as a webhook subscription, at least once and with the event's own id. It
runs in the auth server, beside the other roles. No route is built yet, so
today it only publishes its metrics.

A delivery that fails is tried again after 30 seconds, then after twice as long
each time, at most 6 hours, less up to 20% at random. After the last of its 12
attempts it ends `failed` and stays in the delivery history.
`EVENT_DELIVERY_MAX_ATTEMPTS`, `EVENT_DELIVERY_RETRY_INITIAL_DELAY` and
`EVENT_DELIVERY_RETRY_MAX_DELAY` change the schedule (see
[Configuration](/operate/configuration/)). A destination that is down holds
only its own deliveries: the others go on.

- `qauth_events_pending{kind}` counts the deliveries not finished yet. It grows
  while a destination fails and falls as the retries succeed or run out.
- `qauth_events_delivery_lag_seconds` is how long the oldest event that waits
  for a delivery has waited, the time before the role picked it up included.
  It is 0 while no route has a destination, and about a second in normal
  operation.
- `qauth_events_delivery_attempts_total{kind,result}` counts the attempts. A
  rising `result="failed"` rate means destinations that stay down past the last
  retry.
- `qauth_events_delivery_signer_held` counts the deliveries this node holds
  because the signer is unavailable, and
  `qauth_events_delivery_signer_held_oldest_seconds` is how long it has held
  the oldest. Such a hold spends no attempt, so it never ends in `failed`: the
  role warns at the first hold of a delivery and every 15 minutes while it
  lasts. Alert when the oldest stays above a few minutes.

The pending and lag gauges are read from the database at each scrape; a failed read shows
`NaN` and logs a warning. To see which destinations fail and why:

```sql
SELECT destination_kind, destination_id, status, count(*),
       max(attempt_count) AS attempts, max(last_status_code) AS last_status,
       max(last_error_class) AS last_error
FROM event_deliveries
WHERE status <> 'delivered'
GROUP BY 1, 2, 3
ORDER BY 4 DESC;
```

### Event retention

A realm keeps its user events 90 days and its admin events 365 days by
default. Admin events are never kept fewer than 90 days. Both values are realm
policy, stored on the realm row (`realms.user_event_retention_days`,
`realms.admin_event_retention_days`). `EVENT_RETENTION_USER_DAYS` and
`EVENT_RETENTION_ADMIN_DAYS` only seed a new realm's values: changing them
later leaves existing realms as they are (see
[Configuration](/operate/configuration/)). Until the admin API exists, change
an existing realm's retention with SQL; the row refuses an admin retention
below 90 days.

The `event-retention` job runs every hour, on one node at a time. It deletes a
realm's events once they are older than the realm's retention and every
enabled delivery destination has finished them, as `delivered` or `failed`. A
destination that is down holds its events back only until its retries run out.
A disabled destination holds nothing back. Readers of the event API are not
waited for: one that falls behind retention has to start again. The job
deletes the oldest events first, at most 1000 per transaction.

Admin events go only from the start of a realm's chain, and the newest one
always stays. Before the job deletes admin events, it checks each one against
the one before it. In the same transaction, it stores the last one it deletes
as the realm's chain anchor (`event_chain_anchors`). The chain check then
starts from the anchor. If an old admin event was changed, the job keeps it and
every admin event after it, and logs an error. The chain check reports the
change.

- `qauth_events_retention_deleted_total{category}` counts the events deleted.
- `qauth_events_oldest_age_seconds{category}` is how old each category's
  oldest event is. With the default retention it stays near 90 days for `user`
  and 365 days for `admin`. A value well past the retention means the job does
  not run, or a destination holds events back:
  `qauth_job_runs_total{job="event-retention"}` and the delivery metrics above
  tell which. It is read from the database at each scrape. A failed read shows
  `NaN` and logs a warning.

Only the retention role may delete from `events`.
`eventRetentionGrantStatements()` in `@qauth-labs/infra-db` gives the database
user that runs the job that grant, and the reads it needs. While a deployment
runs every role as one database user, that user owns the tables and holds
every grant.

### Admin event chain

An admin event records a change made by an administrator, a service account or
an operator on the server host: what changed, as a diff with every secret value
`***`, and the approvals the change ran on (see
[Admin events](/reference/events/#admin-events)). Admin events are always on; no
environment key and no realm setting turns them off. The admin API, which will
write most of them, is not built yet.

A realm's admin events form a hash chain: each stores the hash of the one
before it. Check a realm's chain from a host that holds the database
credentials:

```bash
DATABASE_URL=postgresql://qauth:pw@db:5432/qauth \
  pnpm --dir libs/infra/db exec tsx src/scripts/verify-event-chain.ts --realm=<realm name>
```

`pnpm nx run infra-db:events:verify-chain -- --realm=<realm name>` runs the same
check, but Nx reports every failure as exit code `1` and prints lines of its
own, so a monitor uses the command above.

The command only reads, so run it as a database role that may read the
`events` and `event_chain_anchors` tables, such as their owner; a role given
only the event writer's grants cannot. Once the retention job has deleted a
realm's oldest admin events, a full check starts from the realm's chain anchor
and prints it as the point it verified from. A kept head that retention has
since deleted is replaced by the anchor in the same way. `--realm-id=<uuid>` names a realm that no longer exists, and `--json`
prints the report as JSON. Its exit code tells a broken chain from a check
that could not run, so a monitor does not report a database outage as
tampering:

| Exit code | Meaning                                                                                                        |
| --------- | -------------------------------------------------------------------------------------------------------------- |
| `0`       | Every admin event verifies. It prints the chain's head.                                                        |
| `1`       | The chain breaks. It prints the first event that was changed, or that follows one that was removed.            |
| `2`       | A usage error: an unknown flag, a missing realm, or no `DATABASE_URL`. Nothing was read.                       |
| `3`       | The check could not run: the database is unreachable or failing, or no realm and no event has the realm given. |

With exit code `3` the reason is on standard error and nothing is on standard
output. The command waits 10 seconds for a connection.

The chain shows a changed or removed event, but not a chain rewritten from
some event to the end, or the newest events cut, by someone who can write the
database. Keep the head it prints somewhere outside the database, and run the
next check from it with `--from-seq=<seq> --from-hash=<hex>`. That run first
checks that the kept head is still there with the same hash, so it fails when
the chain was cut back to before the kept head or rewritten up to it. Then it
checks the events after the kept head, as a full check does. It does not read
the events before the kept head: one event changed there shows only in a full
check, without `--from-…`, so run both. And as in a full check, events after
the kept head that were rewritten to the end, or cut, leave no break: keep each
new head it prints.

### Example Prometheus scrape config

```yaml
scrape_configs:
  - job_name: qauth-auth-server
    scheme: https
    metrics_path: /internal/metrics
    tls_config:
      ca_file: /etc/prometheus/qauth-internal-ca.crt
      cert_file: /etc/prometheus/prometheus.crt
      key_file: /etc/prometheus/prometheus.key
    static_configs:
      - targets: ['auth-server:3443']
```

The scraper presents `prometheus.crt`, whose SAN `INTERNAL_PEER_ROLES` maps to
`metrics`, and checks the server's certificate against the internal CA. That
certificate must name the host the scraper dials, `auth-server` above, or set
`tls_config.server_name` to a name it does carry. For the scraper to reach
another container, `INTERNAL_HOST` must be an address it can reach, such as
`0.0.0.0`. A scraper beside a single process with no TLS files, in its network
namespace, needs only `targets: ['127.0.0.1:3443']` with the default
`scheme: http`.

## Events as OpenTelemetry Logs

QAuth can send every event it records to your own OpenTelemetry collector, as
one log record per event, over OTLP/HTTP. The
[event reference](/reference/events/) lists the event types. The export is off
by default.

It is telemetry, with no delivery guarantee. A record can be dropped, and a
crash between the moment an event commits and the moment it is sent loses that
record. The event itself is never lost: it stays in the event store either way.
Build anything that must see every event on the event store, not on this
export.

### Turning it on

Set the switch and point the exporter at your collector's OTLP/HTTP port:

```sh
OTEL_EVENTS_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
# Optional:
OTEL_SERVICE_NAME=qauth-auth-server
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=<URL-encoded key>
```

The export reads the standard OpenTelemetry exporter variables, with their
standard meaning. The
[configuration reference](/operate/configuration/#advanced-keys) lists each
one.

- `OTEL_EXPORTER_OTLP_ENDPOINT` is the collector's base URL, and the export
  appends `/v1/logs` to it. `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` is a full URL,
  used as it is. With neither set, the export sends to
  `http://localhost:4318/v1/logs`.
- `OTEL_EXPORTER_OTLP_HEADERS` holds headers such as a collector API key, as
  URL-encoded `name=value` pairs separated by commas. The configuration page
  treats it as a secret.
- `OTEL_EXPORTER_OTLP_TIMEOUT` is how long one export may take, its retries
  included: 10000 ms by default, an hour at most. `OTEL_EXPORTER_OTLP_COMPRESSION`
  is `gzip` or `none`.
- `OTEL_EXPORTER_OTLP_CERTIFICATE` names a PEM file of CA certificates for a
  collector behind TLS with a private CA. `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`
  and `OTEL_EXPORTER_OTLP_CLIENT_KEY` name the client certificate and key for
  mutual TLS.
- Each of these has a `LOGS_` form (`OTEL_EXPORTER_OTLP_LOGS_HEADERS` and so on)
  that wins over the general one. The two header lists are merged.
- `OTEL_SERVICE_NAME` sets the records' `service.name` (`qauth-auth-server` by
  default). `OTEL_RESOURCE_ATTRIBUTES` is not read.

When the export is on, the server checks these values at boot: a malformed
URL, header list, timeout or compression refuses to start, with the variable's
name in the error, and so does a TLS file the process cannot read, or a client
certificate set without its key or a key without its certificate. The
exporter would otherwise drop an unreadable CA file without a word and trust
the public CAs instead. The error never repeats a header value. When the
export is off, the server leaves them alone. They are process-wide, and another
OpenTelemetry component of yours may read them.

The records are JSON-encoded OTLP (`http/json`). `OTEL_EXPORTER_OTLP_PROTOCOL`
is not read, and gRPC is not supported. The OpenTelemetry Collector's `otlp`
receiver accepts JSON on its HTTP port:

```yaml
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
exporters:
  debug: {}
service:
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [debug]
```

The collector is your own, and it often sits on a private network. So the export
does not go through QAuth's SSRF-safe egress client, which guards the
destinations that clients and users register; ADR-019 Decision 8 records this
as its one exception. Its destination comes only from these variables, never
from a realm admin, a client or a user. Point the endpoint only at a collector
you run.

Under Docker Compose every variable above is forwarded to the `auth-server`
container. A certificate or key variable names a path inside the container, so
mount the file too.

### What a record holds

| Part of the record | Value                                                                                              |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| Body               | The event envelope as a JSON string, the same document the event store holds.                      |
| Event name         | The event type, such as `urn:qauth:event:user.signed_in:v1-rc.0`.                                  |
| Timestamp          | The event's `time`.                                                                                |
| Severity           | The type's severity: `info` is INFO (9), `warning` is WARN (13), `critical` is ERROR2 (18).        |
| Severity text      | The type's severity as written in the registry: `info`, `warning` or `critical`.                   |
| Trace and span id  | Those of the span active when the event committed, when the process has one.                       |
| Resource           | `service.name` from `OTEL_SERVICE_NAME`, and the OpenTelemetry SDK's `telemetry.sdk.*` attributes. |
| Scope              | `qauth.events`.                                                                                    |

Every record carries these attributes:

| Attribute              | Value                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| `qauth.event.id`       | The event id, a UUIDv7. It is the same id on every route an event takes.                          |
| `qauth.event.type`     | The event type.                                                                                   |
| `qauth.event.category` | `user` or `admin`.                                                                                |
| `qauth.realm`          | The id of the realm the event happened in.                                                        |
| `qauth.subject.id`     | The subject's id, when the event has a subject.                                                   |
| `qauth.client.id`      | The `client_id` of the client the request came through, when there was one.                       |
| `qauth.request.id`     | The request id echoed on `REQUEST_ID_HEADER`, when no span is active and the event has a request. |

QAuth starts no traces itself. A record carries a trace id only when the
process runs an OpenTelemetry tracing setup of yours, such as the Node.js
auto-instrumentation loaded with `--require`, that made a span active for the
request. Otherwise `qauth.request.id` links the record to the request's log
lines (`reqId`) and to the `trace_id` of an error response.

A record holds what the event holds and nothing more. The event store refuses
an event that carries a password, a token, a key or a value shaped like one,
and the export checks every event against the same rules before it queues the
record. The export adds no masking of its own. On events that a person's own
request caused, the body includes the request's IP address and `User-Agent`,
as the event store does. An admin event's `diff` carries the before and after
values an admin changed, a contact address included, and a field an event type
declares as personal data goes out as it is stored. Your collector and the
storage behind it then hold that personal data, and how long they keep it is
yours to set: the event store's retention does not reach the exported copy.

### Queue, drops and limits

Export never fails a request, and a request never waits for the collector.
When an event commits, the request builds its record and puts it in a queue
in memory. The server sends the queue's records later, on its own:

- The queue holds up to 2048 records. When it is full, each new record pushes
  out the oldest one, so a collector that comes back receives the latest
  events.
- Records go out in batches of up to 512, one batch at a time. A batch leaves
  once 512 records wait, or a second after the first of them arrived. Records
  that arrive while a batch is out wait for it to end.
- A batch the collector refuses, or that cannot be sent before
  `OTEL_EXPORTER_OTLP_TIMEOUT`, is dropped after the exporter's own retries.
  It is not sent again. If an export has not reported 5 seconds after that
  timeout, its batch is given up and the next one goes out.
- When the server stops, it spends up to 5 seconds sending what is queued. It
  logs how many records were left unsent, and drops them.

`qauth_events_telemetry_dropped_total` counts the records the queue gives up.
`reason="queue_full"` counts records pushed out of a full queue, and
`reason="export_failed"` counts records in batches that failed or were given
up. The server logs two other losses instead of counting them: the records
left at shutdown (a warning), and an event that fails the event contract,
which the event store's own check already keeps out (an error). The counter
is in the metrics only while the export is on. A rule like this one tells you
when records keep being dropped for 15 minutes, as they are when the collector
falls behind or cannot be reached; a single burst, such as a collector
restart, does not fire it:

```yaml
- alert: QAuthEventExportDropping
  expr: increase(qauth_events_telemetry_dropped_total[5m]) > 0
  for: 15m
  labels:
    severity: warning
  annotations:
    summary: 'QAuth is dropping event log records'
    description: 'The OpenTelemetry collector refuses or does not answer QAuth exports.'
```

## Background Jobs

The auth server runs periodic jobs in its own process
(`apps/auth-server/src/app/jobs/`). Every node of a deployment runs the same
jobs, and each job runs on one node at a time. The exception is a run that keeps
going past its time limit (below): it can overlap the next node's run, which is
why every job must be safe to repeat.

| Job                 | Interval | Time limit | What it does                                                                                                                                                                                                  |
| ------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `purge-expired`     | 1 hour   | 5 minutes  | Deletes expired authorization codes, email verification tokens and OID4VP requests, and each refresh-token family whose every token has expired.                                                              |
| `ssf-subject-sweep` | 1 hour   | 5 minutes  | Deletes each SSF user subject whose receiver is no longer related to the user, once every event about the user has reached the stream (see [SSF transmitter](/operate/ssf-transmitter/#register-a-receiver)). |

How a run is placed:

- Runs are aligned to the interval on the wall clock: `purge-expired` runs once
  per clock hour. Each node wakes at a random point in the first 10% of the
  interval, at most 5 minutes in, so the nodes do not query the database
  together.
- The first node to wake takes a Postgres advisory lock named after the job, on
  a connection of its own, and runs the job. It keeps the lock until twice that
  wake window has passed (10 minutes past the hour for `purge-expired`), so the
  nodes that wake after it skip that interval. The second window allows for
  clock skew between nodes: keep their clocks synchronised (NTP). A node that
  only gets the lock after that time skips the interval too.
- The lock's connection comes from the server's pool (`DB_POOL_MAX`, 20 by
  default). Each job holds one from the moment it takes the lock until it
  releases it, and the job's own queries use others. A node that finds the lock
  held gives its connection back at once. The server refuses to start with
  `DB_POOL_MAX` below 2, where the lock would leave no connection for requests.
- The lock is a session-level lock, so a connection pooler in transaction mode
  between QAuth and Postgres (for example PgBouncer with
  `pool_mode = transaction`) cannot hold it.

What happens when a run goes wrong:

- A run that fails or reaches its time limit is logged and counted, and runs
  again at the next interval. There is no retry queue: every job is safe to
  repeat. A run is told to stop at its limit; a database statement it has
  already sent still runs to its end in Postgres.
- When a node dies or loses its database connection during a run, Postgres
  drops the lock, and another node takes the job at its next interval. Postgres
  notices at once when the node's process exits. A host that vanishes without
  closing its connection keeps the lock until the database server's TCP
  keepalive (`tcp_keepalives_idle` and the settings next to it) gives up on the
  connection.
- On `SIGTERM` or `SIGINT` the server tells running jobs to stop and waits up to
  5 seconds for them. Then it closes the database pool, which waits for a
  statement a job has already sent, so shutdown can take longer than that.

Each log line carries the job's name as `job`: `job run started`,
`job run finished` with `durationMs`, `job run failed` with `err`, and
`job run exceeded its time limit and was stopped`. A node that skips a run
because another node holds the lock logs `job run skipped: another node holds
its lock` at `debug`. `qauth_job_runs_total` counts the runs; a skipped run is
not counted, and a lock that cannot be taken, for example because the database
is unreachable, counts as a `failure`.

## Alerting (Optional)

QAuth does not ship an alerting stack. The following Prometheus Alertmanager
rules are recommended starting points; tune thresholds to your traffic. They
assume the `auth-server` is also instrumented for HTTP status codes (e.g. via a
proxy exporter or `http_requests_total`-style metric); the auth-failure rule uses
the built-in `qauth_login_attempts_total` counter.

```yaml
groups:
  - name: qauth-auth-server
    rules:
      # Spike in authentication failures — possible credential-stuffing/brute force.
      - alert: QAuthHighLoginFailureRate
        expr: |
          sum(rate(qauth_login_attempts_total{result="failure"}[5m]))
            /
          clamp_min(sum(rate(qauth_login_attempts_total[5m])), 1) > 0.5
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: 'High login-failure ratio on QAuth'
          description: 'Over 50% of login attempts have failed for 10 minutes.'

      # Elevated server errors (requires an HTTP status metric at the proxy/app).
      - alert: QAuthHigh5xxRate
        expr: |
          sum(rate(http_requests_total{job="qauth-auth-server",status=~"5.."}[5m]))
            /
          clamp_min(sum(rate(http_requests_total{job="qauth-auth-server"}[5m])), 1) > 0.05
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: 'High 5xx error rate on QAuth'
          description: 'More than 5% of requests are returning 5xx for 5 minutes.'

      # The scrape target is down.
      - alert: QAuthInstanceDown
        expr: up{job="qauth-auth-server"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: 'QAuth auth-server is down'
          description: 'Prometheus cannot scrape {{ $labels.instance }}.'
```

### Wiring Alertmanager

1. Add the rules above to a file referenced by `rule_files:` in `prometheus.yml`.
2. Point Prometheus at Alertmanager under `alerting.alertmanagers:`.
3. Configure Alertmanager receivers (email, Slack, PagerDuty, ...) and routing.
4. Reload Prometheus (`SIGHUP` or `POST /-/reload`) and verify under
   **Status → Rules** and **Alerts**.

## See also

- [Docker](/operate/docker/) — running the stack this endpoint is served from.
- [Environment-Aware Authorization](/operate/environment-authorization/) — how `environment` affects rate limits referenced above.

---

# Browser Security Model

URL: https://docs.qauth.dev/operate/browser-security/

QAuth's interactive sign-in and consent screens live under `/ui/*` and are
protected by a session cookie, a CSRF token, and a strict set of response
headers. This document describes the contract for anyone integrating with or
operating those endpoints. The machine-to-machine OAuth/OIDC endpoints under
`/oauth/*` and `/auth/*` are JSON/bearer APIs and are **not** affected by the
cookie/CSRF mechanics below.

## Session cookie

| Attribute  | Value                                           |
| ---------- | ----------------------------------------------- |
| Name       | `__Host-qauth_session`                          |
| `HttpOnly` | always                                          |
| `SameSite` | `Lax`                                           |
| `Secure`   | on by default; gated by `SESSION_COOKIE_SECURE` |
| `Path`     | `/`                                             |
| `Domain`   | none (forbidden by the `__Host-` prefix)        |
| `Max-Age`  | the time left until the session's absolute end  |

- The cookie carries only signed session ids, `<kid>.<payload>.<mac>`: the
  `kid` of the realm cookie key that signed it, the session ids as base64url
  JSON, and an HMAC-SHA256 over the cookie's name, the realm id, the `kid` and
  the payload. The key is the realm's `cookie_hmac` key from the key store
  (#493), so a cookie verifies only in its own realm. The session itself lives
  server-side, in Postgres with Redis in front, so logout and revocation end it
  there. A cookie that does not verify, or names no live session, is cleared.
- The login-CSRF and wallet-flow cookies are signed the same way, with the same
  realm key.
- The `__Host-` prefix is browser-enforced: the cookie is rejected unless it is
  `Secure`, `Path=/`, and has no `Domain`. This isolates it from sibling
  subdomains.
- `Secure` is **on by default**. Set `SESSION_COOKIE_SECURE=false` **only** for
  local plain-HTTP development. In production it must stay on (the `__Host-`
  prefix requires it).

## CSRF protection

Four cookie-authenticated, state-changing browser endpoints ship today, and
**every one of them is CSRF-protected**. They do not all use the same mechanism,
so check the column before integrating:

| Endpoint                | Token travels as                  | Mechanism                                                                   |
| ----------------------- | --------------------------------- | --------------------------------------------------------------------------- |
| `POST /ui/consent`      | `csrf_token` form field           | Session-bound double-submit; token stored in the server-side session.       |
| `POST /ui/login`        | `csrf_token` form field           | Signed `__Host-qauth_login_csrf` double-submit cookie (pre-authentication). |
| `POST /ui/wallet-link`  | `csrf_token` form field           | Session cookie + the same signed login-CSRF cookie.                         |
| `DELETE /consents/{id}` | `X-CSRF-Token` **request header** | Per-session `apiCsrfToken`, echoed from `GET /consents/`.                   |

`POST /auth/link/wallet` is a JSON API on the same session cookie and also
requires the `X-CSRF-Token` header; it is registered only when
`WALLET_FEDERATION_ENABLED` is on.

### `POST /ui/consent` — session-bound double-submit

1. `GET /ui/consent` renders a hidden `<input name="csrf_token">`. The same
   value is stored in the server-side session.
2. `POST /ui/consent` must submit that `csrf_token`. The server compares the
   submitted value against the session copy with a timing-safe comparison
   (`csrfTokensEqual`). A mismatch → `400 invalid_csrf_token` and a
   `request.csrf_rejected` event with `form: consent`.
3. The token is **burned** on a successful POST and re-minted on the next
   `GET /ui/consent`, so a captured form cannot be replayed. The token is **not**
   rotated on every GET, so opening the consent page in multiple tabs does not
   invalidate earlier tabs.

Clients embedding the consent flow must round-trip the `csrf_token` field
verbatim from the rendered form; do not generate it client-side.

### `POST /ui/login` — pre-authentication double-submit cookie

Login runs **before** any authenticated session exists, so it cannot use the
session-bound token above. It uses a signed double-submit cookie instead:

1. `GET /ui/login` mints a token, sets it as `__Host-qauth_login_csrf`
   (`HttpOnly`, `SameSite=Lax`, `Path=/`, signed with an HMAC), and renders the
   same value as a hidden `<input name="csrf_token">`.
2. `POST /ui/login` **requires** `csrf_token` in the body — it is a required
   field of the route schema, not an optional hardening extra. A missing or
   mismatched value is rejected and audited as `ui.login.csrf_failure`.

A client that posts credentials without `csrf_token` will be refused. Round-trip
the hidden field verbatim from the rendered form.

### Why the remaining endpoints do not carry a CSRF token

`/auth/login`, `/auth/logout`, `/auth/register`, `/auth/resend-verification`,
and all `/oauth/*` endpoints authenticate with a **bearer token or client
credentials**, not the browser session cookie. They carry no ambient-authority
cookie, so CSRF does not apply.

## Response security headers (issue #113)

`@fastify/helmet` applies the following to every response:

- **Content-Security-Policy** (strict, nonce-based):
  `default-src 'self'`, `script-src 'self'`, `style-src 'self' 'nonce-…'`,
  `img-src 'self' data:`, `font-src 'self' data:`, `connect-src 'self'`,
  `form-action 'self'`, `object-src 'none'`, `frame-ancestors 'none'`,
  `base-uri 'self'`. The server-rendered pages link one stylesheet, the design
  system's, and load its fonts: same-origin files under `/assets/ui/`, which
  `style-src 'self'` and `font-src 'self'` allow without a nonce. A fresh
  per-request nonce authorises the inline `<style>` a page adds for rules of its
  own, such as the login and consent pages; there is **no** `'unsafe-inline'` for
  scripts, so an injected `<script>` is refused by the browser. A page whose
  form's answer redirects the browser to a client adds exactly that client to
  `form-action`: the origin of its `redirect_uri`, or a native app's scheme.
  Chromium and WebKit apply `form-action` to the redirects after a form post,
  so the sign-in, consent, passkey, TOTP and recovery-code pages allow the
  client the authorization request named, once the request is checked.
- **Strict-Transport-Security**: `max-age=31536000; includeSubDomains; preload`
  (one year, preload-eligible). Gated by `SECURITY_HSTS_ENABLED` /
  `SECURITY_HSTS_MAX_AGE`; keep enabled in production behind TLS.
- **X-Frame-Options**: `DENY` — clickjacking protection.
- **X-Content-Type-Options**: `nosniff`.
- **Referrer-Policy**: `no-referrer`.

### Swagger UI exception

The strict CSP would break Swagger UI (it bundles inline scripts/styles), so the
`/docs` prefix is served a relaxed CSP that permits `'unsafe-inline'` for its
own scripts and styles.

There is a **second** relaxation, and operators should know about it: the
consent screen serves a development CSP (`style-src 'self' 'unsafe-inline'`)
whenever the resolved environment policy has `t3SecurityEnforced` false — i.e.
for a client on the `development` profile. Scripts stay `'self'` in that policy;
only inline styles are permitted. Every other route, and every client on
`staging` or `production`, keeps the strict policy.

## Related configuration

| Env var                 | Default    | Purpose                                                                                             |
| ----------------------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `SESSION_COOKIE_SECURE` | `true`     | `Secure` flag on the session cookie.                                                                |
| `SESSION_COOKIE_TTL`    | `86400`    | Session lifetime (seconds), absolute from sign-in. Activity on the hosted pages does not extend it. |
| `SECURITY_HSTS_ENABLED` | `true`     | Emit the HSTS header.                                                                               |
| `SECURITY_HSTS_MAX_AGE` | `31536000` | HSTS `max-age` (seconds).                                                                           |

## See also

- [Environment-Aware Authorization](/operate/environment-authorization/) — the `t3SecurityEnforced` knob. **It does not gate this hardening bundle.** Helmet is registered globally and unconditionally, the CSRF checks are unconditional, and the session cookie's `Secure` flag comes from `SESSION_COOKIE_SECURE` — none of them consult the environment profile. Today `t3SecurityEnforced` relaxes exactly one thing: the consent-screen style CSP described above.
- [Keys](/operate/keys/) — the signing-key side of QAuth's security posture.

---

# Environment-Aware Authorization

URL: https://docs.qauth.dev/operate/environment-authorization/

QAuth treats **environment** — `development`, `staging`, or `production` — as a
first-class **policy-profile dimension**. One attribute flips a coordinated bundle
of security and operational defaults, so an operator hardens a deployment by
setting a single value instead of getting a dozen independent switches right.

This is the operator/how-to guide. For the design rationale, the fail-safe
reasoning, and the prior-art comparison, see
[ADR-008](/reference/records/adr/008-environment-aware-authorization/). The resolver itself lives
in `apps/auth-server/src/app/helpers/environment-policy.ts`.

## The two knobs

Environment is set on two columns, both defaulting to `production`:

| Column                          | Meaning                                                               |
| ------------------------------- | --------------------------------------------------------------------- |
| `oauth_clients.environment`     | The client's **declared** environment.                                |
| `realms.max_environment_laxity` | A realm-level **ceiling** on how lax any client in that realm may be. |

The **effective** environment is the **stricter** of the two
(`production` > `staging` > `development`). A realm pinned to `production` forces
every client in it to the production profile regardless of the client's own field.

```
effective = stricter(client.environment, realm.max_environment_laxity)
```

## Fail-safe defaults

- **Unset / unknown client `environment` → `production`.**
- **Unset / unknown realm `max_environment_laxity` → `production`.**

A fresh realm caps everything at production until an operator deliberately widens
it, and any malformed value resolves to the strictest profile. **Misconfiguration
fails closed** — the relaxed posture is always opt-in and bounded.

## Relaxation is operator-set, never self-asserted

The relaxation direction is set **only** by an operator — seed/manifest, admin
API, or realm config. It is **not** accepted from `POST /oauth/register` (dynamic
client registration) or a CIMD metadata document. A client cannot declare itself
`development` to escape production gates, exactly as it cannot self-grant
`max_agent_mode` (ADR-007 §2).

## The profiles

Security-relevant relaxations apply to **`development` only**. **`staging` keeps
production-grade security** and relaxes only operational conveniences (rate limits,
token lifespan), so promoting dev → staging surfaces the real security posture
before production.

| Knob (`EnvironmentPolicy` field)            | development | staging | production |
| ------------------------------------------- | ----------- | ------- | ---------- |
| `staticApiKeysAllowed`                      | ✅ allowed  | ❌ off  | ❌ off     |
| `localhostRedirectAllowed`                  | ✅          | ❌      | ❌         |
| `pkceRequired`                              | recommended | ✅      | ✅         |
| `accessTokenLifespanTier`                   | long        | short   | short      |
| `refreshRotationRequired`                   | ❌          | ✅      | ✅         |
| `rateLimitTier`                             | lenient     | lenient | strict     |
| `openDynamicRegistration`                   | open        | gated   | gated      |
| `agentStepUpEnforced`                       | ❌          | ✅      | ✅         |
| `t3SecurityEnforced` (style CSP on consent) | ❌          | ✅      | ✅         |

Notes:

- `t3SecurityEnforced` is **narrower than its name suggests**, and the row above
  is the whole of it. The flag has exactly one consumer: when it is false, the
  consent screen serves a relaxed style CSP (`style-src 'self' 'unsafe-inline'`).
  The rest of the T3 browser hardening is **unconditional** and never reads the
  environment profile — `@fastify/helmet` is registered globally
  (`apps/auth-server/src/app/plugins/security-headers.ts`), the `/ui/login` and
  `/ui/consent` CSRF checks always run, and the session cookie's `Secure`
  attribute is driven solely by `SESSION_COOKIE_SECURE`
  (`apps/auth-server/src/app/helpers/session-cookie.ts`). Marking a client
  `production` does **not** turn any of those on, and marking it `development`
  does not turn them off. See [Browser Security](/operate/browser-security/).
- `pkceRequired` here governs whether the **environment profile** hard-requires
  PKCE. QAuth's project-wide floor still defaults `oauth_clients.require_pkce=true`
  regardless, so PKCE is on unless a client is explicitly a `development` client
  that opts out.
- `staging` and `production` are **https-only** for redirect URIs. The RFC 8252
  `http://` loopback carve-out for native / CLI clients (including MCP clients) is
  handled by redirect validation and is permitted in any PKCE-enforcing
  environment — it is not the same flag as `localhostRedirectAllowed`. Loopback
  redirects may use any port at request time (RFC 8252 §7.3); see
  [Redirect URI matching](/integrate/oauth-flow/#redirect-uri-matching). An
  `http://` redirect to any other host is refused in every environment,
  `development` included.
- Hard security floors always hold and are **not** environment-tunable: client
  secrets are always hashed (Argon2id), and audience (`aud`) binding always holds.

## Static developer API keys

Static, long-lived API keys are the deliberate **developer-experience half** of
this feature — and they are environment-gated from day one:

- **`development`**: a client may issue and authenticate with static API keys.
- **`staging` / `production`**: the API-key path is **off**; use OAuth
  `client_credentials` instead.

Keys have the layout `qauth_<keyId>_<secret>` and are presented as a bearer
credential:

```http
Authorization: Bearer qauth_<keyId>_<secret>
```

Only `keyHash` / `prefix` (`qauth_<keyId>`) / `last4` are ever persisted; the full
key is surfaced exactly once at creation. Manage them from the developer portal
(**API keys** section) or the `/api/clients` API. The gate is enforced centrally
via `resolveEnvironmentPolicy(client, realm).staticApiKeysAllowed`, so a key that
exists on a client later moved to `production` simply stops authenticating.

## Concrete values behind the tiers

The profile table is deliberately coarse — it carries legible **tier labels**, not
magic numbers. The concrete values come from configuration so an operator tunes
one place:

- **Access-token lifespan** — `short` maps to the realm's
  `tokens.accessTokenLifespanSeconds` (default `900` seconds); `long`, the
  development convenience, to its `tokens.developmentAccessTokenLifespanSeconds`
  (default `28800`). Both are realm policies, which `ACCESS_TOKEN_LIFESPAN` and
  `DEV_ACCESS_TOKEN_LIFESPAN` only seed for a new realm.
- **Rate limits** — `strict` vs `lenient` select between configured per-window
  caps (`RATE_LIMIT_MAX` / `RATE_LIMIT_WINDOW` and the per-endpoint limits); only
  the cap moves with environment, the window is unchanged.

## Recommended operator setup

- **Production deployment**: leave both columns at their `production` default, or
  explicitly pin `realms.max_environment_laxity = production` to lock the entire
  realm. Nothing else to configure on this dimension — but note the T3 browser
  hardening (security headers, CSRF, the cookie `Secure` flag) is **not** part of
  it: those are unconditional and configured separately, chiefly via
  `SESSION_COOKIE_SECURE` and the `SECURITY_HSTS_*` variables.
- **Local development**: set the developer's realm `max_environment_laxity` to
  `development` (or `staging`) and mark specific clients `environment = development`
  to opt into static API keys, localhost redirects, and long-lived tokens — without
  ever weakening the production realm.
- **Staging / load testing**: use `staging` to keep full production security while
  relaxing only rate limits and token lifespans.

## Related

- [ADR-008: Environment-Aware Authorization Posture](/reference/records/adr/008-environment-aware-authorization/) — rationale, fail-safe design, prior art.
- [ADR-007: MCP-First Positioning](/reference/records/adr/007-mcp-first-positioning/) — the operator-set `max_agent_mode` precedent this reuses.
- [Agent Authorization](/integrate/agent-authorization/) — agent step-up, which this posture enforces in `staging`/`production`.
- [Browser Security](/operate/browser-security/) — the T3 hardening bundle. **This profile does not gate it**: Helmet, the CSRF checks, and the session cookie's `Secure` flag are all unconditional. `t3SecurityEnforced` relaxes exactly one thing — the consent-screen style CSP.

---

# PQC Verifier Guide

URL: https://docs.qauth.dev/operate/pqc-verifier-guide/

This guide explains how token **verifiers** behave with QAuth's post-quantum
hybrid-signing feature (ADR-005): what changes, what doesn't, and what — if
anything — you need to do.

> **TL;DR for existing integrators: nothing is required.** A classical,
> Ed25519-only verifier keeps working **unchanged**. Hybrid signing is designed
> so the bearer token stays an ordinary `EdDSA` JWS that stock JOSE libraries
> validate byte-for-byte. Read on only if you want to _additionally_ validate
> the post-quantum signature.

## Current status (read this first)

Hybrid (Ed25519 + ML-DSA-65) signing has **shipped** and is wired into the live
token routes: `POST /oauth/token` and `POST /auth/login` issue hybrid-signed
access tokens whenever it's on, and `POST /oauth/introspect` returns the
detached PQC component for a hybrid token (see
[OAuth 2.1 Flow → Introspection](/integrate/oauth-flow/#token-introspection-rfc-7662)).
It is a **capability that is OFF by default** (`HYBRID_SIGNING_ENABLED=false`),
so a fresh deployment issues classical Ed25519 access/ID tokens and serves an
EdDSA-only JWKS until an operator opts in. ID tokens are always classical
Ed25519 (or RS256, when configured) — only access tokens can carry the PQC
signature. This guide describes the behavior you will observe **once an
operator enables hybrid signing**.

What is _not_ shipped yet: a first-party SDK that performs the PQC signature
check for you. [`@qauth-labs/resource-guard`](https://github.com/qauth-labs/qauth/blob/main/libs/sdk/resource-guard/README.md),
QAuth's own resource-server SDK, verifies the classical Ed25519 signature only.
The "If you want to validate the post-quantum signature" checklist below is
something you implement yourself today.

> The linked [Security Gate Review](/reference/records/security/005-pqc-hybrid-signing-review/)
> predates live issuance (#275); its own dated note explains the gap. Its
> findings and the default-off posture are otherwise still current.

## The design in one paragraph

QAuth uses a **detached parallel** hybrid signature, deliberately _not_ the
strict concatenated composite of the JOSE/LAMPS drafts. A hybrid token **is** an
ordinary Ed25519 compact JWS: the JWS `alg` stays `EdDSA`, and a stock verifier
validates it with no changes. The ML-DSA-65 (FIPS 204, NIST Level 3)
post-quantum signature covers the **identical** JWS signing-input and is carried
**alongside** the token — never inside the compact string — and delivered
out-of-band via introspection. Two non-critical protected-header members
(`pqc_alg`, `pqc_kid`) advertise the PQC signature to verifiers that care; a
classical verifier ignores them. This is why existing verifiers need no changes.

## 1. JWKS: mixed key types (`OKP` + `AKP`)

When hybrid signing is configured, `GET /.well-known/jwks.json` publishes the
ML-DSA public key **alongside** the Ed25519 key:

```jsonc
{
  "keys": [
    {
      // Ed25519 signing key — RFC 8037. Verifies the bearer token.
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "…",
      "use": "sig",
      "alg": "EdDSA",
      "kid": "ed-2026",
    },
    {
      // ML-DSA-65 public key — the post-quantum half. Public material only.
      "kty": "AKP",
      "pub": "…", // base64url raw ML-DSA-65 public key (1952 bytes)
      "use": "sig",
      "alg": "ML-DSA-65",
      "kid": "mldsa-2026",
    },
  ],
}
```

**Classical-only verifiers: no action required.** RFC 7517 requires a verifier
to **ignore** JWK entries whose `kty` it does not understand. Every mainstream
JOSE library already does this — it selects the `OKP`/`EdDSA` key by `alg`/`kid`
and skips the `AKP` entry. The `AKP` entry never affects Ed25519 verification.

The `AKP` entry carries **only** the public key (`pub`); it never contains
private material (no `priv`, no `d`).

> The auth server publishes the `AKP` entry only while `HYBRID_SIGNING_ENABLED`
> is on: it hands the ML-DSA seed (`JWT_MLDSA_PRIVATE_KEY`) to the JWT plugin
> only then. The plugin itself publishes the entry whenever it receives a seed
> (#246), so a host built on it directly could publish the key without issuing
> hybrid tokens.

## 2. Token delivery: reference-token / introspection is the default

The post-quantum signature is large. Measured on a representative token
(`libs/server/jwt/src/lib/token-size.bench.test.ts`, #247):

| Artifact                                 | Bytes    | Fits a 4 KB cookie? | Fits a 2 KB URL? |
| ---------------------------------------- | -------- | ------------------- | ---------------- |
| Access **bearer** JWS (`.token`)         | **736**  | ✅                  | ✅               |
| ID-token bearer JWS                      | **592**  | ✅                  | ✅               |
| Detached **ML-DSA-65** signature         | **4412** | ❌                  | ❌               |
| Compound (bearer + signature), if inline | **5148** | ❌                  | ❌               |

Because the signature is detached, the **bearer token stays ~736 bytes** in
every channel — it never balloons. The 4412-byte ML-DSA signature is delivered
out-of-band. Accordingly:

- **`PQC_TOKEN_DELIVERY=reference` (the default when hybrid is on):** the bearer
  token is validated normally; the PQC component is retrieved and checked via
  **RFC 7662 introspection** (a POST body, with no header/cookie size ceiling).
  This is the recommended posture, and is how QAuth's own `/oauth/introspect`
  serves it (`apps/auth-server/src/app/helpers/hybrid-token.ts`).
- **`PQC_TOKEN_DELIVERY=self-contained`:** only viable where you control the
  transport and it tolerates a ~4.4 KB payload — i.e. **large-buffer request
  headers, never cookies or URLs**. It requires an explicit
  `PQC_SELF_CONTAINED_ACK=true`, so it can never be selected by accident.

## 3. Draft revision implemented, and churn risk

Post-quantum JOSE is still standardizing. QAuth pins the identifiers it emits so
a draft revision cannot silently change the wire shape:

- **ML-DSA public key in JWKS** (`kty: "AKP"`, `pub` member) and the
  **`ML-DSA-65` algorithm spelling** follow **[RFC 9964](https://www.rfc-editor.org/rfc/rfc9964.html)**
  ("ML-DSA for JOSE and COSE", Standards Track, May 2026 — the published
  successor to `draft-ietf-cose-dilithium`, final revision `-11`). `ML-DSA-65`
  is IANA-registered in the JOSE "JSON Web Signature and Encryption Algorithms"
  registry, and is a _fully-specified_ identifier per
  **[RFC 9864](https://www.rfc-editor.org/rfc/rfc9864.html)** — `alg` alone
  determines the operation, with no companion parameter member.
- The `pqc_alg` / `pqc_kid` protected-header members are **private, unregistered
  JOSE header parameters**, kept **non-critical** so classical verifiers ignore
  them.

> ✅ **Pin corrected (#274, closes review checklist item 1).** The in-code
> constant was previously named `PQC_JOSE_COMPOSITE_DRAFT` and pointed at
> `draft-prabel-jose-pq-composite-sigs-02` — a draft describing the
> _concatenated composite_ construction QAuth deliberately does **not**
> implement. The emitted wire shape was always correct (there was no interop
> break); only the citation was wrong. The constant is now
> `PQC_JOSE_MLDSA_SPEC = 'RFC 9964'`, with `PQC_JOSE_ALG_POLICY_SPEC = 'RFC 9864'`
> for alg-identifier policy. See the
> [security review](/reference/records/security/005-pqc-hybrid-signing-review/).

**The AKP key members are stable**: RFC 9964 is a published Standards Track
RFC, so `kty`/`alg`/`pub` will not change under you. What remains provisional is
the QAuth-private `pqc_alg` / `pqc_kid` header pair, which is unregistered and
may change — re-check this guide periodically.

If QAuth ever adds a true composite path, that is a _separate_ specification —
[`draft-ietf-jose-pq-composite-sigs`](https://datatracker.ietf.org/doc/draft-ietf-jose-pq-composite-sigs/)
("PQ/T Hybrid Composite Signatures for JOSE and COSE", the WG-adopted successor
to the individual `-prabel-` draft) — and would be pinned under its own constant.

## 4. Migration checklist

### If you are a classical, Ed25519-only verifier

**Nothing is required.** Concretely, confirm only that:

- [ ] You fetch keys from `GET /.well-known/jwks.json` and **select by `kid` /
      `alg`** (as every JOSE library does), rather than assuming a single-entry
      JWKS. You will simply skip the `AKP` entry.
- [ ] You pin the accepted algorithm to `EdDSA` (you should already — it blocks
      `alg` confusion). The bearer token's `alg` stays `EdDSA` under hybrid.

That's it. Your integration is unaffected by the rollout.

### If you want to validate the post-quantum signature

Opt-in, for verifiers that want forward-secure assurance. There is no
first-party SDK support for this yet (`resource-guard` verifies Ed25519 only), so
this is a checklist for building it yourself:

- [ ] Read the `AKP` / `ML-DSA-65` public key from JWKS, selecting it by the
      token's signed `pqc_kid` header (not any unsigned transport field).
- [ ] Obtain the detached ML-DSA-65 signature via **introspection** (the default
      delivery channel, and the only one QAuth's own server implements today).
- [ ] Recompute the JWS signing-input — `base64url(header) + "." +
  base64url(payload)` — and verify the ML-DSA-65 signature over those exact
      bytes with the `AKP` public key. (This is the same preimage the Ed25519
      signature covers, so tampering breaks both.)
- [ ] Decide your **downgrade policy**. Verifying the Ed25519 signature is the
      classical floor; require the PQC component wherever you expect
      post-quantum assurance, and treat its absence as a rejection rather than a
      silent downgrade — a token whose signed header advertises `pqc_alg` but
      whose detached signature you cannot retrieve should be treated as
      unverifiable, not as a degraded-but-valid token.

## References

- [ADR-005: Post-Quantum Hybrid Signing](/reference/records/adr/005-pqc-hybrid-signing/) — the
  roadmap and the #243–248 implementation amendments.
- [Security Gate Review](/reference/records/security/005-pqc-hybrid-signing-review/) — the
  reviewed behavior and the pre-default-on checklist.
- [OAuth 2.1 Flow → Introspection](/integrate/oauth-flow/#token-introspection-rfc-7662) — the introspection endpoint
  used as the PQC delivery channel.
- [`@qauth-labs/resource-guard`](https://github.com/qauth-labs/qauth/blob/main/libs/sdk/resource-guard/README.md) —
  the resource-server SDK that performs (classical) token validation.
- [Keys](/operate/keys/) — generating the ML-DSA seed this feature needs.

---

# Upgrades

URL: https://docs.qauth.dev/operate/upgrades/

Every upgrade takes the same three steps: back up the database, run the new
version's migration runner, then start the new version. Migrations only go
forward and downgrades are not supported, so the backup is your only way back
([ADR-018 §5](/reference/records/adr/018-1-0-scope-and-stability/)).

## Upgrade procedure

### 1. Back up the database

```bash
# Adjust host, container and credentials to your deployment.
docker exec qauth-postgres pg_dump -U qauth -d qauth -F c -f /tmp/qauth-pre-upgrade.dump
docker cp qauth-postgres:/tmp/qauth-pre-upgrade.dump ./qauth-pre-upgrade.dump
```

Confirm the dump is not empty. Restoring it later discards every write made
after it was taken.

### 2. Run the migration runner of the new version

The runner is the `migration-runner` image built from
`apps/migration-runner/Dockerfile`. Each release also publishes it, signed, as
`ghcr.io/qauth-labs/qauth/migration-runner` (see
[Published images](/operate/images/)). It holds Node and one program, with the
new version's migrations beside it, and needs only `DATABASE_URL`:

```bash
# Docker Compose: build the new version's image, then run it once.
docker compose build migration-runner
docker compose run --rm migration-runner

# Any other platform: run the image as a one-off job.
docker run --rm -e DATABASE_URL='postgresql://qauth:…@db:5432/qauth' qauth/migration-runner

# From a checkout of the new version, with pnpm installed.
pnpm nx run migration-runner:migrate
```

It applies every pending migration in one transaction and logs each with its
duration:

```text
Applying 2 migrations in one transaction: 0034_webauthn_rp_id_lock, 0035_event_deliveries.
  0034_webauthn_rp_id_lock ran in 14 ms
  0035_event_deliveries ran in 34 ms
Applied 2 migrations in 212 ms. The database is current.
```

It is safe to run twice. A run on a current database prints
`The database is current: all 36 migrations are applied. Nothing to do.` and
exits `0`. The runner holds a Postgres advisory lock while it works, so a second
runner started beside it, for example by every node of a cluster at once, waits
for the first, then finds nothing to do.

| Exit code | Meaning                                                                                                                                                                                          |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `0`       | The database is current: the run applied the pending migrations, or there were none.                                                                                                             |
| `1`       | A migration failed. The error names it, and the whole run rolled back: no migration of the run was applied. With `--check`: migrations are pending.                                              |
| `2`       | Usage error: an unknown flag, `DATABASE_URL` is not set, or the system-client or `DB_USER_*` variables are incomplete or invalid. Nothing was done.                                              |
| `3`       | The run could not start: the database is unreachable, or the migrations folder cannot be read.                                                                                                   |
| `4`       | Every migration is applied, but the system client set by `SYSTEM_CLIENT_REDIRECT_URI` could not be provisioned. The error names why.                                                             |
| `5`       | Every migration is applied, but the grants of the roles' database users named by `DB_USER_*` could not be applied. They are as they were. It wins over `4` when both fail; the errors name both. |

`--check` reports the pending migrations and changes nothing: it takes no lock
and creates nothing, so a read-only database role can run it.

```bash
docker compose run --rm migration-runner --check
```

```text
The database lacks 1 of 36 migrations: 0035_event_deliveries. Run the migration runner without --check to apply them.
```

A failed run changed nothing. Fix the cause the error names, then run the
runner again.

### 3. Start the new version

```bash
docker compose up -d --build auth-server
```

`--build` builds the new version's image first: without it, Compose starts the
image it built for the old version. Rebuild `developer-portal` the same way when
you run it.

At boot the auth server compares the database with the migrations of its own
release. When the database lacks some, the server waits for the migration
runner, up to `DB_MIGRATION_WAIT_MS` (60 seconds by default, `0` to check once),
then exits non-zero with a message that names the missing migrations:

```text
The database lacks 1 migration this release needs: 0035_event_deliveries. Waited 60 s for the migration runner. Run it against this database, then start the server again.
```

So a server started beside the runner, as a platform without job ordering
does, waits for it instead of failing on a missing table.

A database **ahead** of the release does not stop the server: during a rolling
upgrade the old version keeps running on the new schema for a short time. The
server logs a warning with the number of newer migrations and starts.

### Release notes that need more than these steps

Read the release's `CHANGELOG.md` entry before you upgrade. Two upgrades need
more: the upgrade from 0.1 to 0.2, in the next section, and migration 0011 in
QAuth's history, at the end of this page.

## Upgrading from 0.1 to 0.2

:::caution[Back up first. Downgrades are not supported.]
Take the backup of [step 1](#1-back-up-the-database) before anything else.
There is no way back from 0.2 to 0.1 but to restore that backup: every write
made after it is lost. Keep the 0.1 release's environment, its key variables
included: a restored 0.1 deployment needs them again. Keep it apart from the
database backups, as you keep the KEK: the key variables hold the private keys
in the clear, and 0.2 goes on signing with them.
:::

0.2 brings the deployment topology of
[ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/):
one host and one issuer per realm, keys in an encrypted key store, browser
sessions in Postgres, service roles, and health, readiness and metrics per
process. [Topology](/operate/topology/) describes the result. Most of it needs
no action. This section says what does, in order.

| What changes                                         | What breaks when you do nothing                                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| The default realm answers on its issuer's host only. | A caller that reaches the server by another name, such as an internal name, gets `421`.                |
| Keys move into a key store, wrapped by a KEK.        | With `NODE_ENV=production`, the server does not start without a KEK.                                   |
| Browser sessions move to Postgres.                   | Every signed-in user signs in once more.                                                               |
| `/health` checks nothing; `/ready` does.             | A probe on `/health` no longer takes a process out of rotation when Postgres or Redis is down.         |
| The metrics leave the public port.                   | A scrape of `/metrics` gets `404`.                                                                     |
| Two private-address switches are removed.            | A deployment that sets `CIMD_ALLOW_PRIVATE_ADDRESSES` or `ID_JAG_ALLOW_PRIVATE_ADDRESSES` won't start. |

### The upgrade, step by step

1. **Back up the database** ([step 1](#1-back-up-the-database)). Keep the 0.1
   environment apart from it, as you keep the KEK.
2. **Make a KEK and keep it apart from the database.** Run
   `openssl rand -base64 32`. Set the output as `KEK`, or put it in a file and
   set `KEK_PATH`. Store a copy where your database backups are not. See
   [The KEK](#the-kek).
3. **Keep `JWT_ISSUER` as it is.** It becomes the default realm's issuer, and
   its host the realm's host, for good. See
   [The issuer becomes permanent](#the-issuer-becomes-permanent).
4. **List your internal host names in `DEFAULT_REALM_ENDPOINT_HOSTS`.** Name
   every host a server-side caller uses to reach the auth server, such as the
   host of the developer portal's `AUTH_SERVER_URL`. See
   [Endpoint hosts](#endpoint-hosts-for-server-side-callers).
5. **Leave the key variables set for the first boot, and do not change
   them.** The first boot imports them into the key store. See
   [The key import](#the-key-import-and-its-boot-warnings).
6. **Unset `CIMD_ALLOW_PRIVATE_ADDRESSES` and `ID_JAG_ALLOW_PRIVATE_ADDRESSES`.**
   If you set either, read
   [The private-address switches are gone](#the-private-address-switches-are-gone).
7. **Move your probes.** Point readiness probes and load balancer health
   checks at `/ready`, and liveness probes at `/health`. Move the Prometheus
   scrape to the internal listener. See
   [Health, readiness and metrics](#health-readiness-and-metrics).
8. **Read the notes of this release below, from
   [Users sign in once more](#users-sign-in-once-more-after-the-upgrade-to-v02)
   on, then run the migration runner** ([step 2](#2-run-the-migration-runner-of-the-new-version)).
   Some migrations pause token requests while they run.
9. **Start 0.2** ([step 3](#3-start-the-new-version)) **and read the boot
   log.** A good first boot logs `default realm ready` and `realm keys ready`,
   and one warning for each key variable that is still set.
10. **Check the deployment.** See [Check the upgrade](#check-the-upgrade).
11. **Remove the old key variables after the first good boot.** See
    [Remove the key variables](#remove-the-key-variables).
12. **Tell your users.** Each user signs in once more, and developers sign in
    to the portal again
    ([the portal's token](#the-developer-portals-token-moves-to-the-developer-apis-audience)).
    Relying parties that verify tokens themselves follow
    [the JWKS rule](/operate/keys/#what-relying-parties-do-with-the-jwks).

With Docker Compose, `docker-compose.yml` already forwards `KEK`, sets
`DEFAULT_REALM_ENDPOINT_HOSTS` to `auth-server`, the portal's name for the
server, and checks `/ready`. Add `KEK` to your `.env`, or set `KEK_PATH` and
mount the file into `auth-server` as a Compose secret, as the comment above
`KEK_PATH` in `docker-compose.yml` shows: without the mount the server does
not start. Set `DEFAULT_REALM_ENDPOINT_HOSTS` only when other callers reach the
server by other names, and list `auth-server` among them.

### New settings

The settings 0.2 adds for hosts, keys, sessions and roles.
[Configuration](/operate/configuration/) lists every key, those of other areas
new in 0.2 among them.

| Setting                              | Default                                          | What it sets                                                                                                                                   |
| ------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `DEFAULT_REALM_ENDPOINT_HOSTS`       | empty                                            | Host names, comma-separated, that server-side callers reach the default realm by. Added as endpoint hosts at boot.                             |
| `WEBAUTHN_RP_ID`                     | the default realm's host, from `JWT_ISSUER`      | The default realm's passkey RP ID. Locked once the realm has a passkey.                                                                        |
| `WEBAUTHN_RP_ID_ALLOW_PARENT_DOMAIN` | `false`                                          | Allows a parent domain of the realm host as the RP ID. The server warns at every boot.                                                         |
| `KEK_PROVIDER`                       | `local`                                          | Where the KEK lives. `local` reads `KEK` or `KEK_PATH`. Another name loads the adapter package `@qauth-labs/keys-<name>`.                      |
| `KEK`                                | none; outside production, a published dev KEK    | The KEK, as the base64 of 32 random bytes. `NODE_ENV=production` refuses to start without a KEK.                                               |
| `KEK_PATH`                           | none                                             | A file holding the KEK. It wins over `KEK`.                                                                                                    |
| `KEK_PREVIOUS`                       | none                                             | The KEK in use before a KEK rotation. Keys wrapped under it still open.                                                                        |
| `KEK_PREVIOUS_PATH`                  | none                                             | A file holding the previous KEK. It wins over `KEK_PREVIOUS`.                                                                                  |
| `KEK_AWS_*`, `KEK_VAULT_*`           | see [Keys](/operate/keys/#environment-variables) | The settings of the two KEK adapter packages.                                                                                                  |
| `SESSION_LAST_SEEN_INTERVAL`         | `60`                                             | How often, at most, in seconds, a browser session's last-seen time is written.                                                                 |
| `SESSION_RETENTION_DAYS`             | `30`                                             | The days an ended browser session is kept before the purge job deletes it.                                                                     |
| `SERVICE_ROLES`                      | `all`                                            | The roles this process runs: `all`, or a list of `web`, `api`, `admin`, `signer` and `delivery`. See [Service roles](/operate/service-roles/). |
| `SIGNER_URL`                         | none                                             | The `https` URL of the signer service, on a process without the `signer` role.                                                                 |
| `INTERNAL_HOST`                      | `127.0.0.1`                                      | The address the internal listener binds to.                                                                                                    |
| `INTERNAL_PORT`                      | `3443`                                           | The port of the internal listener. It must differ from `PORT` and `ADMIN_API_PORT`.                                                            |
| `INTERNAL_TLS_CERT_PATH`             | none                                             | This process's certificate for mutual TLS between the roles.                                                                                   |
| `INTERNAL_TLS_KEY_PATH`              | none                                             | The private key of that certificate.                                                                                                           |
| `INTERNAL_TLS_CA_PATH`               | none                                             | The CA certificates that issue every peer's certificate.                                                                                       |
| `INTERNAL_PEER_ROLES`                | none                                             | A JSON object from a peer certificate's SAN to the role it calls as, or to `metrics` for a scraper.                                            |
| `EGRESS_ALLOWLIST_PATH`              | none                                             | A JSON file of private hosts and ranges that operator- and admin-set destinations may reach, per realm.                                        |

These settings change meaning:

| Setting                                                                                                                                             | In 0.2                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_ISSUER`                                                                                                                                        | The default realm's permanent issuer. A later boot with another value refuses to start.                                                                                                                                                           |
| `JWT_PRIVATE_KEY`, `JWT_RS256_PRIVATE_KEY`, `JWT_MLDSA_PRIVATE_KEY`, `SESSION_COOKIE_SECRET`, `OID4VP_VERIFIER_SIGNING_KEY` and their `_PATH` forms | Optional. The key boot step imports them into the key store, where a new value replaces the stored key. `JWT_PRIVATE_KEY` or `JWT_PUBLIC_KEY` also picks the key that verifies 0.1's tokens without a `kid` ([below](#remove-the-key-variables)). |
| `METRICS_ENABLED`                                                                                                                                   | Serves the metrics at `GET /internal/metrics` on the internal listener, never on the public port.                                                                                                                                                 |
| `OID4VP_RESPONSE_KEY_SECRET`                                                                                                                        | Read only to open wallet request states written by 0.1, which expire within 15 minutes.                                                                                                                                                           |

`CIMD_ALLOW_PRIVATE_ADDRESSES` and `ID_JAG_ALLOW_PRIVATE_ADDRESSES` are removed.

### The issuer becomes permanent

At the first boot, `JWT_ISSUER` becomes the issuer of the default realm
(`DEFAULT_REALM_NAME`, `master` by default), and its host the realm's primary
host. Both are permanent: a database trigger refuses to change them. Every
issued token, registered client and enrolled passkey depends on them.

- **The realm row.** 0.1 created the default realm with no issuer. The first
  boot of 0.2 fills in its issuer and host. Existing clients, tokens and
  consents keep working.
- **A later change refuses the boot.** A boot whose `JWT_ISSUER` differs from
  the stored issuer stops with
  `A realm's issuer and its host are permanent: set JWT_ISSUER to "<stored>".`
  The comparison is exact, letter case and port included, after one trailing
  slash is removed.
- **A trailing slash.** The realm stores the issuer without it, and its
  discovery documents and tokens name it that way. Each boot warns
  `JWT_ISSUER ends with a slash: ... remove the slash`. 0.1 named the issuer
  with the slash in its tokens, and 0.2 checks `iss` against the stored form.
  So 0.2 refuses every access token issued before the upgrade: a client gets
  `401` until it uses its refresh token, which still works, or signs in again.
  A relying party that compares `iss` with the slashed form must drop the
  slash. Upgrade such a deployment all at once, not node by node: in a mixed
  fleet each release refuses the other's access tokens until they expire.
- **A path.** `https://example.com/auth` keeps working: the issuer keeps its
  path, and only the host routes requests to the realm. Each boot warns that
  `JWT_ISSUER has a path`. A new realm's issuer is an origin with no path, and
  QAuth needs a [dedicated host](/operate/topology/#a-dedicated-host-never-a-path).
- **A host it refuses.** The host must be a name, not an IP address, because a
  passkey RP ID cannot be one. Plain `http` is accepted for `localhost` and
  `*.localhost` only. Either refusal stops the first boot, and nothing is
  written.

The port is part of the issuer, not of the host: `https://auth.example.com:8443`
has the host `auth.example.com`.

Keep `DEFAULT_REALM_NAME` as it is too: the boot finds the default realm by
that name.

### Endpoint hosts for server-side callers

From 0.2 a request belongs to the realm whose host it names. The server reads
the host from `Host`, or from `X-Forwarded-Host` when the hop that sent it is
listed in `TRUST_PROXY`. The match ignores case and the port. A request for any
other host gets `421 Misdirected Request`, with no cookie and no fallback to the
default realm. Only `/health` and `/ready` answer on every host.

So a server-side caller that reaches the auth server by another name breaks,
unless that name is an **endpoint host** of the realm. List every such name in
`DEFAULT_REALM_ENDPOINT_HOSTS`, comma-separated:

- the host of the developer portal's `AUTH_SERVER_URL` (`auth-server` in the
  Compose file);
- the host a resource server introspects tokens at, or fetches the JWKS from,
  when it is not the issuer's host;
- an internal load balancer's name, or an IP address that a monitor calls.

```bash
DEFAULT_REALM_ENDPOINT_HOSTS=auth-server,auth.internal.example
```

Write bare host names: a port is dropped, and a scheme, path or wildcard
refuses the boot. Each boot adds every listed host the realm lacks, and never
removes one: a shorter list later changes nothing. A host belongs to one realm
only, as one kind, so the boot refuses the issuer's own host, or a host of
another realm.

An endpoint host answers the API routes: token, introspection, revocation,
userinfo, registration, discovery, JWKS, the `/auth/*` API routes and the
account and developer APIs. It refuses the browser-session routes with `421`:
`/oauth/authorize`, `/ui/*`, the Interaction API, `/consents`,
`/auth/link/wallet` and the email verification page (`GET /auth/verify`). A
browser always uses the issuer's host.

A reverse proxy in front of the server must pass the realm host as `Host`, or
set `X-Forwarded-Host` and be listed in `TRUST_PROXY`. A proxy that sends its
upstream's name instead (`proxy_set_header Host auth-server`) makes every
request a `421`. See [Reverse proxy](/operate/reverse-proxy/).

### The KEK

The key store wraps every stored key with a key-encryption key (KEK). The
default provider, `KEK_PROVIDER=local`, reads it from `KEK` or `KEK_PATH`.

**Make one.** The KEK is the base64 of 32 random bytes:

```bash
mkdir -p -m 700 ~/qauth-secrets
(umask 077 && openssl rand -base64 32 > ~/qauth-secrets/qauth-kek)
```

`umask 077` keeps the file its owner's alone from the start. Keep it in a
directory of its own, outside any git checkout and apart from the database
backups. [Keys](/operate/keys/#the-kek) says how a container reads it.

Set `KEK_PATH` to the file, or `KEK` to its content. `KEK_PATH` wins when both
are set, and the server warns when group or others can read the file. Give it
to every process that holds the `signer` role: every process, while
`SERVICE_ROLES` is `all`. A process without that role refuses to boot with a
KEK.

**Keep it apart from the database.** The database holds the stored keys,
wrapped. Whoever holds a database backup and the KEK holds every key. So never
put the KEK in the database backup, and back it up on its own, for example in
your secret manager and once more offline. A restored backup needs the KEK it
was taken under.

**Losing it loses every stored key.** Nothing opens a stored key without the
KEK that wrapped it. The signing keys, the cookie key, the data-at-rest key
and the realm secrets it protects, such as the mail password, are lost with
it: the server can no longer sign a token or a cookie, and `/ready` fails its
`kek` check.

Outside production the server falls back to a published development KEK and
warns. It refuses to import a key variable under it, in every environment.
`NODE_ENV=production` refuses to start without a KEK, and refuses the
development KEK. A key management service can hold the KEK instead, through
an adapter package; choose the provider before the first boot, as
[Keys](/operate/keys/#the-kek) describes.

### The key import and its boot warnings

The first boot of a process that holds the `signer` role imports the key
variables into the default realm's key store, under an advisory lock, so nodes
that start together import once:

| Variable                                | Becomes                                                      |
| --------------------------------------- | ------------------------------------------------------------ |
| `JWT_PRIVATE_KEY` / `_PATH`             | The Ed25519 token signing key                                |
| `JWT_RS256_PRIVATE_KEY` / `_PATH`       | The RS256 token signing key, which then signs ID tokens      |
| `JWT_MLDSA_PRIVATE_KEY` / `_PATH`       | The ML-DSA-65 key of the hybrid pair, with hybrid signing on |
| `SESSION_COOKIE_SECRET`                 | The cookie key                                               |
| `OID4VP_VERIFIER_SIGNING_KEY` / `_PATH` | The wallet verifier's request-signing key                    |

The keys themselves do not change, so the tokens 0.1 signed still verify. The
boot then creates the keys the realm lacks: the event-signing and data-at-rest
keys, and the cookie key when `SESSION_COOKIE_SECRET` is unset. A realm that
imports no signing key gets an Ed25519 and an RS256 one. A realm that imports
only `JWT_PRIVATE_KEY` gets no RS256 key, and keeps signing ID tokens with
EdDSA: add one with
[`auth-server:keys:create`](/operate/keys/#adding-a-key-auth-serverkeyscreate).

Every boot logs one info line, `realm keys ready`, that names each key it
imported or created, by purpose, algorithm and `kid`. Then it warns once for
each key variable still set, for example:

```text
JWT_PRIVATE_KEY is in the realm's key store, which signs the tokens: the variable is read only at boot, where a new key in it replaces the stored key and unpublishes the old one at once. Remove it unless you may roll back to a release that signs with it.
```

The warnings are expected after the upgrade. They stop when you remove the
variables. A variable that holds a **new** key at a later boot replaces the
stored key, and the old key leaves the JWKS at once
([Replacing a signing key](/operate/keys/#replacing-a-signing-key)): do not
change a key variable during the upgrade.

The boot stops, naming the variable, when no KEK is set, when a public key
variable is not the half of its private key, when an RS256 key is shorter than
2048 bits, or when a variable's `kid` already names another stored key.

### Check the upgrade

```bash
ISSUER=https://auth.example.com   # your JWT_ISSUER

curl -fsS "$ISSUER/ready"
curl -fsS "$ISSUER/.well-known/openid-configuration" | grep -o '"issuer":"[^"]*"'
curl -fsS "$ISSUER/.well-known/jwks.json"
```

- `/ready` answers `200`, with every check `ok`.
- Discovery names `JWT_ISSUER`, without a trailing slash.
- The JWKS lists the `token_signing` keys of the `realm keys ready` line, each
  with its `kid`. The line's other keys, such as `cookie_hmac` and
  `data_at_rest`, are never in the JWKS.
  An imported key's `kid` is `JWT_RS256_KID` or `JWT_MLDSA_KID` when set, and
  otherwise the RFC 7638 thumbprint of its public key.
- An access token issued before the upgrade still introspects `active: true`,
  and a refresh token issued before it still rotates. With a slashed
  `JWT_ISSUER`, only the refresh token does
  ([The issuer becomes permanent](#the-issuer-becomes-permanent)).
- Each endpoint host answers. With Compose, from the portal's container:

  ```bash
  docker compose exec developer-portal node -e \
    "fetch('http://auth-server:3000/.well-known/openid-configuration').then((r) => console.log(r.status))"
  ```

  `200` means the host is an endpoint host; `421` means it is missing from
  `DEFAULT_REALM_ENDPOINT_HOSTS`.

### Remove the key variables

Remove the private key variables once all three hold:

- every node runs 0.2;
- the first boot logged `realm keys ready` with each key imported;
- you will not go back to 0.1, which signs with them. A rollback restores the
  backup and needs them again, so keep a copy with the KEK until then.

That is `JWT_PRIVATE_KEY`, `JWT_RS256_PRIVATE_KEY`, `JWT_MLDSA_PRIVATE_KEY`,
`SESSION_COOKIE_SECRET`, `OID4VP_VERIFIER_SIGNING_KEY` and their `_PATH`
forms, with `JWT_RS256_PUBLIC_KEY`, `JWT_RS256_KID` and `JWT_MLDSA_KID`. Keep
the OID4VP certificate chain variables: they are public and name the stored
key.

One public key stays a little longer. An access token issued by 0.1 names no
key (`kid`), and the server verifies such a token only with the Ed25519 key
that `JWT_PRIVATE_KEY` or `JWT_PUBLIC_KEY` holds. So, when you remove
`JWT_PRIVATE_KEY`, keep `JWT_PUBLIC_KEY` set to its public half
(`openssl pkey -in jwt-private.pem -pubout`) until the longest access token
lifetime has passed since the last 0.1 node stopped: `ACCESS_TOKEN_LIFESPAN`,
15 minutes by default, or `DEV_ACCESS_TOKEN_LIFESPAN` for development clients,
8 hours by default. Then remove it too. The next release refuses every token
without a `kid`.

Remove `OID4VP_RESPONSE_KEY_SECRET` 15 minutes after the last 0.1 node stopped,
and `SMTP_PASSWORD` and `RESEND_API_KEY` once every node runs 0.2
([Mail secrets move into the realm](#mail-secrets-move-into-the-realm)).

### Health, readiness and metrics

- **`/health` is liveness.** It answers `200` while the process serves, with
  its service roles, and checks nothing. 0.1 checked Postgres and Redis there
  and answered `503` when one was down.
- **`/ready` is readiness.** It runs the checks of the process's roles
  (`database`, `redis`, `kek`, `outbox`) and answers `200`, or `503` with a
  problem document that names the failing check.
- **The metrics are on the internal listener.** `GET /internal/metrics` on
  `INTERNAL_HOST:INTERNAL_PORT` (`127.0.0.1` and `3443` by default). The public port
  answers `404` to `/metrics`. A single process without the internal TLS files
  serves them in plain HTTP on loopback only; a scraper on another machine
  needs mutual TLS, with its certificate's SAN mapped to `metrics` in
  `INTERNAL_PEER_ROLES`.

Both probes answer on every host and carry no realm data. The Compose file's
health check calls `/ready`; the image's own `HEALTHCHECK` stays on `/health`.
See [Health and readiness](/operate/observability/#health-and-readiness) and
[Who can read the metrics](/operate/observability/#who-can-read-the-metrics).

### The private-address switches are gone

0.2 sends every outbound call through one egress client, which never connects
to a private, loopback or link-local address on its own
([ADR-019 Decision 8](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)).
`CIMD_ALLOW_PRIVATE_ADDRESSES` and `ID_JAG_ALLOW_PRIVATE_ADDRESSES` are
removed. A value that is not blank stops the boot with a message that names the
replacement:

- **`CIMD_ALLOW_PRIVATE_ADDRESSES`** has nothing to replace it. A client's
  metadata document and its `jwks_uri` come from the client, and never reach a
  private address now. A test reaches a local server through the test-only
  `createTestEgressClient`.
- **`ID_JAG_ALLOW_PRIVATE_ADDRESSES`** is replaced by the egress allowlist. A
  trusted issuer's discovery URL on a private address is listed, for the realms
  that trust it, in the JSON file `EGRESS_ALLOWLIST_PATH` names. The `jwks_uri`
  its discovery document names never reaches a private address.

```json
{
  "entries": [
    { "host": "idp.corp.example", "realms": ["master"] },
    { "cidr": "10.20.0.0/16", "realms": ["master"], "note": "partner VPN" }
  ]
}
```

See [Outbound calls and the egress allowlist](/operate/docker/#outbound-calls-and-the-egress-allowlist)
for the file's rules.

### Service roles are optional

`SERVICE_ROLES` defaults to `all`: one process runs every role, as 0.1 did.
Nothing changes until you split the roles. [Service roles](/operate/service-roles/)
says which splits work in this release, and [Topology](/operate/topology/#service-roles-and-mutual-tls)
how they fit together.

### The operator realm

In simple mode, one realm on one host, the default realm is also the
**operator realm**
([ADR-019 Decision 1](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)).
The first boot of 0.2 marks it so. Its admins are the operator's admins, and
the admin console will be a client of it. A one-host deployment needs no
second realm, host or issuer for administration.

Adding a second realm splits the two, in a step called the operator-realm
split:

- The default realm keeps its host and its issuer, which are permanent. Its
  clients, users, tokens and passkeys are untouched.
- The operator realm becomes a realm of its own, on a host of its own, with its
  own DNS name and certificate. Operator admins and service accounts sign in
  there, and the admin console moves to that host.

0.2 has no way to add a second realm, so the split cannot happen yet: the realm
lifecycle operations of the admin API
([#694](https://github.com/qauth-labs/qauth/issues/694)) add realms, and this
guide gives the split's commands with them. Meanwhile, choose the operator
realm's host and keep it free, so that it can get its DNS name and certificate
when the split comes.

### Users sign in once more after the upgrade to v0.2

From v0.2 the auth server keeps browser sessions in Postgres, with Redis as a
cache in front of them
([ADR-019 Decision 3](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)).
The upgrade does not move the sessions an earlier version kept in Redis. A user
who was signed in to the hosted pages (`/ui/login`, the consent screen, wallet
sign-in) is asked to sign in once more. A consent screen open during the
upgrade is refused when it is submitted and shown again after that sign-in.

Nothing else is lost. Access tokens, refresh tokens and stored consents are
untouched, so an application that already holds tokens keeps working without
the user. The old Redis session keys (`session:<id>`, and the per-user lists
`user-browser-sessions:<user id>` that logout read) are no longer read and
expire on their own within `SESSION_COOKIE_TTL`; there is nothing to delete.

The session cookie changes too: v0.2 signs it with the realm's cookie key from
the key store, and the cookie names that key
([#493](https://github.com/qauth-labs/qauth/issues/493)). A cookie an earlier
version signed with `SESSION_COOKIE_SECRET` does not verify, and the new version
clears it. `SESSION_COOKIE_SECRET` becomes optional: at the first boot the key
store imports it as the realm's cookie key, and later a different value in it
replaces that key. See [the key store](/operate/keys/#the-key-store).

During a rolling upgrade the two cookie formats do not mix. A node of the old
version refuses the new cookie, and when the user signs in there it sets a
cookie of the old format, which a node of the new version clears. A browser
whose requests go to old and new nodes in turn is asked to sign in again at
each switch, not once, until the last old node is gone. Send the browser
traffic (`/ui/*`, `/oauth/authorize`, the consent screen) to the new nodes only
as soon as the first one is up, or route each browser to one node for the
duration of the roll (sticky sessions); a single-node deployment, or one
upgraded stop-start, is unaffected.

### The developer portal's token moves to the developer API's audience

The developer portal's token moves to the developer API's audience,
`urn:qauth:aud:developer:v1-rc.0`. ADR-018 §5 would take that in two releases,
expand then contract
([API conventions](/reference/api-conventions/#issuing-a-family-audience)),
but v0.2 carries both steps at once:

- **Accepted** ([#509](https://github.com/qauth-labs/qauth/issues/509)).
  `/api/clients`, `/api/consents`, `/auth/logout` and userinfo accept a
  system-client token whose `aud` is the developer audience.
- **Minted, and the old token retired**
  ([#524](https://github.com/qauth-labs/qauth/issues/524)). As each node of v0.2
  boots, it gives the system client of every realm the developer audience, so
  `POST /auth/login` mints the new token from then on, on every node, since
  each one reads the client's row. The deprecated `/api/clients` and
  `/api/consents` accept only the new token. `/auth/logout` still accepts a
  live old one, whose `aud` is the system client's id, for this release only,
  so a developer whose portal session began before the upgrade can still sign
  out: the call ends their sessions, refresh tokens and codes, and grants
  nothing. An expired old token is refused, and the next release removes the
  grace. The Bearer path of `/oauth/authorize` is
  gone: an `Authorization` header there signs no one in, and a request without
  a browser session goes to the login page.

What an operator sees when v0.2 rolls out:

- **Developers sign in to the portal again.** A portal token minted before the
  first node of v0.2 booted carries the system client's id as its `aud`, and
  every v0.2 node refuses it, except to sign out (a token lives
  `ACCESS_TOKEN_LIFESPAN`, 15 minutes by default). The portal answers the
  refusal by sending the developer to its login page.
- **During a rolling upgrade from v0.1.x, more than once.** A v0.1.x node
  does not accept the new token: it refuses userinfo to it, so a developer
  whose request reaches an old node is signed out of the portal, and a token an
  old node minted is refused by the new ones. Until the roll ends, a developer
  is signed out whenever a request reaches a node of the other version than the
  one that signed them in; a portal session lasts `PORTAL_SESSION_TTL`
  (15 minutes by default). A single-node deployment, or one upgraded
  stop-start, is unaffected.
- **A caller of `/oauth/authorize` with a Bearer token stops getting codes.** No
  shipped component used that path; anything that did must send the user through
  the browser flow, as every other client does.
- There is no migration and nothing to run: the boot step changes one row per
  realm and logs `Gave the system client the developer API audience` when it does.

### The developer and account APIs need their scopes

From this release an operation of the developer API (`/developer/v1-rc.0`) or
the account API (`/account/v1-rc.0`) needs, beside the family's audience, the
family's scope of its class: `qauth:developer:read` or `qauth:developer:write`,
`qauth:account:read` or `qauth:account:write`
([#933](https://github.com/qauth-labs/qauth/issues/933)). A token without it is
refused with 403 `forbidden`. The deprecated `/api/clients` and `/api/consents`
routes need the same scopes as the operations they alias, and attributing a
dynamic registration to a developer (`POST /oauth/register` with the
developer's token) needs `qauth:developer:write`. The developer portal's token
carries both developer scopes, so the portal needs nothing. For this release
only, a portal token that names no scope, which a node of the previous release
mints, counts as carrying both, so a developer whose portal session began
before the upgrade, or on a node not yet upgraded, keeps working during and
after the rolling upgrade. The next release refuses such a token; by then
every one has expired. A client you gave a family
audience in its `audience` (the seed manifest's `clients[].audience`) also
needs the scopes it will use in its `scopes`, and asks for them in `scope`; the
token endpoint issues them only to a client that lists the family's audience,
for a token that names a user. There is no migration and nothing to run.

### Refresh tokens pause while migration 0038 runs

Migration 0038 ([#552](https://github.com/qauth-labs/qauth/issues/552)) records
when each refresh-token family started. It fills the new column for every row
of `refresh_tokens` in one statement, inside the runner's transaction. Before
anything else it locks `authorization_codes` and then `refresh_tokens`, the
order a code redemption takes them in, and holds both until that transaction
commits. While the runner works, every request that reads or writes a refresh
token or an authorization code waits: a code exchange, a refresh,
`POST /auth/login`, minting a code at `/oauth/authorize` or on the consent
screen, and the purge job. Nothing fails; those requests finish once the runner
does, unless your proxy or client gives up first. A database that ran 0038 from
`main` before its locks moved to the start is unaffected: the change only
reorders its locks, and the runner never runs a migration twice.

The pause grows with the number of rows in `refresh_tokens`, rotated and
revoked tokens included. Measured on a 12-vCPU AMD EPYC virtual machine with
47 GB of memory, against a `postgres:18-alpine` container on its default
settings (`shared_buffers` 128 MB, `max_wal_size` 1 GB), with five tokens per
family:

| Rows in `refresh_tokens` | Table size | Whole migration | A token insert waited |
| ------------------------ | ---------- | --------------- | --------------------- |
| 100,000                  | 58 MB      | 5.7 s           | 4.7 s                 |
| 1,000,000                | 588 MB     | 100 s           | 99.8 s                |

Almost all of it is the `UPDATE` (5.5 s and 98.4 s). Taking the locks first
adds no work, so these figures, measured before the locks moved, still hold;
minting a code now waits as long as a token insert. These were default
settings; more `shared_buffers` and a larger `max_wal_size` may shorten the
pause, which we have not measured. To estimate your own, count first:

```sql
SELECT count(*) FROM refresh_tokens;
```

With many rows, run the migration at a quiet hour, and keep the proxy's and
the clients' timeouts above the expected pause.

Migrations 0038 and 0041 both take their locks in a redemption's order: a
redemption spends its code in `authorization_codes`, then stores the refresh
token it buys. So a redemption in flight during the upgrade, on a node of either
version, waits for the runner instead of deadlocking with it.

### Migration 0041 reads `refresh_tokens` once more

Migration 0041 ([#627](https://github.com/qauth-labs/qauth/issues/627)) links
each refresh-token family to the authorization code that started it. It adds a
column that starts empty, so it rewrites no row, but its foreign key and index
each read the whole table while the runner holds the lock 0038 described. It
first locks `authorization_codes` against writes, then `refresh_tokens`, in the
order a redemption takes them, so it cannot deadlock with one. So minting a
code at `/oauth/authorize` or on the consent screen, redeeming one at
`/oauth/token` and a logout wait until the runner commits, on nodes of either
version. On the same virtual machine, against a `postgres:18-alpine` container
with 1,000,000 rows in `refresh_tokens` (531 MB), it took 1.3 s, and a token
insert waited for it. Upgrading from a release before 0038 runs 0038 and 0041
in the one transaction, so the two pauses add up.

The same release records each access token it issues from a code or a refresh
family in Redis, so that a replay can deny-list them. It sets those records'
lifetimes with `EXPIRE` and its `NX` and `GT` options, which need **Redis 7.0
or later**. The bundled Compose file runs Redis 7; check the version of a Redis
you run yourself.

### Migration 0042 holds sign-ins while it reads `authorization_codes`

Migration 0042 ([#549](https://github.com/qauth-labs/qauth/issues/549)) records
the browser session behind each authorization code. It adds a column that
starts empty, so it rewrites no row, but its foreign key and index each read
the whole of `authorization_codes`. It first locks `sessions` against writes,
then `authorization_codes`, in the order a code's mint and a session's
revocation take them, so it cannot deadlock with either. So a sign-in, a
sign-out, minting a code and redeeming one wait until the runner commits, on
nodes of either version. Codes live five minutes and the purge job deletes
expired ones, so the table is usually small and the pause short.

### Admin scopes and the admin audience need an admin grant

From this release the token endpoint issues a `qauth:admin:*` scope only to an
account that holds an admin grant reaching that scope's class, through a client
that lists the admin API's audience, and the admin audience only to an account
that holds an admin grant ([#510](https://github.com/qauth-labs/qauth/issues/510)).
A `client_credentials` token gets neither, and neither do the ID-JAG grants or a
delegated token from token exchange. Migration 0043 adds the empty
`admin_grants` and `admin_roles` tables. Their foreign keys briefly lock
`realms` and then `users` against writes (reads go on), so a realm or account
change waits for the runner's commit. No admin route ships in this release,
so nothing that works today stops working; before you use the admin API, give
each account that will use it a grant. During a rolling upgrade a node of the
previous release still issues those scopes without the check, which reaches no
route either.

### Disabled accounts get the time of migration 0044

Migration 0044 ([#748](https://github.com/qauth-labs/qauth/issues/748)) records
when each account was last disabled, so that enabling it again brings back none
of the sessions and tokens it held. An account that is disabled when the
migration runs gets the time of the migration; every other account starts with
none. Only disabled rows are written, but finding them reads the whole `users`
table while the runner holds the lock the new column takes, so on a large table
sign-ins wait for the runner's commit. Run it when no long transaction holds
`users`: the migration sets no `lock_timeout`, so its `ALTER TABLE` queues
behind any open transaction that read the table, and every sign-in and token
request that reads `users` waits behind it while it queues. During a rolling
upgrade a node of the previous release still accepts the old sessions and
access tokens of an account enabled again, and can start new refresh families
from its old sessions: enable an account that was disabled for a takeover only
after every node runs this release ([Accounts](/operate/accounts/)).

An account that was disabled and enabled again before the upgrade gets no
time, and keeps every session and token the previous release brought back
when it was enabled. For each account you enabled again after a takeover,
once every node runs this release, run `db:disable-user` and then
`db:disable-user --enable`: that records the time now and ends everything the
account holds ([Accounts from before the upgrade](/operate/accounts/#accounts-from-before-the-upgrade)).

### Realm policies move onto the realm row

From this release a realm's policies live on its row in Postgres, and the
environment only seeds a new realm
([ADR-019 Decision 10](/reference/records/adr/019-deployment-topology-and-trust-boundaries/),
[#516](https://github.com/qauth-labs/qauth/issues/516)): the token lifetimes,
the verified-account requirement, the password and brute-force policy, client
registration, the mail sender and the environment ceiling, the fields of
[Realm policies](/reference/realm-policies/). Migration 0046 adds three columns
to `realms` and writes no row, so every realm starts the upgrade with no
policies.

**The first boot fills them.** The default realm's boot step gives every realm
that has no policies the values of the environment the server runs with: each
key whose role is `realm-seed` on [Configuration](/operate/configuration/), or
the field's default where the key is unset. Two settings the row already held
are kept, because the server read them from the row before: the environment
ceiling (`max_environment_laxity`), and the dynamic registration allowlist when
it holds a scope (an empty one gets `DEFAULT_DYNAMIC_REGISTRATION_SCOPES`, as
`/oauth/register` used it). The token lifetime columns were never read, so they
take `ACCESS_TOKEN_LIFESPAN` and `REFRESH_TOKEN_LIFESPAN`. The fill is an
`UPDATE ... WHERE policies_version = 0` per realm: of nodes that start
together, the first one writes and the others find the realm filled. So give
every node the same environment for the first boot after the upgrade; the
first node to boot decides the stored values. The log says
`realm policies filled from the environment` for each realm it filled, and
warns for each value a realm's row kept that differs from the environment's
seed (`... kept its posture.maxEnvironmentLaxity from its row ...`), so a
ceiling or an allowlist that does not follow the environment is named once.

**Later changes of the environment change no realm.** Once a realm has its
policies, its row owns them: a seed key only seeds a realm created later. The
flows move to the stored values one area at a time. In this release these
come from the row:

- The token lifetimes
  ([#527](https://github.com/qauth-labs/qauth/issues/527)):
  `ACCESS_TOKEN_LIFESPAN`, `DEV_ACCESS_TOKEN_LIFESPAN` and
  `REFRESH_TOKEN_LIFESPAN` set the lifetimes of a realm only while it has no
  policies (one a node of the previous release created during a rolling
  upgrade, until a node of this release boots again).
- The verified-account gate, the lowest password score and the failed sign-in
  lockout ([#528](https://github.com/qauth-labs/qauth/issues/528)):
  `REQUIRE_VERIFIED_ACCOUNT`, `PASSWORD_MIN_SCORE` and the four
  `FAILED_LOGIN_*` keys apply to a realm only while it has no policies, and
  each realm's own `accounts`, `password` and `bruteForce` policies apply once
  it has them. In particular, on a deployment that already ran this release,
  setting `REQUIRE_VERIFIED_ACCOUNT=false` no longer lets unverified accounts
  of the existing realms sign in; change the realm's stored policy instead.
- The mail transport and sender
  ([#529](https://github.com/qauth-labs/qauth/issues/529), see
  [Mail secrets move into the realm](#mail-secrets-move-into-the-realm)).
- Client registration
  ([#534](https://github.com/qauth-labs/qauth/issues/534)). `/oauth/register`
  and the clients API no longer write `DEFAULT_DYNAMIC_REGISTRATION_SCOPES`
  into a realm's list. A realm that has its policies is held to its own list,
  even an empty one; a realm with none yet, to the list its fill will hold,
  which the first boot stores. Whether a realm accepts an HTTPS URL as a
  `client_id`, its trust policy and its trusted domains are the realm's
  `registration.cimd` policy, which the authorization, consent and token
  endpoints and the realm's discovery documents read. `CIMD_ENABLED`,
  `CIMD_TRUST_POLICY` and `CIMD_TRUSTED_DOMAINS` seed a new realm only; the
  document cache, size and fetch timeout keys stay the deployment's.
- The environment ceiling, which the server read from the row before.

The verification link's lifetime and resend rule still read the environment.
Until an area has moved, the server still applies its keys to every realm, so
keep them set. At every boot the server names each seed key that is still set,
once:

- for a key whose policy the server reads from the row, a warning such as
  `DEFAULT_DYNAMIC_REGISTRATION_SCOPES only seeds new realms and is ignored`;
- for any other key, an info line that the stored policies ignore it, that
  the server still applies it to every realm until it reads that policy from
  the row, and that the stored value applies from then on.

For a key whose policy the server reads from the row, a second warning says
when the key is stricter than the stored value (`... is stricter than the
stored ...`), or, for a policy with no order such as `SMTP_HOST`, when it holds
another value (`... differs from the stored ...`): the stored value applies, so
store the key's value through the realm's policies if the realm should have it.
Nothing more is logged when they agree.

**A key changed after this upgrade never reaches the stored policies.** The
first boot stored the value each key had then. Change a key whose area has not
moved yet, and the server applies the new value while it reads the area from
the environment; the release that moves the area to the row applies the
stored value instead, whatever the key says by then. A key tightened in the
meantime, such as a lower `EMAIL_VERIFICATION_TOKEN_EXPIRY`, would loosen again
at that upgrade. So change the stored policy along with the key, not the key
alone. The token lifetimes, the sign-in policy and CIMD moved in the same
release as the policies themselves: a deployment that upgrades from 0.1 stores
those keys as they are at its first boot, and applies the stored values from
then on.

A realm's stored policies are changed with the admin API's realm policy
update, `realms.policies.update`
([#517](https://github.com/qauth-labs/qauth/issues/517)), on a process that
runs the admin listener. On a deployment without it, see
[Changing a realm's CIMD policy](/operate/docker/#changing-a-realms-cimd-policy).

**A value the policy schema refuses stops the boot.** The schema is stricter
than some keys were, so the server refuses to start, naming the key and never
its value, when a seed key holds one it refuses: a `CIMD_TRUSTED_DOMAINS` entry
that is a single label (`localhost`) or an IP address, an `EMAIL_FROM_NAME`
longer than 100 characters, a `DEFAULT_DYNAMIC_REGISTRATION_SCOPES` entry with a
character a scope cannot have. Correct the value and start the server again. A
value the fill keeps from a realm's row that the schema refuses, such as a
scope written into the allowlist by hand, stops the first boot too, naming the
realm and the field; a scope listed twice is kept once.

`SMTP_PASSWORD` and `RESEND_API_KEY` are never written to the row: they go to
the realm's secret store (see the next section). During a rolling upgrade a node of the
previous release reads none of the new columns and runs on the environment as
before. A realm such a node creates during the roll has no policies (counter 0)
until a node of this release boots again, since only the boot fills them, so
restart one node of this release once the roll is complete.

### Mail secrets move into the realm

From this release each realm sends its mail through its own transport and from
its own sender: `mail.provider`, `mail.fromAddress`, `mail.fromName` and
`mail.smtp.*` of its policies, read again for every mail
([#529](https://github.com/qauth-labs/qauth/issues/529)). The SMTP password and
the Resend API key are secrets: migration 0049 adds the `realm_secrets` table,
which holds each value encrypted with the realm's data-at-rest key and never
in the clear, and no response, log line, audit record or realm file shows one.
The realm's representation says only whether each is set (`passwordSet`,
`apiKeySet`).

**The first boot stores the environment's secret, once.** After the key boot
step, a node that holds the signer stores `SMTP_PASSWORD` (or
`RESEND_API_KEY`) of the environment in the default realm's secret store, and
records a key the environment does not set as unset, unless the realm's stored
transport needs it (`SMTP_PASSWORD` for `smtp`): that one stays unrecorded,
and the first boot whose environment sets it stores it. The log says
`realm secret seeded from the environment` at `info`. From then on the stored
value is used, and no later boot reads the key for that realm: each boot warns
`SMTP_PASSWORD only seeds the first realm's mail.smtp.password at its first
boot, and is ignored` while the key is still set. Remove both keys from the
environment once every node runs this release; until then a realm that a node
of the previous release created during the roll still sends with them.

**Other realms get the environment's secret where it is theirs.** The first
boot after the upgrade fills every realm's policies from the environment, the
mail transport included. Each realm whose stored transport is the
environment's and needs a secret it has no row for gets the environment's
value at that boot, or at the first later boot that can encrypt it (a realm
with no data-at-rest key yet is logged and tried again). Nothing is recorded
for a realm whose transport needs nothing.

**`SMTP_PASSWORD` goes only to its own server.** No realm whose stored
`mail.smtp.host`, `port` or `user` differs from `SMTP_HOST`, `SMTP_PORT` and
`SMTP_USER` is given `SMTP_PASSWORD`: the boot logs
`SMTP_PASSWORD is not stored in the realm "..."` as an error instead. Point the
environment at the realm's server, or set the realm's password through a policy
update. For the same reason a policy update that selects `smtp`, or changes
`mail.smtp.host`, `port` or `secure`, must give `mail.smtp.password` again.

**A mail transport that lacks a setting no longer stops the boot.**
`EMAIL_PROVIDER=smtp` without `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER` or
`SMTP_PASSWORD`, or `resend` without `RESEND_API_KEY`, used to refuse to start.
Now the realm's policy update refuses such a transport (422
`unprocessable_content`, with one JSON Pointer per refused field), the boot warns
for each setting or secret the default realm's stored transport lacks
(`the realm "master" cannot send mail: its mail.smtp.host is required ...`), and
a mail through it fails, logging the missing path.

**SMTP needs TLS and a public host (breaking).** A realm's smtp transport now
requires STARTTLS when `mail.smtp.secure` is off, checks the server certificate
against the host name, and connects only to a public address its host resolves
to: never `localhost`, a private, loopback, link-local or unique-local address,
or a cloud metadata address. A policy update that names `localhost` or such an
IP address as `mail.smtp.host` is refused. Only the operator can relax this,
for every realm, with two keys no realm policy can change:

- `SMTP_ALLOW_PLAINTEXT=true` lets a transport send without STARTTLS;
- `SMTP_ALLOWED_HOSTS` lists the hosts (names or IP addresses, comma-separated)
  a realm may name and reach although they are not public. A cloud metadata
  address stays refused.

A deployment that sends through a local plaintext relay, such as Mailpit on
`localhost:1025` or a relay container on a private Docker network, sets both
before it upgrades, for example `SMTP_ALLOW_PLAINTEXT=true` and
`SMTP_ALLOWED_HOSTS=localhost`; otherwise its mail fails, and the log names the
refused host. The boot logs an error for every realm whose stored SMTP host is
`localhost`, a non-public IP address not in `SMTP_ALLOWED_HOSTS` or a cloud
metadata address, or a listed relay that starts in the clear
(`mail.smtp.secure` false) while `SMTP_ALLOW_PLAINTEXT` is off
(`the realm "master" cannot send mail: its mail.smtp.host localhost is
localhost or a non-public address, which needs localhost in SMTP_ALLOWED_HOSTS
...`), and serves on. It resolves no host name: a name that resolves to a
private address is named when a mail connects to it.

**The `From` header carries the sender name.** Mail is now sent from
`EMAIL_FROM_NAME <EMAIL_FROM_ADDRESS>` as the realm stores them (`QAuth
<no-reply@example.com>` by default), where it used to carry the address alone.

The admin API's realm policy update, `realms.policies.update`
([#517](https://github.com/qauth-labs/qauth/issues/517)), changes a realm's mail
transport, sender and password; the environment keys no longer do. It takes
the password only sealed with `secrets.seal`, and with an approval. On a
deployment that runs no admin listener, replace a leaked or rotated
`SMTP_PASSWORD` or `RESEND_API_KEY` of the default realm by setting the new
value in the environment, deleting the realm's row for it, and restarting
every node:

```sql
DELETE FROM realm_secrets
 WHERE name = 'mail.smtp.password' -- or 'mail.resend.apiKey'
   AND realm_id = (SELECT id FROM realms WHERE name = 'master'); -- DEFAULT_REALM_NAME
```

The next boot of a node that holds the signer stores the new value, as at the
first boot. Restart every node, not one: a running node keeps the transport it
built for the realm until the realm's policies change, and deleting the row
changes none of them.

### Redirect URIs the consent screen cannot show

From this release the consent screen always says where the authorization code
goes, by the host of the redirect URI, "this device" for a loopback address,
or the app's own scheme
([#593](https://github.com/qauth-labs/qauth/issues/593)). Every registration
path refuses a redirect URI it cannot show: a host that is not a DNS name of
valid labels (an underscore, an empty label, a label with a hyphen at either
end), an IPv6 address that is not loopback, or a scheme longer than 64
characters. A client stored before the upgrade with such a URI breaks:

- **A CIMD client** whose document lists one no longer resolves once the
  server fetches its document again: the consent screen refuses it, and so does
  the token endpoint, where its next refresh answers `invalid_client`. Its
  owner changes the document; nothing on the server side fixes it.
- **A seed manifest** that names one is refused whole, so running
  `db:seed-oauth-clients` again changes no client until the URI is fixed or
  removed from the manifest.
- **A client registered dynamically, through `/api/clients` or by the
  manifest** keeps working for a user whose stored consent covers the
  request, but the consent screen answers a new user, or one whose request
  needs the screen, with `invalid_request` (400).

Before you upgrade, list the clients that break with the new release's
listing command ([#914](https://github.com/qauth-labs/qauth/issues/914)). It
applies the rule the consent screen applies, so it finds every such URI, and it
reads no column newer than migration 0023, so it runs against the 0.1 database
before the migration runner does. Run it from a checkout of the new release:

```bash
DATABASE_URL=postgresql://qauth:pw@db:5432/qauth \
  pnpm nx run infra-db:db:list-unshowable-redirect-uris
```

It lists the clients per realm (`-- --realm=<realm name>` for one realm), each
with the URIs the screen cannot show, why, and who can replace them. It exits
`0` when there are none and `1` when it lists any; Nx reports every other
failure as `1` too, so a script that must tell them apart runs
`pnpm --dir libs/infra/db exec tsx src/scripts/list-unshowable-redirect-uris.ts`,
which exits `2` on a usage error and `3` when it could not run. After the
upgrade, every boot of a node that serves the consent screen (the `web` role)
also names such clients in a `warn` line (`the client "…" of the realm "…"
has a redirect URI the consent screen cannot show …`), up to 20 of them, and
says when there are more.

Replace each URI with one the client can receive its code on, through the
client's own registration path, the seed manifest or, for a CIMD client, its
document, as the listing says for each client.

### Migration 0047 can meet a client registration in a deadlock

Migration 0047 ([#593](https://github.com/qauth-labs/qauth/issues/593)) adds
`oauth_clients.verified_domain`. The runner applies every pending migration in
one transaction, so when 0046 is in the same run it already holds `realms`
(0046 changes that table) when 0047 locks `oauth_clients`. A node of the
previous release that stores a new client at that moment (dynamic
registration, a CIMD client resolved for the first time, `/api/clients`, the
seeder) takes the two tables in the other order: `oauth_clients` for its
insert, then `realms` for the foreign key check. Postgres then aborts one of
the two with `deadlock detected`. If it aborts the client's request, that one
request fails and the client registers again. If it aborts the runner, the
whole run rolls back, nothing is half-applied, and the runner exits with an
error: run it again. A lock taken at the start of 0047 would not change the
order, since `realms` is held by then. To avoid the retry, run the migration
runner when no client is being registered, such as before the first node of
the new release starts and with open registration quiet.

### The operator provisions the system client

From this release the auth server no longer creates the developer portal's
system client as a secret-based client
([#631](https://github.com/qauth-labs/qauth/issues/631),
[ADR-017](/reference/records/adr/017-first-party-login/) phase F0). The operator
provisions it: a `private_key_jwt` client with the portal's public keys, the
first-party profile `web_redirect` and the portal's callback. Give the
migration runner `SYSTEM_CLIENT_REDIRECT_URI` and one of
`SYSTEM_CLIENT_JWKS_URI` and `SYSTEM_CLIENT_JWKS`, with the auth server's
`SYSTEM_CLIENT_ID` and `DEFAULT_REALM_NAME`, and the run that applies the
migrations provisions it too (see
[The system client](/operate/docker/#the-system-client)). The seed manifest's
`system_client` section does the same. The profile also waives the consent
screen
([#633](https://github.com/qauth-labs/qauth/issues/633), ADR-017 Decision 9):
once provisioned, the system client is issued codes at `/oauth/authorize`
without it, unless a request asks for a dangerous scope or `prompt=consent`,
and each such code is recorded as a
[`consent.administrative`](/reference/events/#consentadministrative-v1-rc0)
event.

Nothing breaks if you do not, yet. An existing system client row is kept as
it is, except that a row without the developer API's audience is given it
(see [the developer portal's token](#the-developer-portals-token-moves-to-the-developer-apis-audience)),
and the portal's sign-in keeps working through it; a realm that has none gets a
placeholder that holds no secret and no key, with that audience. The portal's
move to the redirect flow needs the provisioned row.

Migration 0048 adds `oauth_clients.first_party_profile`,
`first_party_policy` and `first_party_reason`, nullable with no default, and
six CHECKs that every existing row passes. The previous release keeps
creating and updating clients on the new schema.

Remove a client's first-party profile only after every node runs this
release. The removal revokes the client's refresh tokens under a lock that a
token write of this release waits for; a node of the previous release does not
take it, so a refresh token it commits while the profile is removed survives
the removal.

### The delivery role reads `realms.issuer`

From this release the [SSF transmitter](/operate/ssf-transmitter/) names a user
in its SETs under the realm's issuer, so the delivery role reads
`realms.issuer` ([#540](https://github.com/qauth-labs/qauth/issues/540)). A
deployment whose delivery role connects as the server's own database user needs
nothing, nor does one whose migration runner grants the roles' users
([below](#each-role-can-connect-as-a-database-user-of-its-own)). One that runs
it as a database user of its own, with the grants of
`eventDeliveryGrantStatements` from `@qauth-labs/infra-db` applied by hand,
gives that user the new column before the new version starts, by applying those
statements again or with the one statement they add:

```sql
GRANT SELECT ("issuer") ON TABLE "realms" TO <delivery_role>;
```

Nothing checks the grants at boot. Without this one, every SSF delivery
attempt fails with `permission denied for table realms` and is retried until
its attempts run out; the delivery role logs `a delivery route threw`.

### Each role can connect as a database user of its own

A split deployment can now give each service role a Postgres user with only
the grants it needs
([#498](https://github.com/qauth-labs/qauth/issues/498); ADR-019 Decisions 8
and 9). Nothing changes until you name the users: with no `DB_USER_*` variable
set, every role connects as the one user, which owns the tables, as before. To
split them, create the users, name them to the migration runner and give each
role's processes their own `DATABASE_URL`, as
[Topology](/operate/topology/#one-user-per-role) shows. Every runner run then
applies the grants after its migrations, so a later release that adds a table
needs no step of yours.

Migration 0055 adds `ssf_subject_events_pending`, a `SECURITY DEFINER` function
the SSF subject sweep calls instead of reading `events`, so the `api` role's
user holds no `SELECT` on the event store. `EXECUTE` on it is revoked from
`PUBLIC`; the grants give it to `api`. The previous release keeps running on
the new schema: it does not call the function.

A process whose only role is `delivery` no longer runs the default realm's boot
step, which creates and updates the realm row; its user may not write
`realms`. A process of any other role runs it, as before.

### Keep a relying party's `client_credentials` to the scopes it needs

A `client_credentials` token names no user, and until this release the grant
issued any scope of a client's `scopes`. So a relying party given the grant to
manage its [SSF stream](/operate/ssf-transmitter/#register-a-receiver) could
also get a token without a user for each scope its users grant it
([#891](https://github.com/qauth-labs/qauth/issues/891)). Migration 0051 adds
`oauth_clients.client_credentials_scopes`, nullable with no default and a CHECK
every existing row passes: the scopes that grant may issue, out of `scopes`.
NULL, every existing client's value, keeps the grant as it was, and the
previous release keeps creating and updating clients on the new schema.
From 0.2.3, a CIMD client is the exception
([#956](https://github.com/qauth-labs/qauth/issues/956)): without a list, the
grant issues it no token, and its `cimd_clients` entry in the seed manifest
sets the list
([Tokens a CIMD client gets as itself](/operate/docker/#tokens-a-cimd-client-gets-as-itself)).

After the upgrade, give every client that signs users in and holds
`client_credentials` the list, an SSF receiver's `["ssf:stream"]`, in its seed
manifest entry, and set it on the stored row (the seeder writes an existing
client only with `--rotate`, which also issues a new secret). A later
`--rotate` refuses an entry without the list for a client that has one, so the
manifest and the row stay in step.

The list takes effect on a node once that node runs this release. Until every
node does, a node of the previous release, which does not read the column,
still issues every scope of `scopes` on `client_credentials`. Setting the list
during the roll does no harm: such a node's writes to the client, a `--rotate`
of its seeder included, do not name the column and leave the list as it is.

Rolling back to an earlier release without restoring the backup lifts every
list, because its token endpoint ignores the column. The column and its values
are kept, and the lists apply again once the nodes run this release again;
restoring the backup from before the upgrade removes them with the column.

### New passwords meet one password policy

From this release `POST /auth/register` checks a new password against the
realm's password policy
([#634](https://github.com/qauth-labs/qauth/issues/634), ADR-017 Decision 8):
at least `password.minLength` characters after NFC normalisation, 15 by
default; not a common word or password, nor the address or the service's or
realm's name, as a whole; and a zxcvbn score of at least `password.minScore`.
A refused password answers `422` `weak_password` with its `reasons`. Existing
passwords keep working and are not checked again.

`password.minLength` is a new field of the realm policies. The first node of
this release to boot gives every realm that lacks it the seed
`PASSWORD_MIN_LENGTH` (15 when unset), as for any field a release adds. A
value below 8 refuses the boot; a value below 15 boots with a warning naming
`PASSWORD_MIN_LENGTH`, since NIST SP 800-63B-4 allows a shorter minimum only
for a password used within multi-factor authentication.

A password set from this release is hashed in Unicode NFC, and its credential
records `password_normalization: "nfc"` in `credential_data`. During a rolling
upgrade a node of the previous release ignores that member: it verifies the
password as typed. For a password typed already in NFC, which is what keyboards
and input methods produce for nearly all text, that is the same password. A
user whose new password contains a character typed in a decomposed form (an
`e` followed by a combining accent, for example) may be refused by a node of
the previous release until every node runs this release, and after a rollback.
A node of the previous release also still registers passwords under the old
rule (the score floor only) while it runs.

### Passwords on a breach list

From this release a realm can check passwords against a breach list
([#635](https://github.com/qauth-labs/qauth/issues/635), ADR-020 §3). The new
realm policy `password.breachListSource` is `off` in every realm after the
upgrade (the first node of this release gives every realm the seed
`PASSWORD_BREACH_LIST_SOURCE`, `off` when unset), so nothing changes until an
operator turns it on. Set `BREACHED_PASSWORD_LIST_PATH` (a file of SHA-1
digests, 40 hex characters a line, with an optional `:count`, at most
5,000,000 of them) for `local`, or
`BREACHED_PASSWORD_RANGE_URL` (an `https` URL whose path ends with `/`, such
as `https://api.pwnedpasswords.com/range/`) for `k_anonymity`; a private
mirror needs an `EGRESS_ALLOWLIST_PATH` entry naming the realms that use it.
Each node loads the local list at boot and again within 30 seconds of the file
changing (a new modification time, size or inode, so a file renamed into place
counts); a reload that fails keeps the list it had. A longer list does not load:
keep a corpus's most common passwords, not the whole corpus, and give each node
about 20 bytes a digest of memory, three times that while a reload builds the
next list. A realm that names a source the
deployment did not set up gets a failed check on every password, which lets
the sign-in through and is counted and recorded: watch
`qauth_breached_password_checks_total{result="failed"}` after turning a
source on.

Once a realm checks, `POST /auth/register` refuses a password on the list.
At sign-in the list is checked, and a new password asked for, only in the
Interaction API: with `INTERACTION_UI_ENABLED` on, a user whose password is on
the list is asked for a new one at their next sign-in, after a code mailed to
their address (or their second factor). The legacy `/ui/login`, which
`/oauth/authorize` still uses while the switch is off (the default), and
`POST /auth/login` check neither the list nor a pending update until they move
onto the sign-in engine ([#709](https://github.com/qauth-labs/qauth/issues/709)).

Migration 0059 adds the `user_required_actions` table, which holds the
`update_password` action the admin API and the account's "this wasn't me" will
ask for (no route writes it yet). During a rolling upgrade a node of the
previous release neither checks the list nor reads that table, and cannot read
a sign-in that a node of this release has marked for a password update: that
sign-in starts again on the older node and completes as before.

A deployment whose migration runner grants the roles' database users
([above](#each-role-can-connect-as-a-database-user-of-its-own)), or whose roles
connect as the one user that owns the tables, needs nothing. One that applies
the grants of each role's user by hand gives them the new table before the new
version starts, by applying the statements of `databaseUserGrantStatements`
from `@qauth-labs/infra-db` again or with the ones they add:

```sql
GRANT SELECT, INSERT, DELETE ON TABLE "user_required_actions" TO <web_role>;
GRANT SELECT, INSERT ON TABLE "user_required_actions" TO <api_role>, <admin_role>;
```

Nothing checks the grants at boot. Without the `web` one, every password
sign-in through the Interaction API is refused as unavailable, with
`permission denied for table user_required_actions` in the log.

### Password reset and the session epoch

With `INTERACTION_UI_ENABLED` on, the Interaction API's password step offers
the owner's password reset
([#642](https://github.com/qauth-labs/qauth/issues/642)). Migration 0062 adds
the `user_session_epochs` table: one row per user, written by the reset in the
transaction that replaces the password. Every browser session created before a
user's last reset, or within a second after it (the margin for the clocks of
two nodes), is ended at its next use. The auth server caches each user's
epoch in Redis for up to 60 seconds; Postgres stays the source of truth, and a
reset overwrites the cached value at once. The migration adds one table and
changes no row of another, so a node of the previous release keeps working on
the new schema during a rolling upgrade: it neither reads nor writes the table,
and so does not end a session a reset made older until it reaches a node of
this release.

A deployment whose migration runner grants the roles' database users, or whose
roles connect as the one user that owns the tables, needs nothing. One that
applies the grants by hand gives the `web` role's user the new table before the
new version starts:

```sql
GRANT SELECT, INSERT, UPDATE ON TABLE "user_session_epochs" TO <web_role>;
```

Without it, every request that reads a browser session (the authorization
endpoint among them) and every Interaction API sign-in fails, with
`permission denied for table user_session_epochs` in the log.

### Tokens record how the user signed in

From this release the ID token and the access token of a browser sign-in carry
`amr` and `auth_time`, and every refresh keeps both
([#662](https://github.com/qauth-labs/qauth/issues/662)). Migration 0065 adds
three empty columns for them: `authorization_codes.amr`,
`refresh_tokens.auth_time` and `refresh_tokens.amr`. It rewrites no row and
reads neither table: its CHECKs are added `NOT VALID`, because every existing
row is empty in the new columns. It first locks `authorization_codes` and then
`refresh_tokens`, in a redemption's order, so minting a code, redeeming one and
a refresh wait until the runner commits, which takes moments. The migration
sets no `lock_timeout`: run it when no long transaction holds either table.

Tokens issued from what existed before the upgrade carry less, until the user
signs in again:

- A browser session from before the upgrade gives its codes `auth_time` but no
  `amr`.
- A refresh family from before the upgrade, and one a node of the previous
  release refreshes during a rolling upgrade, gives its access tokens neither
  claim.

Both fail closed: a resource server that asks for a recent sign-in, or for a
given method, sends the user to sign in again.

## Upgrading within 1.x

:::caution[Back up first]
Take the backup of [step 1](#1-back-up-the-database) before every upgrade.
Downgrades are not supported, within 1.x or otherwise: restoring the backup is
the only way back.
:::

This section is a stub until 1.0 ships. From 1.0 on, ADR-018 §5 promises:

- An upgrade within 1.x is the three steps above and nothing else: back up, run
  the new version's migration runner, start the new version.
- No 1.x migration is destructive. None drops or renames a table or column,
  narrows a column's type or deletes rows. A change of shape adds the new form
  beside the old one, so the previous version keeps working on the new schema
  while a rolling upgrade replaces its nodes.
- CI tests an upgrade from every earlier 1.x minor release.

That test runs today, before 1.0, from each release listed in
`upgrade-baselines.json` at the repository root. It starts the release, writes
data through its HTTP API, runs this version's migration runner and nothing
else, and starts this version. Then it checks that tokens issued before the
upgrade still introspect, the refresh token rotates, consents and API keys are
still there, and passwords still sign in. It then starts the old release again
on the migrated database and runs the same smoke tests. Until the 1.0 release
candidate, a failure of that last check is reported but does not fail CI.

## History: the migration 0011 runbook (ADR-002)

This runbook predates the migration runner: where it says
`pnpm nx run infra-db:db:migrate` or `drizzle-kit migrate`, run the migration
runner of Step 2 above. A failed migration is reported the same way, by name,
and rolls back.

QAuth's history contains one **destructive** schema migration you must plan
around: migration **0011** (ADR-002, issue [#230]), which permanently drops
`users.email`, `users.email_normalized`, and `users.password_hash`. Skipping
its precondition doesn't just fail the migration — it can **silently** strip
`email`/`email_verified` claims from existing users, including users whose
email was verified, without an error anywhere.

This section restates the runbook from `CHANGELOG.md`'s `[Unreleased]` section
of the time as an ordered procedure. **`CHANGELOG.md` is the source of record** — if the two
disagree, trust the CHANGELOG and the migration files in
`libs/infra/db/drizzle/`, and file an issue against this page.

[#230]: https://github.com/qauth-labs/qauth/issues/230

> **⚠️ No rollback after migration 0011.** Migration 0011 **drops columns**.
> Dropped columns cannot be reconstructed — password hashes are unrecoverable
> by design, and once `users.email` is gone there is no way to get it back
> from inside the database. **A full database backup taken immediately before
> running the migration is the only undo.** Restoring it discards every write
> made after the backup. Take the backup before Step 4 below, not after
> something looks wrong.

### Which path applies to you

| Your current deployment                                                                                                    | Path                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Already running a release at or after the #228/#229 dual-write cutover, not yet past #230 (migration 0011 not yet applied) | **One-hop** — go to [Step 3](#step-3-run-the-backfill-verification)                                                                             |
| Running anything older (pre-#228), or unsure                                                                               | **Two-hop** — go to [Step 1](#step-1-the-two-hop-precondition-pre-229-deployments-only)                                                         |
| A fresh install with no existing users                                                                                     | Migrations apply cleanly with no data to guard; skip to [Step 4](#step-4-back-up-the-database) as a formality, or just run the migration runner |

If you don't know which release you're running, check whether
`pnpm nx run infra-db:db:backfill-identity` exists as a target in your
deployed checkout's `libs/infra/db/project.json`. If it does, you're on the
dual-write release — one-hop. If it doesn't (as on current `main`, see below),
and you haven't already applied migration 0011, you need the two-hop path.

### Step 1: the two-hop precondition (pre-#229 deployments only)

**The backfill tooling has been deleted from the tree.** `db:backfill-identity`
(the nx target, `libs/infra/db/src/scripts/backfill-identity.ts`, and its
implementation under `libs/infra/db/src/lib/backfill/`) was added in #226 and
**removed** in the same commit that added migration 0011
(`29abe4a`, closing #230) — the CHANGELOG entry for that removal reads "#226
backfill machinery retired (git history is the archive...)". Current `main`
has no `db:backfill-identity` target at all — verify with
`pnpm nx show project infra-db --json | grep backfill` against your checkout.

This is what actually **gates** the two-hop path: it is not a runtime guard,
it is that the tool you need has already been deleted from anything at or
after migration 0011. If you're upgrading from before the #228/#229 dual-write
cutover, you cannot get the backfill tool by deploying current `main` — you
must:

1. Deploy a build from the commit range that has the backfill target: at or
   after `62886c9` (#226, "add idempotent ADR-002 identity backfill") and
   before `29abe4a` (#230, "drop legacy users identity columns").

   **Build `00c23f04`** unless you have a reason not to. It is the immediate
   parent of `29abe4a` — the newest state of `main` that still carries the
   backfill tool and migration 0010's dual-write behaviour, and does not yet
   carry migration 0011. Verify what you checked out before deploying it:

   ```bash
   git show 00c23f04:libs/infra/db/project.json | grep backfill-identity   # must match
   git ls-tree 00c23f04 libs/infra/db/drizzle | grep 0011                  # must be EMPTY
   ```

   **No release tag names this commit** — giving the hop a pinnable tag is
   tracked in [#362](https://github.com/qauth-labs/qauth/issues/362). Until
   then a SHA is the only precise instrument available, which is why this page
   gives you one rather than a tag that would be wrong.

   :::danger[`v0.1.0-rc.0` is not a safe starting point]
   The repository's first tag, `v0.1.0-rc.0` (2026-07-25), **postdates**
   migration 0011 and already contains the destructive drop, as every later
   release does. Deploying it as
   the "previous release" of a two-hop upgrade applies 0011 to a database that
   was never backfilled — which is the failure this whole page exists to
   prevent. Confirm for yourself with
   `git ls-tree v0.1.0-rc.0 libs/infra/db/drizzle | grep 0011`.
   :::

2. Run the [Step 3](#step-3-run-the-backfill-verification) backfill against
   that deployment.
3. Only then continue upgrading, release by release, until you reach the
   target release containing migration 0011.

Skip this step entirely if you're already on a release at or after the
dual-write cutover (#228/#229) and haven't applied migration 0011 yet — go
straight to Step 3.

### Step 2: understand the dual-write window (context, no action)

The release between #228 and #230 **dual-writes**: it writes both the legacy
`users.email`/`password_hash` columns and the new `user_credentials` /
`user_attributes` tables in the same transactions, so the two stay in sync.
This is why the CHANGELOG notes that `--refresh` is safe on that release even
though the backfill tool's own `--help` text calls `--refresh`
"PRE-CUTOVER ONLY" — the warning is about running `--refresh` against an
**older**, non-dual-writing release, where it would overwrite already-correct
rows with stale legacy-column data. On the dual-write release itself, the two
sources are equal by construction, so refreshing is a no-op-safe reconciliation.

### Step 3: run the backfill verification

Run this against the dual-write release (#228/#229) — either the one you're
already on (one-hop), or the intermediate one you deployed in Step 1 (two-hop):

```bash
pnpm nx run infra-db:db:backfill-identity -- --refresh
pnpm nx run infra-db:db:backfill-identity -- --verify-only
```

**Both commands must exit `0`.** `--verify-only` confirms every user has a
`(self_reported, email)` `user_attributes` row (among the other identity
rows the backfill populates).

**If `--verify-only` exits non-zero:** do not proceed. Something did not
backfill cleanly — re-run `--refresh` and `--verify-only` again; if it still
fails, this is a data problem to resolve before touching schema, not something
migration 0011's guard will explain further (its guard message is deliberately
terser — see Step 5).

**Why this matters, concretely:** without a clean backfill, existing users —
**including users with a verified email** — silently lose their `email` and
`email_verified` claims on token, refresh, and userinfo responses once you're
past migration 0011. There is no error at request time; the claims are simply
absent, because claim resolution reads exclusively from `user_attributes`
after ADR-002, and nothing populates that table except this backfill (or
normal post-cutover writes). This is the reason this page exists — do not
skip this step because the app "seems to still work" after upgrading. It will
appear to work until a user's client asks for their email.

### Step 4: back up the database

Immediately before running the migration. This is your only undo (see the
warning at the top of this page).

```bash
# Adjust host/container/credentials to your deployment.
docker exec qauth-postgres pg_dump -U qauth -d qauth -F c -f /tmp/qauth-pre-0011.dump
docker cp qauth-postgres:/tmp/qauth-pre-0011.dump ./qauth-pre-0011.dump
```

Confirm the dump file is non-empty and, if you can afford the time, that it
restores cleanly to a scratch database before proceeding.

### Step 5: optional — preflight the migration's own guard

Migration 0011 opens with an in-SQL guard (`libs/infra/db/drizzle/0011_striped_brother_voodoo.sql`)
that runs **before any DDL** in the same file and **aborts the entire
migration atomically** — zero schema changes applied — if it finds:

- any user with a `password_hash` but no matching `user_credentials` row
  (`provider_type = 'password'`), or
- any user with an `email` but no `user_credentials` row at all.

You can run the same two checks yourself first, without touching schema:

```sql
SELECT count(*) FROM users u
WHERE u.password_hash IS NOT NULL
  AND NOT EXISTS (
    SELECT 1 FROM user_credentials uc
    WHERE uc.user_id = u.id AND uc.provider_type = 'password'
  );

SELECT count(*) FROM users u
WHERE u.email IS NOT NULL
  AND NOT EXISTS (
    SELECT 1 FROM user_credentials uc WHERE uc.user_id = u.id
  );
```

Both should return `0`. If either doesn't, **stop** — go back to Step 3; the
migration will abort with the same finding, but finding it here costs you
nothing (this is a read-only `SELECT`, not a migration attempt).

If the guard fires anyway when you run the real migration, the error message
names the count of affected users on each side and tells you to re-run the
Step 3 backfill runbook. **No data is modified when the guard fires** — the
whole file rolls back (drizzle-kit runs each migration file in a transaction),
so it's safe to fix the underlying data and simply retry.

### Step 6: apply migration 0011, before starting the new release

```bash
pnpm nx run infra-db:db:migrate
```

**Ordering matters and is asymmetric.** Apply this migration **before**
starting any instance of the release that expects it — the new binary writes
only the ADR-002 tables (`user_credentials` / `user_attributes`), not the
legacy columns, so an old-schema database fed new-binary traffic accumulates
writes the still-there legacy columns won't reflect. Unlike the direction
above (guarded by migration 0011's own precheck), **this direction has no
in-SQL guard** — nothing stops you from starting the new binary against an
unmigrated database. Sequence your rollout so the migration completes first.

**What you'll see on success:** the migration applies, in this order (reading
straight from `0011_striped_brother_voodoo.sql`):

- `email_verification_tokens` drops its `email_verification_tokens_user_id_users_id_fk`
  foreign-key constraint (the column it references is dropped last, below).
- Four indexes on the legacy columns are dropped:
  `idx_users_realm_email_normalized_unique`, `idx_users_email`,
  `idx_users_realm_email_enabled`, `idx_email_verification_tokens_user_id`.
- `email_verification_tokens.credential_id` is promoted to `NOT NULL`.
- `users.email` is dropped.
- `users.email_normalized` is dropped.
- `users.password_hash` is dropped.
- `email_verification_tokens.user_id` is dropped.

Plus a `NOTICE` if any in-flight email-verification tokens were deleted — see
[Step 7](#step-7-minor-operational-consequences-to-expect) below.

**What you'll see on the guard firing:** a `RAISE EXCEPTION` naming the two
counts above and telling you to deploy the backfill release and re-run
Step 3. `drizzle-kit migrate` reports this as a failed migration; nothing was
applied. Go fix Step 3, then re-run this step.

### Step 7: minor operational consequences to expect

Neither of these blocks the migration; both are one-time and self-healing:

- **In-flight email-verification tokens.** Migration 0011 first re-points any
  verification token minted without a `credential_id` at the user's password
  credential (an idempotent re-run of the #228 backfill), then deletes
  whatever remains unresolvable. An affected user's outstanding verification
  link stops working; they click "resend" once and get a new one. Nothing to
  action operationally — just don't be surprised by a small number of deleted
  rows in the migration's `NOTICE` output.
- **Normalized-case email in old UI strings.** For accounts created before
  #228, a few user-visible strings (the register response, the consent-screen
  address, log lines) switch from the original-case email to its normalized
  lowercase form, because the original-case string lived in the now-dropped
  `users.email` column and only the normalized form survives in
  `user_credentials`. Cosmetic only — sign-in and claim resolution are
  unaffected (email matching was always case-insensitive).

### Step 8: migration 0012 (no precondition, any time after 0011)

A later migration drops two more columns —
`users.email_verified` / `users.email_verified_at`
(`libs/infra/db/drizzle/0012_flat_morlocks.sql`) — but **needs no guard and no
special ordering**. They've had no writers since migration 0011 (verified
state has lived in `user_credentials.credential_data.email_verified` /
`user_attributes.verified` since then), and their one sanctioned reader was a
literal default value, not a real read. Apply it whenever you apply the rest
of that release's migrations — nothing to sequence around.

### Verify after applying 0011

- `pnpm nx run infra-db:db:migrate` exits 0 and the migration log shows 0011
  (and 0012, if applicable) applied.
- Log in as an existing user with a previously-verified email, through a
  client granted the `email` scope, and confirm `email`/`email_verified` are
  present in the ID token, the userinfo response and the access token — this is
  the concrete symptom of a skipped backfill, so check it explicitly rather than
  assuming Step 3 worked. Without the `email` scope all three omit the claims
  by design.
- Spot-check a user created before #228 for the normalized-email cosmetic
  change (Step 7) so it doesn't get reported as a bug later.

## See also

- [Docker](/operate/docker/) — the `migration-runner` service; its
  Troubleshooting section points back here for a migration 0011 failure.
- [Configuration](/operate/configuration/) — `DB_MIGRATION_WAIT_MS`, the auth
  server's wait for missing migrations at boot.
- [Keys](/operate/keys/) — the key store and the KEK that the upgrade to 0.2
  moves the key variables into.
- [Topology](/operate/topology/) — the hosts, roles and proxy rules a 0.2
  deployment follows.

---

# Configuration

URL: https://docs.qauth.dev/operate/configuration/

<!-- Generated from libs/server/config/src/lib/registry by its tests. Do not edit by hand: change the registry and run `pnpm nx test docs-checks -- -u`. -->

QAuth reads its configuration from environment variables. This page lists every QAuth key the auth server and the developer portal read, generated from the configuration key registry in `libs/server/config/src/lib/registry/`. A test fails when the page, the registry and the env schemas disagree. Variables of the Node.js runtime itself, such as `UV_THREADPOOL_SIZE`, are not listed.

## Stability tiers

Every key has a tier, which says how it may change ([ADR-018 §5](/reference/records/adr/018-1-0-scope-and-stability/)).

- **Stable** keys follow the deprecation policy. A deprecation is announced in a minor release; the old name or behaviour keeps working, with a warning at boot, for at least 12 months, and it is removed only in a new major release.
- **Advanced** keys may change in a minor release. Read the release notes before you upgrade a deployment that sets one.
- **Experimental** keys may change at any time, without a deprecation window. The server logs a warning at boot for each experimental key that is set, and for each key set to an experimental value. A key or value that switches on an [experimental feature](/reference/experimental-features/) warns through that feature instead, once the feature is on.

## Roles

Every key has a role, which says who owns its value ([ADR-019 Decision 10](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)).

- **deployment**: the environment owns the value, for the whole deployment.
- **realm-seed**: a realm policy, which the realm row owns. The key seeds a new realm, and a realm that had no policies at its first boot after the upgrade that put them on the row; a later change of the key changes no existing realm. Until the server reads the policy from the realm row, it still applies the key to every realm, unless its description says it reads the realm row. The Role column names the policy the key seeds.

A key marked **Secret** holds a credential. This page never shows its value, not even as a default, and neither does the boot log.

## Stable keys

### Server

| Key                  | Role       | Default                                                                   | Since | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------- | ---------- | ------------------------------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ADMIN_API_BASE_URL` | deployment | unset                                                                     | 0.2.0 | The URL clients call the admin API's listener at, such as `https://admin.auth.example.com`, with a path when a proxy serves the listener under one and strips it; every admin call carries a DPoP proof whose `htu` must be this URL followed by the request's path, never a URL taken from the request, and a process that runs the listener refuses to start without it; in production it must be `https` (terminate TLS in front of the listener), unless both it and `ADMIN_API_HOST` name loopback. |
| `ADMIN_API_ENABLED`  | deployment | `false`                                                                   | 0.2.0 | Run the admin API on its own internal listener, on a process whose `SERVICE_ROLES` holds `admin`, off by default; it needs `DPOP_ENABLED` and `ADMIN_API_BASE_URL`, since every admin call carries a DPoP-bound admin token; `false` serves no admin API on this process, and the public listener never serves it.                                                                                                                                                                                       |
| `ADMIN_API_HOST`     | deployment | `127.0.0.1`                                                               | 0.2.0 | The address the admin API's listener binds to, loopback by default; the listener grants nothing for a caller's network position, so every call but the one for its OpenAPI document needs a DPoP-bound admin token and a proof made with its key.                                                                                                                                                                                                                                                        |
| `ADMIN_API_PORT`     | deployment | `3002`                                                                    | 0.2.0 | The TCP port the admin API's listener binds to; it must differ from `PORT`.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `CORS_ORIGIN`        | deployment | none in `production`, so cross-origin requests are refused; `*` otherwise | 0.1.0 | The origins, comma-separated, allowed to call the server cross-origin, such as a browser-based client's origin for its calls to the token endpoint; the authorization endpoint and the other sign-in and consent pages answer no CORS, whatever it holds.                                                                                                                                                                                                                                                |
| `ENABLE_SWAGGER`     | deployment | `true`, or `false` when `NODE_ENV=production`                             | 0.1.0 | Serve the Swagger UI at `/docs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `HOST`               | deployment | `0.0.0.0`                                                                 | 0.1.0 | The address the auth server listens on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `NODE_ENV`           | deployment | `development`                                                             | 0.1.0 | The runtime mode, `development`, `test` or `production`; `production` turns on the strict boot checks, such as refusing the development session secret.                                                                                                                                                                                                                                                                                                                                                  |
| `PORT`               | deployment | `3000`                                                                    | 0.1.0 | The TCP port the auth server listens on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `SERVICE_ROLES`      | deployment | `all`                                                                     | 0.2.0 | The roles this process runs, `all` or a comma-separated list of `web` (the browser-session endpoints), `api` (the token, discovery, account and developer endpoints), `admin`, `signer` (the KEK and every private key) and `delivery` (event delivery); each role registers only its own routes, plugins and jobs, and a process without `signer` refuses to boot when it finds a KEK or a private key variable.                                                                                        |
| `TRUST_PROXY`        | deployment | `false`                                                                   | 0.1.0 | The reverse proxies whose `X-Forwarded-For` hops set the client address and whose `X-Forwarded-Host` names the realm host, as a comma-separated list of addresses, CIDR ranges or `loopback`, `linklocal` and `uniquelocal`; `true` and a hop count are refused.                                                                                                                                                                                                                                         |

### Logs and metrics

| Key               | Role       | Default | Since | Description                                                                                                                                                 |
| ----------------- | ---------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LOG_LEVEL`       | deployment | `info`  | 0.1.0 | The lowest level the server logs: `fatal`, `error`, `warn`, `info`, `debug` or `trace`.                                                                     |
| `METRICS_ENABLED` | deployment | `true`  | 0.1.0 | Serve Prometheus metrics at `GET /internal/metrics` on the internal listener, never on the public one; the listener runs on every process while this is on. |

### Events

| Key                          | Role                                   | Default | Since | Description                                                                                                                                                                                                                        |
| ---------------------------- | -------------------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EVENT_RETENTION_ADMIN_DAYS` | realm-seed: `retention.adminEventDays` | `365`   | 0.2.0 | The days a new realm keeps its admin events, at least 90, before the retention job deletes the oldest of them; it seeds the realm row, so a later change leaves existing realms' retention as it is.                               |
| `EVENT_RETENTION_USER_DAYS`  | realm-seed: `retention.userEventDays`  | `90`    | 0.2.0 | The days a new realm keeps its user events before the retention job deletes them, once every enabled delivery destination has finished them; it seeds the realm row, so a later change leaves existing realms' retention as it is. |

### Database and Redis

| Key              | Role       | Default     | Since | Description                                                                                                          |
| ---------------- | ---------- | ----------- | ----- | -------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL`   | deployment | required    | 0.1.0 | The Postgres connection URL, credentials included. Secret.                                                           |
| `REDIS_DB`       | deployment | `0`         | 0.1.0 | The Redis database number, used when `REDIS_URL` is unset.                                                           |
| `REDIS_HOST`     | deployment | `localhost` | 0.1.0 | The Redis host, used when `REDIS_URL` is unset.                                                                      |
| `REDIS_PASSWORD` | deployment | unset       | 0.1.0 | The Redis password, used when `REDIS_URL` is unset. Secret.                                                          |
| `REDIS_PORT`     | deployment | `6379`      | 0.1.0 | The Redis port, used when `REDIS_URL` is unset.                                                                      |
| `REDIS_URL`      | deployment | unset       | 0.1.0 | The Redis connection URL; when set, `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD` and `REDIS_DB` are ignored. Secret. |

### Realms

| Key                            | Role       | Default  | Since | Description                                                                                                                                                                                                                                                                                                                     |
| ------------------------------ | ---------- | -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DEFAULT_REALM_ENDPOINT_HOSTS` | deployment | empty    | 0.2.0 | Host names, comma-separated, that server-side callers reach the default realm by, such as `auth-server` from the developer portal's `AUTH_SERVER_URL`; each missing one is added as an endpoint host at boot and none is ever removed; an endpoint host answers the API routes and refuses the browser-session routes with 421. |
| `DEFAULT_REALM_NAME`           | deployment | `master` | 0.1.0 | The name of the default realm, a single-realm setting with `JWT_ISSUER`: the server creates the realm at boot when it is missing, and in simple mode it is also the operator realm.                                                                                                                                             |

### Tokens

| Key                         | Role                                                       | Default  | Since | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------- | ---------------------------------------------------------- | -------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACCESS_TOKEN_LIFESPAN`     | realm-seed: `tokens.accessTokenLifespanSeconds`            | `900`    | 0.1.0 | The access token lifetime, in seconds, at most 86400 (a day), for `staging` and `production` clients, and the lifetime of every ID token, that seeds `tokens.accessTokenLifespanSeconds` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again).                                                                                                                                                                                                                                                                                                                                                                 |
| `DEV_ACCESS_TOKEN_LIFESPAN` | realm-seed: `tokens.developmentAccessTokenLifespanSeconds` | `28800`  | 0.1.0 | The access token lifetime, in seconds, at most 86400 (a day), for `development` clients only, that seeds `tokens.developmentAccessTokenLifespanSeconds` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again).                                                                                                                                                                                                                                                                                                                                                                                                  |
| `JWT_ISSUER`                | deployment                                                 | required | 0.1.0 | The default realm's issuer URL and the `iss` of its tokens, a single-realm setting with `DEFAULT_REALM_NAME`: at first boot it becomes the default realm's issuer, without a trailing slash, and its host the realm's permanent primary host; a request for a host that no realm has gets 421.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `REFRESH_TOKEN_LIFESPAN`    | realm-seed: `tokens.refreshTokenLifespanSeconds`           | `604800` | 0.1.0 | The lifetime, in seconds, at most 7776000 (90 days), of a new or rotated refresh token, that seeds `tokens.refreshTokenLifespanSeconds` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again); a rotated token gets the lifetime from the refresh, except a browser-based client's (a public client with an `https` redirect URI), which expires no later than the token it replaces, so the client's family ends with its first token (RFC 10017 §6.3.2.3), while confidential clients and native apps, whose every redirect URI is a loopback or private-use scheme one, keep the lifetime from each refresh. |

### Signing

| Key                      | Role       | Default   | Since | Description                                                                                                                                                                                                                       |
| ------------------------ | ---------- | --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HYBRID_SIGNING_ENABLED` | deployment | `false`   | 0.1.0 | Turn on hybrid Ed25519 and ML-DSA-65 signing, which requires `SIGNING_ALGORITHM_MODE=ed25519+ml-dsa-65`; the realm's key store holds the pair, and a realm whose active Ed25519 token key has no ML-DSA-65 half refuses to start. |
| `SIGNING_ALGORITHM_MODE` | deployment | `ed25519` | 0.1.0 | Which signature algorithms are enabled: `ed25519`, or `ed25519+ml-dsa-65` to add ML-DSA-65.                                                                                                                                       |

### Keys and secrets

| Key                 | Role       | Default                                                                            | Since | Description                                                                                                                                                                                                      |
| ------------------- | ---------- | ---------------------------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KEK`               | deployment | a published development KEK outside production; refused when `NODE_ENV=production` | 0.2.0 | The KEK of the `local` provider, as the base64 of 32 random bytes, for example from `openssl rand -base64 32`; the boot stops when a key variable must be imported into the key store and no KEK is set. Secret. |
| `KEK_PATH`          | deployment | unset                                                                              | 0.2.0 | A file holding the KEK as base64; it takes precedence over `KEK`, and the server warns when group or others can read or write it.                                                                                |
| `KEK_PREVIOUS`      | deployment | unset                                                                              | 0.2.0 | The KEK in use before a KEK rotation, as base64; keys wrapped under it still open until they are re-wrapped. Secret.                                                                                             |
| `KEK_PREVIOUS_PATH` | deployment | unset                                                                              | 0.2.0 | A file holding the previous KEK as base64; it takes precedence over `KEK_PREVIOUS`.                                                                                                                              |
| `KEK_PROVIDER`      | deployment | `local`                                                                            | 0.2.0 | Which provider holds the key-encryption key (KEK) that wraps every stored key: `local` reads it from `KEK` or `KEK_PATH`, and any other name loads the optional package `@qauth-labs/keys-<name>`.               |

### Accounts and passwords

| Key                             | Role                                          | Default | Since | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------- | --------------------------------------------- | ------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ALLOW_SIGN_UP`                 | realm-seed: `accounts.allowSignUp`            | `false` | 0.2.0 | Whether a person may create a new account through the hosted sign-in (an upstream identity that no account holds yet, and a password registration a client starts with `prompt=create` while its operator-set `hosted_flows` name `register`, create one only while this is on, and since 0.2.1 the legacy `POST /auth/register` answers 403 while it is off), that seeds `accounts.allowSignUp` of a new realm, and of a realm whose stored policies lack it at the first boot of the release that added it; once the realm has it, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is.                                                                                                                                                                                                                |
| `FAILED_LOGIN_LOCKOUT_DURATION` | realm-seed: `bruteForce.lockoutSeconds`       | `900`   | 0.1.0 | How long, in seconds, a locked-out identifier is refused before any credential check, at most 86400 (a day), that seeds `bruteForce.lockoutSeconds` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again).                                                                                                                                                                                                                                                                                                          |
| `FAILED_LOGIN_MAX_ATTEMPTS`     | realm-seed: `bruteForce.maxAttempts`          | `5`     | 0.1.0 | How many failed logins for one identifier, inside the window, start a lockout, that seeds `bruteForce.maxAttempts` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again).                                                                                                                                                                                                                                                                                                                                           |
| `FAILED_LOGIN_TRACKING_ENABLED` | realm-seed: `bruteForce.enabled`              | `true`  | 0.1.0 | Lock an identifier out after repeated failed logins (with it off, failed logins are only logged), that seeds `bruteForce.enabled` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again).                                                                                                                                                                                                                                                                                                                            |
| `FAILED_LOGIN_WINDOW`           | realm-seed: `bruteForce.windowSeconds`        | `900`   | 0.1.0 | The window, in seconds, over which failed logins are counted, at most 86400 (a day), that seeds `bruteForce.windowSeconds` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again).                                                                                                                                                                                                                                                                                                                                   |
| `PASSWORD_BREACH_LIST_SOURCE`   | realm-seed: `password.breachListSource`       | `off`   | 0.2.0 | Which breach list new and presented passwords are checked against: `off`, `local` (the list at `BREACHED_PASSWORD_LIST_PATH`) or `k_anonymity` (the range lookup at `BREACHED_PASSWORD_RANGE_URL`, which sends only the first five hex characters of the password's SHA-1), where a check that fails never blocks a sign-in, that seeds `password.breachListSource` of a new realm, and of a realm whose stored policies lack it at the first boot of the release that added it; once the realm has it, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is.                                                                                                                                                                                                                                             |
| `PASSWORD_MIN_LENGTH`           | realm-seed: `password.minLength`              | `15`    | 0.2.0 | The fewest characters (Unicode code points, after NFC normalisation) a new password must have, from 8 to 64 (below 8 fails the boot, and below 15 boots with a warning, since NIST SP 800-63B-4 allows a shorter minimum only for a password used within multi-factor authentication), that seeds `password.minLength` of a new realm, and of a realm whose stored policies lack it at the first boot of the release that added it; once the realm has it, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is.                                                                                                                                                                                                                                                                                          |
| `PASSWORD_MIN_SCORE`            | realm-seed: `password.minScore`               | `2`     | 0.1.0 | The strength score, from 0 (very weak) to 4 (strong), a new password must reach, that seeds `password.minScore` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again).                                                                                                                                                                                                                                                                                                                                              |
| `REQUIRE_VERIFIED_ACCOUNT`      | realm-seed: `accounts.requireVerifiedAccount` | `true`  | 0.1.0 | Refuse a password login on the legacy login routes (`POST /auth/login`, `POST /ui/login`), with the same answer as a wrong password, until the account is verified (for a password account, by its confirmed email address); a sign-in through the Interaction API verifies an unverified account inline with an emailed code after its password instead, whatever this says; it seeds `accounts.requireVerifiedAccount` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again). Old name: `REQUIRE_EMAIL_VERIFIED`. |

### Mail

| Key                                                | Role                                                | Default  | Since | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------- | --------------------------------------------------- | -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `EMAIL_FROM_ADDRESS`                               | realm-seed: `mail.fromAddress`                      | required | 0.1.0 | The sender address of the mail QAuth sends, that seeds `mail.fromAddress` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, its mail reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade sends with this key until a node of this release boots again).                                                                                                                                                                          |
| `EMAIL_FROM_NAME`                                  | realm-seed: `mail.fromName`                         | `QAuth`  | 0.1.0 | The sender name of the mail QAuth sends, in its `From` header, that seeds `mail.fromName` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, its mail reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade sends with this key until a node of this release boots again).                                                                                                                                                          |
| `EMAIL_PROVIDER`                                   | realm-seed: `mail.provider`                         | `mock`   | 0.1.0 | How mail is sent: `mock`, which delivers nothing, `resend` or `smtp`, that seeds `mail.provider` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, its mail reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade sends with this key until a node of this release boots again).                                                                                                                                                   |
| `EMAIL_VERIFICATION_INVALIDATE_EXISTING_ON_RESEND` | realm-seed: `mail.invalidateExistingTokensOnResend` | `true`   | 0.1.0 | When a new verification link is sent, invalidate the earlier ones, so only the latest works.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `EMAIL_VERIFICATION_TOKEN_EXPIRY`                  | realm-seed: `mail.verificationTokenExpirySeconds`   | `86400`  | 0.1.0 | How long, in seconds, an email verification link stays valid; at least 3600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `RESEND_API_KEY`                                   | realm-seed: `mail.resend.apiKey`                    | unset    | 0.1.0 | The Resend API key, for `EMAIL_PROVIDER=resend`, that seeds `mail.resend.apiKey` once: the first boot that can encrypt it stores it, encrypted with the realm's data-at-rest key, in the first realm and in each realm whose stored transport is `resend` with no API key yet; no later boot reads it for a realm that has one, so change it through the realm's policies (a realm a node of the previous release created during a rolling upgrade sends with this key until a node of this release boots again), and remove it once every node runs a release that stores it. Secret.                                                                 |
| `SMTP_ALLOWED_HOSTS`                               | deployment                                          | unset    | 0.2.0 | Comma-separated SMTP hosts (names or IP addresses, matched exactly) that a realm's smtp transport may name and reach although they are not public, such as `localhost`, a private, loopback, link-local or unique-local address, or a name that resolves to one; unset, a policy update refuses such a `mail.smtp.host` and every connection goes only to a public address the host resolves to, and a cloud metadata address is never reachable either way.                                                                                                                                                                                           |
| `SMTP_ALLOW_PLAINTEXT`                             | deployment                                          | `false`  | 0.2.0 | Let a realm's smtp transport whose `mail.smtp.secure` is off send over a connection the SMTP server does not upgrade with STARTTLS, such as a local relay; off, such a transport requires STARTTLS, with the certificate checked, and only the operator sets it, since no realm policy can turn it on.                                                                                                                                                                                                                                                                                                                                                 |
| `SMTP_HOST`                                        | realm-seed: `mail.smtp.host`                        | unset    | 0.1.0 | The SMTP server host, for `EMAIL_PROVIDER=smtp`, that seeds `mail.smtp.host` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, its mail reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade sends with this key until a node of this release boots again).                                                                                                                                                                       |
| `SMTP_PASSWORD`                                    | realm-seed: `mail.smtp.password`                    | unset    | 0.1.0 | The SMTP password, that seeds `mail.smtp.password` once: the first boot that can encrypt it stores it, encrypted with the realm's data-at-rest key, in the first realm and in each realm whose stored smtp server and user are `SMTP_HOST`, `SMTP_PORT` and `SMTP_USER` and that has no password yet, and in no realm whose server is another; no later boot reads it for a realm that has one, so change it through the realm's policies (a realm a node of the previous release created during a rolling upgrade sends with this key until a node of this release boots again), and remove it once every node runs a release that stores it. Secret. |
| `SMTP_PORT`                                        | realm-seed: `mail.smtp.port`                        | unset    | 0.1.0 | The SMTP server port, for `EMAIL_PROVIDER=smtp`, that seeds `mail.smtp.port` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, its mail reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade sends with this key until a node of this release boots again).                                                                                                                                                                       |
| `SMTP_SECURE`                                      | realm-seed: `mail.smtp.secure`                      | `true`   | 0.1.0 | Connect to the SMTP server over TLS, that seeds `mail.smtp.secure` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, its mail reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade sends with this key until a node of this release boots again).                                                                                                                                                                                 |
| `SMTP_USER`                                        | realm-seed: `mail.smtp.user`                        | unset    | 0.1.0 | The SMTP user name, that seeds `mail.smtp.user` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, its mail reads the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade sends with this key until a node of this release boots again).                                                                                                                                                                                                    |

### Client registration

| Key                                   | Role                                                        | Default                               | Since | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------- | ----------------------------------------------------------- | ------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CIMD_ENABLED`                        | realm-seed: `registration.cimd.enabled`                     | `true`                                | 0.1.0 | Whether an HTTPS URL is accepted as a `client_id`, its Client ID Metadata Document fetched on demand, that seeds `registration.cimd.enabled` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, client resolution and discovery read the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again).                                                                                                       |
| `CIMD_TRUSTED_DOMAINS`                | realm-seed: `registration.cimd.trustedDomains`              | empty                                 | 0.1.0 | The hosts the `allowlist` trust policy accepts, separated by spaces or commas, where a leading `*.` matches subdomains, that seeds `registration.cimd.trustedDomains` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, client resolution and discovery read the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again).                                                                              |
| `CIMD_TRUST_POLICY`                   | realm-seed: `registration.cimd.trustPolicy`                 | `accept-any-https`                    | 0.1.0 | Which hosts a Client ID Metadata Document may come from, `accept-any-https` or `allowlist` for the trusted domains only, that seeds `registration.cimd.trustPolicy` of a new realm, and of a realm that had no policies at the first boot after the upgrade that put them on the row; once the realm has its policies, client resolution and discovery read the realm row's value, never this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade runs on this key until a node of this release boots again).                                                                                |
| `DEFAULT_DYNAMIC_REGISTRATION_SCOPES` | realm-seed: `registration.dynamicRegistrationAllowedScopes` | `openid profile email offline_access` | 0.1.0 | The scopes, separated by spaces or commas, that seed the dynamic registration allowlist of a new realm, and of a realm whose row held none at the first boot after the upgrade that put the policies on the row; once the realm has its policies, the server caps a registration with the realm row's list, never with this key, so a later change leaves every such realm as it is (a realm a node of the previous release created during a rolling upgrade has none until a node of this release boots again, and until then an empty list in its row reads as this key), and boot refuses a scope in the `qauth:` namespace, which is reserved for QAuth's own scopes. |
| `REDIRECT_URI_CUSTOM_SCHEMES`         | realm-seed: `registration.redirectUriCustomSchemes`         | empty                                 | 0.1.3 | Schemes without a period that a redirect URI may use besides `https`, loopback `http` and reverse-domain schemes, separated by spaces or commas, such as `cursor`; boot refuses one a browser or the operating system acts on, such as `javascript`.                                                                                                                                                                                                                                                                                                                                                                                                                      |

### Enterprise-managed authorization (ID-JAG)

| Key                      | Role       | Default | Since | Description                                                                                                                                                |
| ------------------------ | ---------- | ------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ID_JAG_ENABLED`         | deployment | `false` | 0.1.0 | Turn on the Identity Assertion Authorization Grant: accepting ID-JAG assertions at the token endpoint and minting them by token exchange.                  |
| `ID_JAG_TRUSTED_ISSUERS` | deployment | empty   | 0.1.0 | The exact issuer identifiers of the enterprise identity providers whose ID-JAG assertions are accepted, separated by spaces or commas; empty accepts none. |

### Wallet federation

| Key                         | Role       | Default | Since | Description                                                                                                                                                                                                   |
| --------------------------- | ---------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OID4VP_VERIFIER_PROFILE`   | deployment | unset   | 0.1.0 | The verifier profile wallet sign-in runs under, `haip-1.0` or `oid4vp-1.0-base`, with no default: with wallet sign-in on and no profile, the server refuses to start. Experimental values: `oid4vp-1.0-base`. |
| `WALLET_FEDERATION_ENABLED` | deployment | `false` | 0.1.0 | Turn on wallet sign-in with OpenID for Verifiable Presentations, which also requires `OID4VP_VERIFIER_PROFILE`.                                                                                               |

## Advanced keys

### Server

| Key                      | Role       | Default     | Since | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------ | ---------- | ----------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EGRESS_ALLOWLIST_PATH`  | deployment | unset       | 0.2.0 | A JSON file of hosts and address ranges, each for the realms it lists, that outbound calls to destinations the operator or a realm admin set may reach although they are not public; read once at boot, and never applied to a destination that a client, an end user or a fetched document supplies.                                                                                                                                                                                                                                                                                                                                  |
| `INTERNAL_HOST`          | deployment | `127.0.0.1` | 0.2.0 | The address the internal listener binds to, loopback by default; the listener runs on a process whose `SERVICE_ROLES` holds `signer` but not every role, for the other roles' calls to the signer service, and on every process while `METRICS_ENABLED` is on, for the metrics scraper (`GET /internal/metrics`), and serves mutual TLS only, except on a single process without the internal TLS files, where it serves plain HTTP on a loopback address only.                                                                                                                                                                        |
| `INTERNAL_PEER_ROLES`    | deployment | unset       | 0.2.0 | A JSON object from a subject alternative name of a peer's certificate, a URI such as a SPIFFE ID or a DNS name, to the service role the peer calls the internal listener as, or to `metrics` for a metrics scraper, which may read `GET /internal/metrics` only, such as `{"spiffe://example.org/qauth/web":"web","spiffe://example.org/prometheus":"metrics"}`; the listener answers `403` to a peer whose certificate names no SAN here, and to one whose role a route's module does not admit; `signer` is refused, as the signer never calls as a peer, and with the internal TLS files the listener refuses to start without one. |
| `INTERNAL_PORT`          | deployment | `3443`      | 0.2.0 | The TCP port the internal listener binds to; it must differ from `PORT` and from `ADMIN_API_PORT` where the admin API's listener runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `INTERNAL_TLS_CA_PATH`   | deployment | unset       | 0.2.0 | A PEM file with the CA certificates that issue internal peers' certificates, which the internal listener requires of every client and reloads when the file changes; a file that holds a public root CA, such as a system bundle, is refused; required where `SIGNER_URL` is, and where the internal listener runs while the roles are split.                                                                                                                                                                                                                                                                                          |
| `INTERNAL_TLS_CERT_PATH` | deployment | unset       | 0.2.0 | A PEM file with this process's certificate for internal traffic over mutual TLS: the one it presents on calls to the signer service, and the one its internal listener serves, which the listener reloads when the file changes; required where `SIGNER_URL` is, and where the internal listener runs while the roles are split.                                                                                                                                                                                                                                                                                                       |
| `INTERNAL_TLS_KEY_PATH`  | deployment | unset       | 0.2.0 | A PEM file with the private key of `INTERNAL_TLS_CERT_PATH`, reloaded with it; required where `SIGNER_URL` is, and where the internal listener runs while the roles are split.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `REQUEST_TIMEOUT_MS`     | deployment | `60000`     | 0.1.0 | How long, in milliseconds, a client may take to send one complete request before the server answers `408`; at least 1000.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `SECURITY_HSTS_ENABLED`  | deployment | `true`      | 0.1.0 | Send the `Strict-Transport-Security` header; keep it on in production.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `SECURITY_HSTS_MAX_AGE`  | deployment | `31536000`  | 0.1.0 | The `max-age`, in seconds, of the `Strict-Transport-Security` header.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

### Logs and metrics

| Key                                          | Role       | Default                                                           | Since | Description                                                                                                                                                                                 |
| -------------------------------------------- | ---------- | ----------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LOG_PRETTY`                                 | deployment | `false`                                                           | 0.1.0 | Write human-readable, coloured logs instead of JSON, for local development.                                                                                                                 |
| `OTEL_EVENTS_ENABLED`                        | deployment | `false`                                                           | 0.2.0 | Send every event as an OpenTelemetry log record to the collector the `OTEL_EXPORTER_OTLP_*` keys name, as telemetry without a delivery guarantee; only then are those keys checked at boot. |
| `OTEL_EXPORTER_OTLP_CERTIFICATE`             | deployment | Node's own CA certificates                                        | 0.2.0 | A PEM file of the CA certificates that verify the collector's TLS certificate.                                                                                                              |
| `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`      | deployment | unset                                                             | 0.2.0 | A PEM file of the client certificate chain, for a collector that asks for mutual TLS.                                                                                                       |
| `OTEL_EXPORTER_OTLP_CLIENT_KEY`              | deployment | unset                                                             | 0.2.0 | A PEM file of the client certificate's private key, for a collector that asks for mutual TLS.                                                                                               |
| `OTEL_EXPORTER_OTLP_COMPRESSION`             | deployment | `none`, the OpenTelemetry default                                 | 0.2.0 | How export requests are compressed, `gzip` or `none`.                                                                                                                                       |
| `OTEL_EXPORTER_OTLP_ENDPOINT`                | deployment | `http://localhost:4318`, the OpenTelemetry default                | 0.2.0 | The collector's OTLP/HTTP base URL, to which `/v1/logs` is appended.                                                                                                                        |
| `OTEL_EXPORTER_OTLP_HEADERS`                 | deployment | unset                                                             | 0.2.0 | Headers sent with every export, such as the collector's API key, as URL-encoded `name=value` pairs, comma-separated. Secret.                                                                |
| `OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE`        | deployment | `OTEL_EXPORTER_OTLP_CERTIFICATE`, else Node's own CA certificates | 0.2.0 | The CA certificate file for event exports, in place of `OTEL_EXPORTER_OTLP_CERTIFICATE`.                                                                                                    |
| `OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE` | deployment | `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, else none                | 0.2.0 | The client certificate file for event exports, in place of `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`.                                                                                         |
| `OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY`         | deployment | `OTEL_EXPORTER_OTLP_CLIENT_KEY`, else none                        | 0.2.0 | The client key file for event exports, in place of `OTEL_EXPORTER_OTLP_CLIENT_KEY`.                                                                                                         |
| `OTEL_EXPORTER_OTLP_LOGS_COMPRESSION`        | deployment | `OTEL_EXPORTER_OTLP_COMPRESSION`, else `none`                     | 0.2.0 | How event export requests are compressed, in place of `OTEL_EXPORTER_OTLP_COMPRESSION`.                                                                                                     |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`           | deployment | `OTEL_EXPORTER_OTLP_ENDPOINT` with `/v1/logs` appended            | 0.2.0 | The full URL event records are sent to, used as it is and in place of `OTEL_EXPORTER_OTLP_ENDPOINT`.                                                                                        |
| `OTEL_EXPORTER_OTLP_LOGS_HEADERS`            | deployment | unset                                                             | 0.2.0 | Headers sent with every event export, in the same form, merged over `OTEL_EXPORTER_OTLP_HEADERS`. Secret.                                                                                   |
| `OTEL_EXPORTER_OTLP_LOGS_TIMEOUT`            | deployment | `OTEL_EXPORTER_OTLP_TIMEOUT`, else `10000`                        | 0.2.0 | How long one event export may take, in milliseconds, in place of `OTEL_EXPORTER_OTLP_TIMEOUT`.                                                                                              |
| `OTEL_EXPORTER_OTLP_TIMEOUT`                 | deployment | `10000`, the OpenTelemetry default                                | 0.2.0 | How long one export may take, its retries included, in milliseconds, at most an hour.                                                                                                       |
| `OTEL_SERVICE_NAME`                          | deployment | `qauth-auth-server`                                               | 0.2.0 | The `service.name` resource attribute of every exported event record.                                                                                                                       |
| `REQUEST_ID_HEADER`                          | deployment | `x-request-id`                                                    | 0.1.0 | The HTTP header that carries the request id, taken from the request when present and echoed on the response.                                                                                |

### Events

| Key                                  | Role       | Default | Since | Description                                                                                                                                                                                                             |
| ------------------------------------ | ---------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EVENT_DELIVERY_MAX_ATTEMPTS`        | deployment | `12`    | 0.2.0 | The attempts an event delivery to a webhook or another route gets before it ends `failed`; a failed delivery stays in the delivery history.                                                                             |
| `EVENT_DELIVERY_RETRY_INITIAL_DELAY` | deployment | `30`    | 0.2.0 | Seconds an event delivery waits after its first failed attempt; each later wait doubles, less up to 20% at random.                                                                                                      |
| `EVENT_DELIVERY_RETRY_MAX_DELAY`     | deployment | `21600` | 0.2.0 | The longest wait between two attempts of an event delivery, in seconds; at least `EVENT_DELIVERY_RETRY_INITIAL_DELAY`.                                                                                                  |
| `SSF_TRANSMITTER_ENABLED`            | deployment | `false` | 0.2.0 | Turn the Shared Signals Framework transmitter on (`/.well-known/ssf-configuration`, stream management under `/ssf/`, push delivery of Security Event Tokens) for each realm whose `ssf_transmitter_enabled` is also on. |

### Database and Redis

| Key                          | Role       | Default | Since | Description                                                                                                                                                                                                                                            |
| ---------------------------- | ---------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DB_MIGRATION_WAIT_MS`       | deployment | `60000` | 0.2.0 | How long, in milliseconds, the auth server waits at boot for the database to have every migration of its release before it exits naming the missing ones, `0` to check once; a database ahead of the release is accepted, as during a rolling upgrade. |
| `DB_POOL_CONNECTION_TIMEOUT` | deployment | `2000`  | 0.1.0 | How long, in milliseconds, the pool waits for a new Postgres connection.                                                                                                                                                                               |
| `DB_POOL_IDLE_TIMEOUT`       | deployment | `10000` | 0.1.0 | How long, in milliseconds, an idle Postgres connection stays in the pool.                                                                                                                                                                              |
| `DB_POOL_MAX`                | deployment | `20`    | 0.1.0 | The largest number of connections in the Postgres pool, at least 2 for the auth server, whose running jobs hold one for their lock.                                                                                                                    |
| `DB_POOL_MIN`                | deployment | `2`     | 0.1.0 | The smallest number of connections the Postgres pool keeps.                                                                                                                                                                                            |
| `REDIS_COMMAND_TIMEOUT`      | deployment | `5000`  | 0.1.0 | How long, in milliseconds, the server waits for one Redis command.                                                                                                                                                                                     |
| `REDIS_CONNECTION_TIMEOUT`   | deployment | `10000` | 0.1.0 | How long, in milliseconds, the server waits to connect to Redis.                                                                                                                                                                                       |
| `REDIS_MAX_RETRIES`          | deployment | `3`     | 0.1.0 | How many times one Redis command is retried before it fails.                                                                                                                                                                                           |

### Tokens

| Key            | Role       | Default | Since | Description                                                                                                                                                               |
| -------------- | ---------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DPOP_ENABLED` | deployment | `false` | 0.2.0 | Turn DPoP-bound tokens on (RFC 9449): the token endpoint binds tokens to the key of a DPoP proof, and refuses a client marked `dpop_bound_access_tokens` that sends none. |

### Signing

| Key                      | Role       | Default     | Since | Description                                                                                                                                                                                               |
| ------------------------ | ---------- | ----------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PQC_SELF_CONTAINED_ACK` | deployment | `false`     | 0.1.0 | Confirm that `self-contained` hybrid tokens, whose ML-DSA-65 signature exceeds cookie and URL size limits, travel only where large headers are accepted; `PQC_TOKEN_DELIVERY=self-contained` requires it. |
| `PQC_TOKEN_DELIVERY`     | deployment | `reference` | 0.1.0 | How the ML-DSA-65 signature of a hybrid token reaches a verifier: `reference`, through introspection, or `self-contained`, with the token.                                                                |

### Keys and secrets

| Key                                | Role       | Default                                          | Since | Description                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------- | ---------- | ------------------------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_MLDSA_KID`                    | deployment | unset                                            | 0.1.0 | The key id of the ML-DSA-65 key, published as `pqc_kid` and in the JWKS.                                                                                                                                                                                                                                                        |
| `JWT_MLDSA_PRIVATE_KEY`            | deployment | unset                                            | 0.1.0 | An ML-DSA-65 private key for hybrid signing, as a base64url-encoded 32-byte seed, imported into the default realm's key store with the Ed25519 key as a hybrid pair. Secret.                                                                                                                                                    |
| `JWT_MLDSA_PRIVATE_KEY_PATH`       | deployment | unset                                            | 0.1.0 | A file holding the ML-DSA-65 seed; it takes precedence over `JWT_MLDSA_PRIVATE_KEY`.                                                                                                                                                                                                                                            |
| `JWT_PRIVATE_KEY`                  | deployment | none; the key store holds the signing keys       | 0.1.0 | An Ed25519 private key, PEM, imported into the default realm's key store when the store lacks it, where it replaces the active Ed25519 token key; tokens are signed with the stored key; only a process that holds the `signer` role may have it. Secret.                                                                       |
| `JWT_PRIVATE_KEY_PATH`             | deployment | unset                                            | 0.1.0 | A file holding the Ed25519 private key; it takes precedence over `JWT_PRIVATE_KEY`.                                                                                                                                                                                                                                             |
| `JWT_PUBLIC_KEY`                   | deployment | unset                                            | 0.1.0 | The Ed25519 public key, PEM; derived from the private key when unset, and refused at boot when it is not the private key's public half; a process without the `signer` role does not need it, as it verifies tokens with the realm's published keys.                                                                            |
| `JWT_PUBLIC_KEY_PATH`              | deployment | unset                                            | 0.1.0 | A file holding the Ed25519 public key; it takes precedence over `JWT_PUBLIC_KEY`.                                                                                                                                                                                                                                               |
| `JWT_RS256_KID`                    | deployment | unset                                            | 0.1.0 | The `kid` of the RS256 key in the JWKS, which must differ from the Ed25519 key id.                                                                                                                                                                                                                                              |
| `JWT_RS256_PRIVATE_KEY`            | deployment | unset                                            | 0.1.0 | An RSA private key, PKCS#8 PEM, imported into the default realm's key store as its RS256 key, which signs ID tokens and is published in the JWKS. Secret.                                                                                                                                                                       |
| `JWT_RS256_PRIVATE_KEY_PATH`       | deployment | unset                                            | 0.1.0 | A file holding the RS256 private key; it takes precedence over `JWT_RS256_PRIVATE_KEY`.                                                                                                                                                                                                                                         |
| `JWT_RS256_PUBLIC_KEY`             | deployment | unset                                            | 0.1.0 | The RS256 public key, SPKI PEM; derived from the private key when unset.                                                                                                                                                                                                                                                        |
| `JWT_RS256_PUBLIC_KEY_PATH`        | deployment | unset                                            | 0.1.0 | A file holding the RS256 public key; it takes precedence over `JWT_RS256_PUBLIC_KEY`.                                                                                                                                                                                                                                           |
| `OID4VP_RESPONSE_KEY_SECRET`       | deployment | unset                                            | 0.1.0 | A 32-byte key, base64 or base64url, read only to open the per-request response decryption keys a release before 0.2 stored with it, at most 15 minutes old; new keys are sealed with the realm's `data_at_rest` key; remove it once every node runs this release. Secret.                                                       |
| `OID4VP_VERIFIER_SIGNING_KEY`      | deployment | unset                                            | 0.1.0 | The verifier's ES256 private key, PEM, imported into the default realm's key store as its OID4VP request key when the store lacks it, where it replaces the active one; request objects are signed with the stored key, which the certificate chain must name; only a process that holds the `signer` role may have it. Secret. |
| `OID4VP_VERIFIER_SIGNING_KEY_PATH` | deployment | unset                                            | 0.1.0 | A file holding the verifier signing key, imported as `OID4VP_VERIFIER_SIGNING_KEY` is; it takes precedence over it.                                                                                                                                                                                                             |
| `PORTAL_SESSION_SECRET`            | deployment | required                                         | 0.1.0 | The random secret that signs the developer portal's session cookie; use at least 32 characters. Secret.                                                                                                                                                                                                                         |
| `SESSION_COOKIE_SECRET`            | deployment | none; the key store holds the realm's cookie key | 0.1.0 | A session cookie secret of at least 32 characters, imported into the default realm's key store when it differs from the stored cookie key, which it then replaces; the cookies are signed with the stored key, and `NODE_ENV=production` refuses every value QAuth's examples published. Secret.                                |
| `SIGNER_URL`                       | deployment | unset                                            | 0.2.0 | The `https` URL of the signer service, required with the internal TLS files on a process whose `SERVICE_ROLES` leaves out `signer`; ignored, with a warning, where the signer runs in-process.                                                                                                                                  |

### Accounts and passwords

| Key                                 | Role                                        | Default  | Since | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------- | ------------------------------------------- | -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BOT_CHALLENGE_DIFFICULTY`          | realm-seed: `botChallenge.difficulty`       | `18`     | 0.2.0 | How many leading zero bits the built-in proof of work asks for, 1 to 32, each one doubling the page's work (18 is about 262,000 SHA-256 hashes, a second or two in a browser), that seeds `botChallenge.difficulty` of a new realm, and of a realm whose stored policies lack it at the first boot of the release that added it; once the realm has it, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is.                                                                                                                                                       |
| `BOT_CHALLENGE_HOSTED_NAME`         | deployment                                  | unset    | 0.2.0 | The name the hosted bot-challenge provider goes by in the `captcha` step, such as `turnstile`: a lower-case letter, then up to 31 lower-case letters, digits, `_` or `-`, never `pow`; required when `BOT_CHALLENGE_PROVIDER` is `hosted`.                                                                                                                                                                                                                                                                                                                                                                                |
| `BOT_CHALLENGE_HOSTED_SECRET`       | deployment                                  | unset    | 0.2.0 | The operator's secret for the hosted bot-challenge provider, sent with each token to its verify URL and never logged; required when `BOT_CHALLENGE_PROVIDER` is `hosted`. Secret.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `BOT_CHALLENGE_HOSTED_SITE_KEY`     | deployment                                  | unset    | 0.2.0 | The hosted bot-challenge provider's public site key, sent to the page in the `captcha` step; required when `BOT_CHALLENGE_PROVIDER` is `hosted`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `BOT_CHALLENGE_HOSTED_VERIFY_URL`   | deployment                                  | unset    | 0.2.0 | The https URL the hosted bot-challenge provider checks tokens at, such as `https://challenges.cloudflare.com/turnstile/v0/siteverify`, reached through the egress client as an operator destination with no redirect followed and capped time and size, so a host on a private address needs an `EGRESS_ALLOWLIST_PATH` entry naming the realms that use it; it carries no user name, password, query or fragment, and is required when `BOT_CHALLENGE_PROVIDER` is `hosted`.                                                                                                                                             |
| `BOT_CHALLENGE_PROVIDER`            | deployment                                  | `pow`    | 0.2.0 | Who answers the bot challenge the sign-in engine asks for past a soft threshold and at a sign-up that requires it: `pow`, the built-in proof of work, which the page solves from the realm origin and the server checks with no outbound call, or `hosted`, the provider the `BOT_CHALLENGE_HOSTED_*` keys name, whose tokens are checked at its verify URL through the egress client; a provider that cannot answer refuses the round, never waves it through.                                                                                                                                                           |
| `BOT_CHALLENGE_REQUIRED_AT_SIGN_UP` | realm-seed: `botChallenge.requiredAtSignUp` | `false`  | 0.2.0 | Whether every sign-up through the sign-in engine (the legacy `POST /auth/register` never asks) passes the bot challenge before its address is asked for, whatever the client, which then needs JavaScript on the hosted pages and is refused to a client that cannot serve the `captcha` step, that seeds `botChallenge.requiredAtSignUp` of a new realm, and of a realm whose stored policies lack it at the first boot of the release that added it; once the realm has it, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is.                                 |
| `BREACHED_PASSWORD_LIST_PATH`       | deployment                                  | unset    | 0.2.0 | A file of SHA-1 digests of breached passwords, one per line as 40 hex characters with an optional `:count` (the form the Have I Been Pwned downloader writes), that realms whose `password.breachListSource` is `local` check passwords against; at most 5,000,000 distinct digests (100 MB in memory), so a whole corpus does not load and its most common passwords do; loaded at boot, loaded again without a restart within 30 seconds of the file changing, and kept as it was when a reload fails; unset, there is no local list, and a realm that names `local` gets a failed check, which never blocks a sign-in. |
| `BREACHED_PASSWORD_RANGE_URL`       | deployment                                  | unset    | 0.2.0 | The https URL, such as `https://api.pwnedpasswords.com/range/`, that the k-anonymity range lookup of realms whose `password.breachListSource` is `k_anonymity` appends the first five hex characters of a password's SHA-1 to, reached through the egress client as an operator destination; it carries no user name, password, query or fragment, its path ends with `/`, and a bad value fails the boot; unset, there is no lookup, and such a realm gets a failed check, which never blocks a sign-in.                                                                                                                 |
| `PASSWORD_HASH_QUEUE_LIMIT`         | deployment                                  | `32`     | 0.2.0 | How many Argon2id jobs may wait for a free thread before a client-secret check is refused at once with `503` and `Retry-After`; `0` refuses one whenever every thread is busy.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `PASSWORD_MEMORY_COST`              | deployment                                  | `65536`  | 0.1.0 | The Argon2id memory cost, in KiB, of a password hash.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `PASSWORD_PARALLELISM`              | deployment                                  | `4`      | 0.1.0 | The Argon2id parallelism, in lanes, of a password hash.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `PASSWORD_TIME_COST`                | deployment                                  | `3`      | 0.1.0 | The Argon2id time cost, in iterations, of a password hash.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `SYSTEM_CLIENT_ID`                  | deployment                                  | `system` | 0.1.0 | The client id of the system client, the developer portal's client that direct logins are issued under; the operator provisions it from the migration runner's `SYSTEM_CLIENT_*` variables or the seed manifest's `system_client` section, and until then a placeholder that holds no secret is created on first use; set the same value on the migration runner.                                                                                                                                                                                                                                                          |

### Browser sessions

| Key                          | Role       | Default | Since | Description                                                                                                                                                                                         |
| ---------------------------- | ---------- | ------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INTERACTION_TTL`            | deployment | `1800`  | 0.2.0 | How long, in seconds, a browser sign-in ceremony and its flow cookie live, counted from the request that starts it (one whose first step nobody answers ends after 10 minutes); from 60 to 7200.    |
| `SESSION_COOKIE_SECURE`      | deployment | `true`  | 0.1.0 | Set the `Secure` attribute on the session cookie; only a plain-HTTP development stack turns it off.                                                                                                 |
| `SESSION_COOKIE_TTL`         | deployment | `86400` | 0.1.0 | The browser session lifetime, in seconds, counted from sign-in.                                                                                                                                     |
| `SESSION_LAST_SEEN_INTERVAL` | deployment | `60`    | 0.2.0 | How often, at most, in seconds, the last-seen time of a browser session is written; the idle limit of its realm is judged from that time.                                                           |
| `SESSION_RETENTION_DAYS`     | deployment | `30`    | 0.2.0 | The days a browser session row is kept after it ended, or after the session expiry job marked it expired or idle, for the account and admin session lists, before the session purge job deletes it. |

### Mail

| Key              | Role       | Default | Since | Description                                                                                                                                                                                                                                            |
| ---------------- | ---------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `EMAIL_BASE_URL` | deployment | unset   | 0.1.0 | Optional and not read since 0.2.0, because a link in mail, such as a verification link, starts at the issuer of the realm the account belongs to; still accepted, with a boot warning that it is ignored when it names another base than `JWT_ISSUER`. |

### Client registration

| Key                         | Role       | Default | Since | Description                                                                                                             |
| --------------------------- | ---------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------- |
| `CIMD_CACHE_DEFAULT_TTL`    | deployment | `300`   | 0.1.0 | How long, in seconds, a fetched metadata document is cached when its response states no lifetime.                       |
| `CIMD_CACHE_MAX_TTL`        | deployment | `3600`  | 0.1.0 | The longest time, in seconds, a fetched metadata document is cached, whatever its response states.                      |
| `CIMD_FETCH_TIMEOUT_MS`     | deployment | `5000`  | 0.1.0 | The deadline, in milliseconds, for one whole metadata document fetch.                                                   |
| `CIMD_MAX_DOCUMENT_BYTES`   | deployment | `65536` | 0.1.0 | The largest metadata document, in bytes, the server accepts.                                                            |
| `DYNAMIC_CLIENT_BADGE_DAYS` | deployment | `30`    | 0.1.0 | How many days after dynamic registration the consent screen marks a client as newly registered; `0` turns the mark off. |
| `MAX_CLIENTS_PER_DEVELOPER` | deployment | `100`   | 0.1.0 | The most OAuth clients one developer account may own, at least 1.                                                       |

### Enterprise-managed authorization (ID-JAG)

| Key                              | Role       | Default | Since | Description                                                                                                                                                                                                    |
| -------------------------------- | ---------- | ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ID_JAG_CLOCK_SKEW_LEEWAY`       | deployment | `60`    | 0.1.0 | The clock skew, in seconds, allowed when checking an assertion's `exp`, `nbf` and `iat`; at most 300.                                                                                                          |
| `ID_JAG_FETCH_TIMEOUT_MS`        | deployment | `5000`  | 0.1.0 | The deadline, in milliseconds, for each fetch of a trusted issuer's discovery document and JWKS.                                                                                                               |
| `ID_JAG_ISSUED_LIFETIME`         | deployment | `300`   | 0.1.0 | The lifetime, in seconds, of an ID-JAG the server mints; at most 3600.                                                                                                                                         |
| `ID_JAG_JWKS_CACHE_TTL`          | deployment | `300`   | 0.1.0 | How long, in seconds, a trusted issuer's discovery document and JWKS are cached; at most 3600. `0` turns the cache off, and every assertion then costs the issuer two fetches.                                 |
| `ID_JAG_JWKS_NEGATIVE_CACHE_TTL` | deployment | `30`    | 0.2.0 | How long, in seconds, a failed fetch of a trusted issuer's discovery document or JWKS is remembered, during which no fetch is made for that issuer; from 1 to 300.                                             |
| `ID_JAG_JWKS_REFRESH_COOLDOWN`   | deployment | `30`    | 0.2.0 | The shortest time, in seconds, between two refreshes of a trusted issuer's discovery document and JWKS forced by assertions with an unknown `kid`, which inside it are refused without a fetch; from 1 to 300. |
| `ID_JAG_MAX_ASSERTION_LIFETIME`  | deployment | `300`   | 0.1.0 | The longest lifetime, in seconds, of an assertion the server accepts; at most 3600.                                                                                                                            |
| `ID_JAG_MAX_DOCUMENT_BYTES`      | deployment | `65536` | 0.1.0 | The largest discovery document or JWKS, in bytes, the server accepts.                                                                                                                                          |

### Passkeys

| Key                                  | Role                                    | Default                                     | Since | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------ | --------------------------------------- | ------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PASSKEY_OFFER_AFTER_SIGN_IN`        | realm-seed: `passkeys.offerAfterSignIn` | `true`                                      | 0.2.4 | Whether the hosted sign-in offers to add a passkey after a password sign-in, to a verified account whose only factor is that password, while `WEBAUTHN_ENABLED` is on (a passkey added from the account page is not affected), that seeds `passkeys.offerAfterSignIn` of a new realm, and of a realm whose stored policies lack it at the first boot of the release that added it; once the realm has it, the server reads the realm row's value, never this key, so a later change leaves every such realm as it is. |
| `WEBAUTHN_ANDROID_APPS`              | deployment                              | empty                                       | 0.2.0 | Android apps as JSON, package name to SHA-256 signing-certificate fingerprints, served in `/.well-known/assetlinks.json` while the RP ID is the realm host.                                                                                                                                                                                                                                                                                                                                                           |
| `WEBAUTHN_APPLE_APP_IDS`             | deployment                              | empty                                       | 0.2.0 | Apple app identifiers (`<Team ID>.<bundle id>`), comma-separated, served in `/.well-known/apple-app-site-association` while the RP ID is the realm host.                                                                                                                                                                                                                                                                                                                                                              |
| `WEBAUTHN_ENABLED`                   | deployment                              | `false`                                     | 0.2.0 | Turn passkeys on: passkey sign-in, the offer to add one after a password sign-in where the realm keeps it (`passkeys.offerAfterSignIn`), and sign-up with a passkey alone (no email address) where the realm allows sign-up; only the hosted pages (`INTERACTION_UI_ENABLED`) offer a passkey, and while they are off the server warns at every boot.                                                                                                                                                                 |
| `WEBAUTHN_RP_ID`                     | deployment                              | the default realm's host, from `JWT_ISSUER` | 0.2.0 | The default realm's passkey RP ID, stored on the realm at boot: its host, or a parent domain that is not a public suffix, with `WEBAUTHN_RP_ID_ALLOW_PARENT_DOMAIN`; locked once the realm has a passkey, after which another value refuses to boot.                                                                                                                                                                                                                                                                  |
| `WEBAUTHN_RP_ID_ALLOW_PARENT_DOMAIN` | deployment                              | `false`                                     | 0.2.0 | Allow a parent domain of the realm host as the RP ID, which lets every host under it ask for the realm's passkeys; the server warns at every boot.                                                                                                                                                                                                                                                                                                                                                                    |

### Wallet federation

| Key                                      | Role       | Default                                           | Since | Description                                                                                                                                 |
| ---------------------------------------- | ---------- | ------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACR_VALUE_STYLE`                        | deployment | `eidas-uri`                                       | 0.1.0 | How the `acr` claim is written: `eidas-uri` for the eIDAS URIs, or `loa-name` for the bare level names.                                     |
| `OID4VP_ATTESTING_ISSUERS`               | deployment | unset                                             | 0.1.0 | As JSON, the issuers whose issuance validates a wallet's key attestation, each with the attack-potential grade it establishes.              |
| `OID4VP_EMAIL_VERIFYING_ISSUERS`         | deployment | unset                                             | 0.1.0 | The trusted issuers, comma-separated, whose `email` claim counts as verified even when the wallet does not disclose `email_verified: true`. |
| `OID4VP_ISSUER_ASSURANCE`                | deployment | unset                                             | 0.1.0 | As JSON, per realm name, the eIDAS level of assurance a trusted issuer's credentials establish, which becomes the `acr` claim.              |
| `OID4VP_ISSUER_JWKS`                     | deployment | unset                                             | 0.1.0 | As JSON, the public keys each credential issuer signs with; a key here grants no trust on its own.                                          |
| `OID4VP_REQUESTED_VCT`                   | deployment | unset                                             | 0.1.0 | The credential types (`vct` values) the wallet sign-in screen asks for, comma-separated; without them the screen is not offered.            |
| `OID4VP_STATUS_LIST_SIGNERS`             | deployment | unset                                             | 0.1.0 | As JSON, the status issuer that may sign the lists served under a URI prefix on another host.                                               |
| `OID4VP_STATUS_LIST_TRUST_ANCHORS`       | deployment | unset                                             | 0.1.0 | The PEM certificates a Status List Token's certificate chain must end at, set together with `OID4VP_STATUS_LIST_URI_ALLOWLIST`.             |
| `OID4VP_STATUS_LIST_TRUST_ANCHORS_PATH`  | deployment | unset                                             | 0.1.0 | A file holding more status list trust anchors, added to `OID4VP_STATUS_LIST_TRUST_ANCHORS`.                                                 |
| `OID4VP_STATUS_LIST_URI_ALLOWLIST`       | deployment | unset                                             | 0.1.0 | The `https://` URI prefixes, comma-separated, that status lists may be fetched from, set together with `OID4VP_STATUS_LIST_TRUST_ANCHORS`.  |
| `OID4VP_SUBJECT_BINDING_CLAIMS`          | deployment | unset                                             | 0.1.0 | The credential claims, comma-separated, that bind a presentation to the asserted account; `asserted-lookup` refuses to start without them.  |
| `OID4VP_SUBJECT_CLAIM`                   | deployment | unset                                             | 0.1.0 | The claim that carries an issuer's stable subject identifier, for `OID4VP_SUBJECT_RESOLUTION=issuer-scoped-claim`.                          |
| `OID4VP_SUBJECT_CLAIM_ISSUERS`           | deployment | unset                                             | 0.1.0 | The issuers, comma-separated, whose credentials `issuer-scoped-claim` resolution may key an account on.                                     |
| `OID4VP_SUBJECT_RESOLUTION`              | deployment | the verifier profile's default, `asserted-lookup` | 0.1.0 | How a presentation is resolved to an account: `asserted-lookup` or `issuer-scoped-claim`.                                                   |
| `OID4VP_TRUSTED_ISSUERS`                 | deployment | unset                                             | 0.1.0 | As JSON, per realm name, the credential issuers whose credentials that realm accepts; unset, no realm trusts any issuer.                    |
| `OID4VP_VERIFIER_CERTIFICATE_CHAIN`      | deployment | unset                                             | 0.1.0 | The verifier's PEM certificate chain, leaf first and without the trust anchor, sent as the signed request's `x5c`.                          |
| `OID4VP_VERIFIER_CERTIFICATE_CHAIN_PATH` | deployment | unset                                             | 0.1.0 | A file holding the verifier certificate chain; it takes precedence over `OID4VP_VERIFIER_CERTIFICATE_CHAIN`.                                |
| `OID4VP_VERIFIER_TRUST_ANCHORS`          | deployment | unset                                             | 0.1.0 | The PEM certificates the verifier certificate chain must end at, checked at boot.                                                           |
| `OID4VP_VERIFIER_TRUST_ANCHORS_PATH`     | deployment | unset                                             | 0.1.0 | A file holding more verifier trust anchors, added to `OID4VP_VERIFIER_TRUST_ANCHORS`.                                                       |
| `OID4VP_WALLET_INVOCATION_ENDPOINT`      | deployment | `openid4vp://`                                    | 0.1.0 | Where the wallet sign-in screen's QR code and wallet button point: a wallet's custom scheme or universal link.                              |

### Plugins

| Key                   | Role       | Default | Since | Description                                                                                                                                                                                    |
| --------------------- | ---------- | ------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_METHOD_PLUGINS` | deployment | empty   | 0.2.0 | The AuthMethod plugin packages to load at boot, by npm package name, comma-separated; the operator installs them with the deployment, and a package that is not a valid plugin stops the boot. |

### Rate limits

| Key                                 | Role       | Default | Since | Description                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------- | ---------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTHORIZE_RATE_LIMIT`              | deployment | `60`    | 0.1.0 | The most authorization requests allowed per window for a `production` realm, the strict tier.                                                                                                                                                                                                                                                                                 |
| `AUTHORIZE_RATE_LIMIT_LENIENT`      | deployment | `600`   | 0.1.0 | The most authorization requests allowed per window for a `development` or `staging` realm, the lenient tier.                                                                                                                                                                                                                                                                  |
| `AUTHORIZE_RATE_WINDOW`             | deployment | `60`    | 0.1.0 | The window, in seconds, of both authorization request limits.                                                                                                                                                                                                                                                                                                                 |
| `CEREMONY_APP_PEERS`                | deployment | empty   | 0.2.0 | The ceremony app server's egress addresses, as IP addresses and CIDR ranges, whose step reads of the Interaction API count per interaction under `CEREMONY_APP_PEER_RATE_LIMIT` instead of per address; empty by default, so a deployment whose ceremony app reads the step from its server must list that server here, or everyone signing in shares its one address bucket. |
| `CEREMONY_APP_PEER_RATE_LIMIT`      | deployment | unset   | 0.2.0 | The step reads of the Interaction API a peer listed in `CEREMONY_APP_PEERS` may make of one interaction per minute, set together with that list; a boot that sets one of the two without the other is refused.                                                                                                                                                                |
| `HEALTH_RATE_LIMIT_MAX`             | deployment | `1000`  | 0.1.0 | The most requests per client address to each of `/health` and `/ready`, counted in the process's memory allowed per window.                                                                                                                                                                                                                                                   |
| `HEALTH_RATE_LIMIT_WINDOW`          | deployment | `60`    | 0.1.0 | The window, in seconds, of `HEALTH_RATE_LIMIT_MAX`.                                                                                                                                                                                                                                                                                                                           |
| `INTROSPECT_RATE_LIMIT`             | deployment | `30`    | 0.1.0 | The most introspection requests allowed per window.                                                                                                                                                                                                                                                                                                                           |
| `INTROSPECT_RATE_WINDOW`            | deployment | `60`    | 0.1.0 | The window, in seconds, of `INTROSPECT_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                           |
| `LOGIN_RATE_LIMIT`                  | deployment | `5`     | 0.1.0 | The most login attempts allowed per window.                                                                                                                                                                                                                                                                                                                                   |
| `LOGIN_RATE_WINDOW`                 | deployment | `900`   | 0.1.0 | The window, in seconds, of `LOGIN_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                                |
| `LOGOUT_RATE_LIMIT`                 | deployment | `20`    | 0.1.0 | The most logout requests allowed per window.                                                                                                                                                                                                                                                                                                                                  |
| `LOGOUT_RATE_WINDOW`                | deployment | `60`    | 0.1.0 | The window, in seconds, of `LOGOUT_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                               |
| `OID4VP_REQUEST_OBJECT_RATE_LIMIT`  | deployment | `30`    | 0.1.0 | The most request object fetches from `GET /oid4vp/request/:handle` per client address allowed per window.                                                                                                                                                                                                                                                                     |
| `OID4VP_REQUEST_OBJECT_RATE_WINDOW` | deployment | `60`    | 0.1.0 | The window, in seconds, of `OID4VP_REQUEST_OBJECT_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                |
| `OID4VP_RESPONSE_RATE_LIMIT`        | deployment | `30`    | 0.1.0 | The most wallet responses to `POST /oid4vp/response` per client address allowed per window.                                                                                                                                                                                                                                                                                   |
| `OID4VP_RESPONSE_RATE_WINDOW`       | deployment | `60`    | 0.1.0 | The window, in seconds, of `OID4VP_RESPONSE_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                      |
| `RATE_LIMIT_ENABLED`                | deployment | `true`  | 0.1.0 | Apply the rate limits at all; only a development or test stack turns them off.                                                                                                                                                                                                                                                                                                |
| `RATE_LIMIT_MAX`                    | deployment | `100`   | 0.1.0 | The most requests to a route with no limit of its own allowed per window.                                                                                                                                                                                                                                                                                                     |
| `RATE_LIMIT_WINDOW`                 | deployment | `3600`  | 0.1.0 | The window, in seconds, of `RATE_LIMIT_MAX`.                                                                                                                                                                                                                                                                                                                                  |
| `REFRESH_RATE_LIMIT`                | deployment | `10`    | 0.1.0 | The most refresh token requests allowed per window.                                                                                                                                                                                                                                                                                                                           |
| `REFRESH_RATE_WINDOW`               | deployment | `60`    | 0.1.0 | The window, in seconds, of `REFRESH_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                              |
| `REGISTER_CLIENT_RATE_LIMIT`        | deployment | `30`    | 0.1.0 | The most dynamic client registrations per client address allowed per window.                                                                                                                                                                                                                                                                                                  |
| `REGISTER_CLIENT_RATE_WINDOW`       | deployment | `60`    | 0.1.0 | The window, in seconds, of `REGISTER_CLIENT_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                      |
| `REGISTRATION_RATE_LIMIT`           | deployment | `3`     | 0.1.0 | The most account registrations allowed per window.                                                                                                                                                                                                                                                                                                                            |
| `REGISTRATION_RATE_WINDOW`          | deployment | `3600`  | 0.1.0 | The window, in seconds, of `REGISTRATION_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                         |
| `RESEND_VERIFICATION_EMAIL_LIMIT`   | deployment | `3`     | 0.1.0 | The most verification mail resends per email address allowed per window.                                                                                                                                                                                                                                                                                                      |
| `RESEND_VERIFICATION_EMAIL_WINDOW`  | deployment | `3600`  | 0.1.0 | The window, in seconds, of `RESEND_VERIFICATION_EMAIL_LIMIT`.                                                                                                                                                                                                                                                                                                                 |
| `RESEND_VERIFICATION_MIN_INTERVAL`  | deployment | `60`    | 0.1.0 | The shortest time, in seconds, between two verification mail resends to one address.                                                                                                                                                                                                                                                                                          |
| `RESEND_VERIFICATION_RATE_LIMIT`    | deployment | `100`   | 0.1.0 | The most verification mail resends per client address allowed per window.                                                                                                                                                                                                                                                                                                     |
| `RESEND_VERIFICATION_RATE_WINDOW`   | deployment | `60`    | 0.1.0 | The window, in seconds, of `RESEND_VERIFICATION_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                  |
| `TOKEN_RATE_LIMIT`                  | deployment | `30`    | 0.1.0 | The most token requests allowed per window for a `production` realm, the strict tier.                                                                                                                                                                                                                                                                                         |
| `TOKEN_RATE_LIMIT_LENIENT`          | deployment | `300`   | 0.1.0 | The most token requests allowed per window for a `development` or `staging` realm, the lenient tier.                                                                                                                                                                                                                                                                          |
| `TOKEN_RATE_WINDOW`                 | deployment | `60`    | 0.1.0 | The window, in seconds, of both token request limits.                                                                                                                                                                                                                                                                                                                         |
| `USERINFO_RATE_LIMIT`               | deployment | `60`    | 0.1.0 | The most userinfo requests allowed per window.                                                                                                                                                                                                                                                                                                                                |
| `USERINFO_RATE_WINDOW`              | deployment | `60`    | 0.1.0 | The window, in seconds, of `USERINFO_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                             |
| `VERIFICATION_RATE_LIMIT`           | deployment | `10`    | 0.1.0 | The most email verification attempts allowed per window.                                                                                                                                                                                                                                                                                                                      |
| `VERIFICATION_RATE_WINDOW`          | deployment | `900`   | 0.1.0 | The window, in seconds, of `VERIFICATION_RATE_LIMIT`.                                                                                                                                                                                                                                                                                                                         |

### Developer portal

| Key                  | Role       | Default  | Since | Description                                                                                                                                   |
| -------------------- | ---------- | -------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_SERVER_URL`    | deployment | required | 0.1.0 | The base URL the developer portal's server uses to reach the auth server.                                                                     |
| `PORTAL_SESSION_TTL` | deployment | `900`    | 0.1.0 | The developer portal session lifetime, in seconds.                                                                                            |
| `PORTAL_TRUST_PROXY` | deployment | unset    | 0.1.0 | The proxies in front of the developer portal, as comma-separated IP addresses, whose forwarded client address, protocol and host it believes. |

### Testing

| Key      | Role       | Default | Since | Description                                                                  |
| -------- | ---------- | ------- | ----- | ---------------------------------------------------------------------------- |
| `VITEST` | deployment | unset   | 0.1.0 | Set by the Vitest test runner; a deployment never sets it. Development only. |

## Experimental keys

### Browser sessions

| Key                      | Role       | Default | Since | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------ | ---------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CEREMONY_APP_DEPLOYED`  | deployment | `false` | 0.2.2 | Temporary: the operator's word that a ceremony app serves the ceremony page `/ui/interaction/{id}` on every realm host (operate/reverse-proxy.md), required while `INTERACTION_UI_ENABLED` is on, which sends every browser sign-in there, a page the auth server does not serve, so that without a ceremony app every sign-in would end in a 404; it only lifts that refusal, the auth server goes on serving its own `/ui` pages, and it goes with the switch.                                                    |
| `INTERACTION_UI_ENABLED` | deployment | `false` | 0.2.0 | Temporary: have `/oauth/authorize` start an interaction where a person must sign in or consent, and redirect to the ceremony page `/ui/interaction/{id}` with that id only, instead of the `/ui/login` and `/ui/consent` pages, and serve the hosted account pages at `/ui/account`; the auth server does not serve the ceremony page, a ceremony app must serve it on every realm host, so the boot refuses this switch unless `CEREMONY_APP_DEPLOYED` is on; the cut-over to the ceremony app removes the switch. |

### Plugins

| Key                  | Role       | Default | Since | Description                                                                                                                                           |
| -------------------- | ---------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PLUGIN_API_ENABLED` | deployment | `false` | 0.2.0 | Turn on the experimental plugin API, so a plugin outside QAuth's first-party list loads; with it off, such a plugin is skipped and the boot says why. |

### Experimental values

These values of stable and advanced keys are experimental, and the server warns at boot when one is set. A value that switches on an [experimental feature](/reference/experimental-features/) warns through that feature instead, once the feature is on.

| Key                       | Experimental values |
| ------------------------- | ------------------- |
| `OID4VP_VERIFIER_PROFILE` | `oid4vp-1.0-base`   |

## Renamed keys

A renamed key keeps working under its old name for the deprecation window.

- Only the old name is set: the server uses its value and logs a warning at boot.
- Both names are set to the same value: the server logs a warning at boot.
- Both names are set to different values: the server refuses to start, and the error names both.

| Old name                 | Use instead                | Deprecated since |
| ------------------------ | -------------------------- | ---------------- |
| `REQUIRE_EMAIL_VERIFIED` | `REQUIRE_VERIFIED_ACCOUNT` | 0.1.0            |

## Removed keys

The server no longer reads these keys and refuses to start while one is set, whatever its value. The error names the key and what replaces it.

| Key                              | Removed in | Instead                                                                                                                                                                                                                                                         |
| -------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CIMD_ALLOW_PRIVATE_ADDRESSES`   | 0.2.0      | A metadata document or client jwks_uri never reaches a private address now; list an operator-set private destination in the file EGRESS_ALLOWLIST_PATH names, and reach a test server through createTestEgressClient.                                           |
| `ID_JAG_ALLOW_PRIVATE_ADDRESSES` | 0.2.0      | A trusted issuer's discovery URL on a private address is listed, for its realms, in the file EGRESS_ALLOWLIST_PATH names; the jwks_uri its discovery document names never reaches a private address. Tests reach a local issuer through createTestEgressClient. |

## Adding a key

A pull request that adds, renames or removes a key registers the change in the same pull request: an entry in `libs/server/config/src/lib/registry/keys/`, with its tier, role, default and one sentence, and a regenerated page; a removed key moves to `registry/removed.ts`. A stable key also appears in `.env.example`. A test fails until all three agree.

---

# Published images

URL: https://docs.qauth.dev/operate/images/

Each QAuth release publishes two container images, built once from the
release tag by the repository's `release-images` workflow
(`release-images.yml` in the workflows directory):

| Image                                       | What it is                                                                    |
| ------------------------------------------- | ----------------------------------------------------------------------------- |
| `ghcr.io/qauth-labs/qauth/auth-server`      | The authorization server, from `apps/auth-server/Dockerfile`                  |
| `ghcr.io/qauth-labs/qauth/migration-runner` | The program every upgrade runs first, from `apps/migration-runner/Dockerfile` |

Both are `linux/amd64` only for now.

The developer portal is not published as an image. Its Dockerfile writes the
auth server's public URL (`VITE_AUTH_SERVER_URL`) into the browser bundle at
build time, so one image could only ever talk to one host. Build it from
source with your own URL, as the [Docker guide](/operate/docker/) shows.

## Tags and digests

A release `vX.Y.Z` is tagged `X.Y.Z` and `X.Y`. A release candidate
`vX.Y.Z-rc.N` is tagged only `X.Y.Z-rc.N`, so it never moves a stable tag.
There is no `latest` tag before 1.0.

Tags can move; a digest cannot. Pin the digest that the release's workflow run
lists in its summary, and keep the tag only as a readable comment:

```yaml
services:
  migration-runner:
    image: ghcr.io/qauth-labs/qauth/migration-runner@sha256:<digest> # 0.2.0
  auth-server:
    image: ghcr.io/qauth-labs/qauth/auth-server@sha256:<digest> # 0.2.0
```

In the repository's `docker-compose.yml`, these two lines replace the `build:`
blocks of the same services. Everything else stays the same: the environment,
the keys and the order (the migration runner first, then the server). See
[Upgrades](/operate/upgrades/) for that order on every later version.

## Verify before you run

Every image digest is signed with cosign, keyless, by the release workflow's
own identity. Two attestations are attached to the same digest: build
provenance (SLSA) and an SPDX SBOM. Check all three before you deploy a digest.

The signature, with [cosign](https://docs.sigstore.dev/cosign/) 3.0 or later. The release
workflow signs with cosign 3, which stores the signature in the newer Sigstore bundle format;
cosign 2.x does not look there and reports `no signatures found` for a signed image:

```bash
cosign verify ghcr.io/qauth-labs/qauth/auth-server@sha256:<digest> \
  --certificate-identity-regexp '^https://github.com/qauth-labs/qauth/.github/workflows/release-images.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
```

The provenance and the SBOM, with the `gh` command-line tool. These need no cosign, and they
check the same signing identity (the release workflow at a tag), so they also serve as the
alternative when cosign 3 is not at hand:

```bash
gh attestation verify oci://ghcr.io/qauth-labs/qauth/auth-server@sha256:<digest> \
  --repo qauth-labs/qauth

gh attestation verify oci://ghcr.io/qauth-labs/qauth/auth-server@sha256:<digest> \
  --repo qauth-labs/qauth --predicate-type https://spdx.dev/Document/v2.3
```

The first command proves which workflow run, commit and tag built the image.
The second shows the packages inside it. Run the same commands for the
`migration-runner` digest.

## Add a plugin to the image

An [AuthMethod plugin](/extend/auth-method-contract/) is an npm package that the server imports by
name at boot, from its own `node_modules`. The server never fetches code, so a deployment that uses
a plugin runs its own image: the published one, with the package added on top.

The published `auth-server` image runs QAuth's sources from `/app`, a `pnpm deploy` tree, and
imports a listed plugin from `/app/node_modules/<package name>`. Install the plugin in a build
stage with npm and copy its directory there:

- **nested** (`--install-strategy=nested`), so the plugin's own dependencies, such as the plugin
  SDK, sit inside its directory and travel with it;
- **without its peer dependencies** (`--omit=peer`), so it takes `zod` from the server: a plugin's
  config schema must be built with the server's Zod, or the boot cannot read its secret members;
- **without install scripts** (`--ignore-scripts`);
- **from a lockfile you have read** (`npm ci`), at an exact version. Without a lockfile, npm
  resolves the ranges of the plugin's own dependencies again at every build, so a rebuild can put
  code nobody has read into the server.

Keep the plugin's `package.json` and `package-lock.json` in your build context, here in
`plugins/`. Write them once without installing anything, and read the lockfile before you commit
it:

```bash
mkdir plugins && cd plugins
npm init --yes > /dev/null
npm install --package-lock-only --save-exact --omit=dev --omit=peer \
  --install-strategy=nested --ignore-scripts @example/qauth-plugin-corp-sso@1.2.3
```

```dockerfile
# syntax=docker/dockerfile:1.7
# The QAuth release, by the digest you verified above.
ARG QAUTH_IMAGE=ghcr.io/qauth-labs/qauth/auth-server@sha256:<digest>

# The build stage writes the files the server will run: pin it by digest too.
FROM node:26-alpine@sha256:<digest> AS plugin
WORKDIR /plugin
COPY plugins/package.json plugins/package-lock.json ./
RUN npm ci --omit=dev --omit=peer --install-strategy=nested --ignore-scripts

FROM ${QAUTH_IMAGE}
COPY --from=plugin --chown=nodejs:nodejs \
  /plugin/node_modules/@example/qauth-plugin-corp-sso \
  /app/node_modules/@example/qauth-plugin-corp-sso
```

Copy one directory per plugin, at the same path below `/app/node_modules` as its package name.
Then list the package and, unless it is on QAuth's first-party list, turn on the plugin API:

```bash
AUTH_METHOD_PLUGINS=@example/qauth-plugin-corp-sso
PLUGIN_API_ENABLED=true
```

At boot the server logs `AuthMethod plugin @example/qauth-plugin-corp-sso loaded` with the
plugin's `id` and `type`. A package it cannot import stops the boot, and with
`PLUGIN_API_ENABLED` off it logs a warning that names the package and says why it was skipped. A
realm admin then enables and configures the plugin through the admin API
([Installing and enabling a plugin](/extend/auth-method-contract/#installing-and-enabling-a-plugin)).

A plugin release is built for one QAuth contract version, so rebuild this image at every QAuth
upgrade with the plugin version made for the new release; a mismatch stops the boot and says so.
Move the lockfile to that version with the same `npm install --package-lock-only` in `plugins/`,
and read its diff before you commit it.
Your image is no longer the digest QAuth signed: verify the base digest before you build on it,
and pin the build stage by digest as well. `npm audit signatures` in the build stage checks that
the registry's signatures and attestations are valid, not who built the package: to know that,
read the version's provenance (on npmjs.com, or the attestation at
`npm view <package>@<version> dist.attestations.url`) and check that it names the plugin's own
repository and release workflow. Plugin code runs
in the server's process, beside its keys in a single deployment, so add only a package you trust
as you trust the server.

For example, QAuth's own GitHub plugin, `@qauth-labs/plugin-github`, installs this way: the
end-to-end suite of its repository installs it with these flags into the released server image,
and its README names the plugin version made for each QAuth release.
The example's sources are in [qauth-labs/plugin-github](https://github.com/qauth-labs/plugin-github).

### QAuth's provider plugins

QAuth makes these plugins. Each lives in its own repository and has its own version line, and each
README says which QAuth release a version is for, what to set up at the provider, and the config
members. None is on the first-party list, so each needs `PLUGIN_API_ENABLED=true`. Register the
redirect URI at the provider, once for each host a realm signs in on.

| Provider  | Package                                                                                 | Redirect URI to register                           |
| --------- | --------------------------------------------------------------------------------------- | -------------------------------------------------- |
| GitHub    | [`@qauth-labs/plugin-github`](https://github.com/qauth-labs/plugin-github#readme)       | `https://<realm host>/upstream/github/callback`    |
| Google    | [`@qauth-labs/plugin-google`](https://github.com/qauth-labs/plugin-google#readme)       | `https://<realm host>/upstream/google/callback`    |
| Microsoft | [`@qauth-labs/plugin-microsoft`](https://github.com/qauth-labs/plugin-microsoft#readme) | `https://<realm host>/upstream/microsoft/callback` |

Google and Microsoft are [preset plugins](/extend/preset-plugins/), built on the server's own
OpenID Connect client, so they need QAuth `0.2.3` or later.

## What a release runs

1. A maintainer pushes the tag. A stable tag needs its `## [X.Y.Z]` section in
   `CHANGELOG.md` first, or the workflow stops.
2. The publish jobs wait in the `release` environment until a maintainer
   approves them.
3. Each image is built once, pushed by digest, signed and attested, and its
   digest is written to the run's summary.

A manual run of the workflow, and a pull request that changes it, build both
images and push nothing.

The same tag also stages QAuth's SDK packages on npm at the same version, in a
second workflow behind its own approval. The images and the packages of a
release always carry the same version.

---

# Reverse Proxy

URL: https://docs.qauth.dev/operate/reverse-proxy/

QAuth runs behind a reverse proxy ([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/),
Decisions 1, 5 and 8). The proxy terminates TLS, sends each realm host to the auth server, sends
`/ui/*` on the same host to the ceremony app, and sets the security headers of the ceremony pages.

The repository ships a reference configuration for nginx in `deploy/reference/proxy/`. The rules
below do not depend on nginx: another proxy that follows every one of them is a valid replacement.

:::caution[The ceremony app has not shipped yet]
Until the reference ceremony app ships, the auth server renders `/ui/*` itself and needs its
session cookie there. This configuration strips that cookie and sends `/ui/*` to the ceremony app,
so it is not yet a working front for browser sign-in. It fixes and tests the rules ahead of that
split. For the same reason the auth server refuses to boot with `INTERACTION_UI_ENABLED` on unless
`CEREMONY_APP_DEPLOYED` says a ceremony app serves the ceremony page `/ui/interaction/{id}`: the
server does not serve it, so without one every browser sign-in ends in a 404. The setting only
lifts that refusal; the auth server goes on serving its own `/ui` pages.
:::

## The rules

1. **Realm hosts only.** Every realm's host goes to the auth server. The match is case-insensitive
   and ignores the port. Any other host gets `421 Misdirected Request`, with no realm context. Only
   `/health` and `/ready` answer on every host. They go to the auth server.
2. **Route on the normalised path.** Merge repeated slashes, decode the percent-escapes of
   unreserved characters, and resolve `.` and `..` segments. Then match case-sensitively. Send the
   upstream the normalised path, not the raw request target, so it cannot read the path
   differently from the way it was routed. A proxy may decode more than that: nginx decodes every
   escape, so `%3B` reaches the upstream as `;`. Rules 3 and 9 then apply to the decoded path.
3. **Refuse path variants with 404.** The proxy answers by itself and neither upstream sees the
   request:
   - a disguised separator anywhere in the path, before the query: an encoded slash (`%2F`), or a
     backslash (`\` or `%5C`), which a WHATWG URL parser reads as a slash;
   - a path that looks like `/ui` but does not start with exactly `/ui/`. That is any path which,
     with every percent-escape decoded and compared case-insensitively, matches
     `^/ui(?:$|[^a-z0-9_-])`. Examples: `/ui` itself, a case variant such as `/UI/login`, a path
     parameter such as `/ui;x/login` or `/ui%3Bx/login`.
4. **Split by path.** `/ui/*` goes to the ceremony app. Every other path goes to the auth server.
5. **Strip cookies from `/ui/*`, both ways.** Remove the `Cookie` header from every request to
   `/ui/*`, including every separate `cookie` field of an HTTP/2 request, and drop every
   `Set-Cookie` from the answers. The ceremony app never sees QAuth's cookies and cannot set or
   overwrite one on the realm origin, so it can neither read nor mint a session-bound value.
6. **Set the ceremony headers.** On every `/ui/*` answer, replace whatever the app sent. This
   includes error answers and answers the proxy makes itself, such as a `502`.
   - `Content-Security-Policy: default-src 'self'; base-uri 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self' data:; connect-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'`
   - `Referrer-Policy: no-referrer`
   - `Cache-Control: no-store`, with one exception. A content-hashed asset gets
     `Cache-Control: public, max-age=31536000, immutable` when all of these hold: the answer is a
     `200` or `304` to a `GET` or `HEAD`, it sets no cookie, and the whole normalised path matches
     `^/ui/assets/(?:[A-Za-z0-9._-]+-)?[A-Za-z0-9_-]{8,}\.(?:js|mjs|css|woff2|woff|svg|png|jpg|jpeg|gif|webp|avif|ico)\z`.
     The pattern ends in `\z`, not `$`, because in most regular-expression engines `$` also
     matches before a final newline, which `%0A` decodes to.

     The pattern alone cannot tell a hashed name from a name such as `logo-standard.svg`. The
     ceremony app must therefore put nothing under `/ui/assets/` but files named by a hash of their
     content. Serve any other file outside that prefix, where it gets `no-store`. The reference
     app's build already does this.

   - One exception to the policy: a hosted bot-challenge provider's script hosts (ADR-019
     Decision 5). The list is empty by default, and the built-in proof of work needs none. When
     the auth server runs `BOT_CHALLENGE_PROVIDER=hosted`, the operator may name the provider's
     hosts, and the proxy adds them to `script-src` and `frame-src` on the interaction page,
     `/ui/interaction/*`, where a person signs in and signs up. No other path gets them, but a
     password reset, consent and the logout confirmation share that path, so they get them too. Accept
     only a list of `https` host sources separated by spaces, such as
     `https://challenges.cloudflare.com`, and drop any other value whole: a `;` in it would end
     the directive and add another. By naming hosts, the operator accepts that the provider's
     script runs where passwords are typed, as part of the realm's trusted computing base.
7. **Let no upstream steer the proxy.** Ignore every response header that asks the proxy to fetch
   another location or file internally: nginx's `X-Accel-Redirect` and the other `X-Accel-*`
   headers, or their equivalent in another proxy. Otherwise the ceremony app could have the proxy
   fetch an auth server page, with the client's cookies, and serve it under `/ui/*` without the
   ceremony headers.
8. **At the first hop, overwrite the forwarded headers.** This proxy is the one clients connect to.
   Set `X-Forwarded-For` to the address the proxy accepted the connection from, `X-Forwarded-Host`
   to the realm host and `X-Forwarded-Proto` to the scheme the client used, which is `https` on the
   only listener. Never pass on, or append to, what the client sent. Remove `Forwarded`,
   `X-Real-IP`, `X-Forwarded-Port`, `X-Forwarded-Prefix`, `X-Original-URL` and `X-Rewrite-URL`:
   QAuth reads none of them, and a web framework behind the proxy might. Then set the auth server's
   `TRUST_PROXY` to the proxy's address, so the auth server believes these headers from the proxy
   and from no one else.

   With another trusted hop in front, such as a load balancer, this proxy is no longer the first
   hop. It must then append the address it accepted the connection from to `X-Forwarded-For`
   (nginx: `$proxy_add_x_forwarded_for`), as [Docker](/operate/docker/#production-considerations)
   describes, and `TRUST_PROXY` must list every trusted hop. Overwriting there would make every
   client look like the hop in front of it. The first hop of the chain still overwrites.

9. **Keep internal paths internal.** Answer `404` on the public side for `/metrics`, `/internal/*`
   and their variants: every path which, with every percent-escape decoded and compared
   case-insensitively, matches `^/(?:metrics|internal)(?:$|[^a-z0-9_-])`.
10. **Mount certificates as files.** Automatic certificates (ACME) are not part of 1.0.

## The reference configuration

| File                       | Edit it? | What it holds                                                                                                              |
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `nginx.conf`               | No       | The `http` block: path normalisation, the separator, `Cache-Control` and CSP maps, and the default server (421, health).   |
| `qauth/realm.conf`         | No       | The rules of a realm host: path variants, internal paths, `/ui/*` and its headers, and everything else to the auth server. |
| `qauth/proxy-headers.conf` | No       | `Host`, the forwarded headers and the ignored `X-Accel-*` headers, for every proxied location.                             |
| `site/upstreams.conf`      | Yes      | The addresses of the auth server and the ceremony app.                                                                     |
| `site/realms.conf`         | Yes      | The realm hosts and their certificate paths. The hosts in it are examples.                                                 |
| `site/bot-challenge.conf`  | Yes      | A hosted bot-challenge provider's script hosts, per realm host. Empty by default.                                          |
| `test/`                    | No       | The CI test and its stub upstream.                                                                                         |

Inside the container the files sit at `/etc/nginx/nginx.conf`, `/etc/nginx/qauth/` and
`/etc/nginx/site/`. The certificate and its key are mounted at `/etc/nginx/certs/fullchain.pem`
and `/etc/nginx/certs/privkey.pem`. One certificate covers every realm host, and the default server
presents it too. For a certificate per host, copy the server block in `site/realms.conf` once per
host, with that host's `server_name` and certificate paths, and keep its `include`.

`site/realms.conf` names realm hosts only. An endpoint host, which server-to-server callers use
(Decision 1), usually stays on the internal network; through this proxy it gets `421`.

nginx resolves the upstream names once, at start, so the auth server and the ceremony app must be
resolvable when the proxy starts.

With the Compose stack, the proxy joins `qauth-network` with a fixed address below `<prefix>.128`,
as [Docker](/operate/docker/#production-considerations) describes for `TRUST_PROXY`:

```yaml
services:
  reverse-proxy:
    image: nginx:1.30-alpine
    ports:
      - '443:443'
    volumes:
      - ./deploy/reference/proxy/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./deploy/reference/proxy/qauth:/etc/nginx/qauth:ro
      - ./proxy/site:/etc/nginx/site:ro # your copies of site/*.conf
      - ./proxy/certs:/etc/nginx/certs:ro # fullchain.pem and privkey.pem
    networks:
      qauth-network:
        ipv4_address: ${QAUTH_NETWORK_PREFIX:-172.30.80}.20
```

Then set `TRUST_PROXY=172.30.80.10,172.30.80.20` on the auth server: the developer portal's address
and the proxy's.

The auth server must then be reachable only through the proxy. `docker-compose.yml` publishes it on
host port `3000`; take that mapping away when you add the proxy, for example in your override file:

```yaml
services:
  auth-server:
    ports: !reset []
```

`!reset` needs Docker Compose 2.24 or later; with an older Compose, delete the `ports` entry of
`auth-server` instead. Otherwise a client can send a realm `Host` straight to port `3000` and skip
every rule above: the path refusals, the cookie stripping, the ceremony headers and the `404` on
`/metrics` and `/internal/*`.

The reference configuration leaves out a plain-HTTP listener and its redirect, and IPv6 listeners.
A hosted bot-challenge provider's script hosts go in `site/bot-challenge.conf`, by realm host:

```nginx
map $host $qauth_bot_challenge_hosts {
    auth.example.com  "https://challenges.cloudflare.com";
    default  "";
}
```

An existing `site/` directory from an earlier release needs this file, with the empty default,
or nginx refuses to start.

## The test

`pnpm nx run reference-proxy:test-integration` starts the configuration, unchanged, in the nginx
image, in front of a stub auth server and a stub ceremony app. The stubs echo the headers and
cookies they receive, and the test checks every rule above against them, including that a refused
request reaches neither stub. It needs Docker and `openssl`. CI's `integration` job runs it
whenever a file under `deploy/reference/proxy/` changes.

---

# SSF transmitter

URL: https://docs.qauth.dev/operate/ssf-transmitter/

QAuth can be an [OpenID Shared Signals Framework 1.0](https://openid.net/specs/openid-sharedsignals-framework-1_0-final.html)
(SSF) transmitter. A receiver, such as a resource server, creates a stream at QAuth, and QAuth
pushes Security Event Tokens (SETs, RFC 8417) to the receiver's endpoint (RFC 8935). The SETs come
out of QAuth's event store and are sent by the delivery role, with its retries and its delivery
history.

The transmitter is experimental and off by default. It sends QAuth's security events as CAEP 1.0,
RISC 1.0 or QAuth-defined events: a sign-out as `session-revoked`, a withdrawn consent as
`token-claims-change`, a client secret, API key or wallet credential change as
`credential-change`, an RFC 7009 revocation as QAuth's `token-revoked`, and so on.
[SSF events](/reference/ssf-events/) lists every mapping, its subject and its members, generated
from the event registry.

## Turn it on

Two switches, both off by default:

1. The deployment's: `SSF_TRANSMITTER_ENABLED=true`. Off, the server registers no SSF route,
   serves no `/.well-known/ssf-configuration` and writes no SSF delivery.
2. Each realm's: `realms.ssf_transmitter_enabled`. A realm whose switch is off answers `404` on the
   metadata and on every `/ssf/` route, as for a route that does not exist, and its streams receive
   nothing. No API sets it yet; set it on the realm row:

```sql
UPDATE realms SET ssf_transmitter_enabled = true WHERE name = 'master';
```

The auth server reads realm rows through a cache, so a change takes effect within 30 seconds.

A realm needs two keys of its own: an `event_signing` key, which signs its SETs, and a
`data_at_rest` key, which stores receivers' headers. The default realm gets both at boot. For
any other realm, create them before turning its switch on (see
[Keys](/operate/keys/#adding-a-key-auth-serverkeyscreate)):

```bash
pnpm nx run auth-server:keys:create --realm=<realm> --purpose=event_signing --algorithm=EdDSA
pnpm nx run auth-server:keys:create --realm=<realm> --purpose=data_at_rest --algorithm=A256GCM
```

Without them, creating a stream with an `authorization_header` fails, and every delivery fails at
signing until its attempts run out.

With both on, the realm:

- serves the transmitter metadata at `/.well-known/ssf-configuration`. Every URL in it is built
  from the realm's issuer, which is also the `iss` of its SETs;
- serves its SET signing keys (the `event_signing` purpose of ADR-019 Decision 9) at
  `/ssf/jwks.json`, the `jwks_uri` of the metadata. A receiver verifies each SET with a key from
  there. It needs no token, and is cached for at most 5 minutes, as the realm JWKS is;
- keeps the SET keys out of the realm JWKS at `/.well-known/jwks.json`, which holds only the keys
  of its access, ID and logout tokens. A resource server that skips the `typ` check therefore cannot take
  a SET for an access token;
- serves stream management under `/ssf/` (see the
  [API reference](/integrate/api-reference/#shared-signals-framework-transmitter)).

## Register a receiver

A receiver is an OAuth client of the realm. It authenticates with its own access token from the
`client_credentials` grant, and the token must:

- carry the `ssf:stream` scope (a token without it gets `403`);
- name the realm's issuer in `aud`, so a token minted for another resource cannot manage streams;
- name no other realm's issuer in `aud`. A `client_id` is unique only within a realm, so such a
  token may come from a client of the same name in that realm. It gets `401`.

Give `ssf:stream` only to clients you trust with the realm's security events. A receiver may add
a user only when the user is related to it, in one of two ways:

- **Its users.** The user holds an active consent for the receiver's client, or a live refresh
  token the client was issued (decided on 2026-10-26). Such a receiver is the client your users
  sign in through, given `client_credentials` and `ssf:stream` as well, with the
  `client_credentials` grant kept to `ssf:stream` (see below).
- **A resource server's users.** The user holds a live refresh token whose audience names the
  receiver as a resource server (decided on 2026-10-31). A receiver is the resource server of the
  values its `audience` lists, the column introspection reads the same way, except a
  `urn:qauth:aud:` value and the realm's issuer: every receiver lists the issuer to manage its
  stream, and the issuer names QAuth itself. A refresh token's audience is what the refresh grant
  gives its access tokens: its RFC 8707 `resource` when it has one, else its client's `audience`,
  else its client's `client_id`.

A refresh token is live as the token endpoint reads it: not revoked, not expired, and its family
not past the realm's `sso_max_lifespan` or the browser session that started it. A disabled user is
related to no receiver, and a client that no user signs in to and that serves no audience can add
no user.

Two grants relate no one. QAuth stores no access token, so a user who holds only access tokens for
a resource server, issued without a refresh token (the user approved without remembering the
decision, so no consent was stored), is not related to it. And a consent's per-resource scopes
(`resource_scopes`) record a grant, not a token: they relate no user to a resource server.

A user subject lasts as long as its relation. The relation is checked when the subject is added,
and again by the `ssf-subject-sweep` job every hour: once the relation has ended (the user
withdrew the consent, the refresh tokens were revoked or ran out, or the user was disabled or
deleted) and every event about the user has reached the stream (delivered, or given up after its
attempts), the job deletes the subject. So the SET that tells of the end, a withdrawn consent's
`token-claims-change` say, still reaches the receiver, and none after it does. The receiver adds
the user again once they are related again. A disablement ends the relation too: after
`account-disabled` reaches the stream the sweep deletes the subject, so `account-enabled` reaches
only a stream the sweep has not cleared yet, and the receiver adds the user again once they are
enabled.

A receiver may add any client of the realm, but a client's own credential changes (its secret, its
API keys) reach only that client's stream. Taking the scope away, disabling or suspending the
client, or deleting it stops its deliveries, and its token stops working on `/ssf/` at once, not
when it expires; deleting the client deletes its stream.

Give the relying party's client `client_credentials`, the `ssf:stream` scope and the realm's issuer
as its audience, beside what its users sign in with, and keep the `client_credentials` grant to
`ssf:stream` with `client_credentials_scopes`, for example as an entry of the seed manifest's
`clients`:

```json
{
  "client_id": "notes-app",
  "name": "Notes",
  "grant_types": ["authorization_code", "refresh_token", "client_credentials"],
  "redirect_uris": ["https://notes.example.com/callback"],
  "scopes": ["openid", "notes:read", "ssf:stream"],
  "client_credentials_scopes": ["ssf:stream"],
  "audience": ["https://auth.example.com"]
}
```

A `client_credentials` token names no user: its `sub` is the client's `client_id`.
`client_credentials_scopes` lists the scopes that grant may issue, out of `scopes`. With
`["ssf:stream"]`, the client gets a token of its own for `ssf:stream` only, and the scopes its
users grant it at sign-in, `openid` and `notes:read` here, reach only the tokens a user granted:
a `client_credentials` request for one of them is refused with `invalid_scope`. The seeder refuses
a list that names a scope `scopes` does not hold, and the list on a client without the
`client_credentials` grant.

A relying party that is a CIMD client (its `client_id` is the URL of its metadata document) gets
the grant from its document, which must declare `client_credentials`,
`token_endpoint_auth_method: private_key_jwt` and a key set. Its scopes and the list come from its
entry in the seed manifest's `cimd_clients`, and without the list the grant issues it no token at
all ([Tokens a CIMD client gets as itself](/operate/docker/#tokens-a-cimd-client-gets-as-itself)):

```json
{
  "client_id": "https://notes.example.com/oauth/client.json",
  "scopes": ["openid", "notes:read", "ssf:stream"],
  "client_credentials_scopes": ["ssf:stream"],
  "audience": ["https://auth.example.com"]
}
```

Every seeder run writes a `cimd_clients` entry's list to the row, without `--rotate`, and a
resolution of the document never changes it.

Keep the realm's issuer the client's only `audience` (without one, the token's `aud` is the
client's `client_id`, which `/ssf/` refuses). The list narrows a `client_credentials` token's
scopes, not its `aud`, which is the client's `audience`: a resource server listed there beside the
issuer finds itself in the `aud` of a token that names no user, and accepts it if it checks only
`aud` and the signature.

The receiver then gets a token:

```bash
curl -s https://auth.example.com/oauth/token \
  -d grant_type=client_credentials -d scope=ssf:stream \
  -d client_id=notes-app -d client_secret="$SECRET"
```

:::caution[Without the list, a client of `clients` gets a token without a user for any of its scopes]
A client of the manifest's `clients` that holds `client_credentials` and has no
`client_credentials_scopes` gets a token for itself, with no user, for any scope in its `scopes`,
each scope its users grant it at sign-in included. Set the list on every such client that signs
users in. (A CIMD client without the list gets no `client_credentials` token.)

Add it to the client's manifest entry. The seeder writes an existing client only with `--rotate`,
which also issues it a new secret; to set the stored row without rotating:

```sql
UPDATE oauth_clients SET client_credentials_scopes = '["ssf:stream"]'
WHERE realm_id = '<realm id>' AND client_id = 'notes-app';
```

A later `--rotate` refuses an entry without the list for a client whose row has one, so the
rotation cannot lift it unnoticed; to lift it on purpose, set the column to `NULL` first.

The token endpoint reads the client row on every request, so the next token request follows the
list, on every node of a release that knows it (a node of an older release ignores the column).
A token issued before keeps its scopes until it expires.
:::

## Create a stream

A receiver has one stream per realm; a second create answers `409`. Delivery is push only, to an
`https` URL on a public address:

```bash
curl -s https://auth.example.com/ssf/stream \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "events_requested": [
      "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
      "https://schemas.openid.net/secevent/caep/event-type/credential-change"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://risk.example.com/ssf/events",
      "authorization_header": "Bearer receiver-shared-secret"
    },
    "description": "Risk engine"
  }'
```

- QAuth checks `endpoint_url` through its egress client when the stream is created or changed: an
  address that is private, loopback, link-local or otherwise not public is refused with `400`
  (`bad_request`, with `endpoint_url is refused` as the `detail`; the reason is in the server's
  log, not in the answer). It checks again at every delivery, so a name that later resolves to
  such an address is refused then too.
- `authorization_header` is sent with every push. QAuth stores it encrypted with the realm's
  `data_at_rest` key and never returns it. A `PATCH` whose `delivery` leaves it out and keeps the
  same `endpoint_url` keeps the stored header, so sending back what a read returned changes
  nothing; a new `endpoint_url` never gets the old header, and a `PUT` replaces it.
- `events_delivered` in the answer is what QAuth will send: the requested events it supports.
  `events_supported` lists them all.

## Add subjects

The transmitter's `default_subjects` is `NONE`: a stream receives events only about the subjects
its receiver adds. Name a user of the realm as `iss_sub` with the realm's issuer, and a client by
its `client_id`, as `uri` when that is a URL and `opaque` otherwise. A user must be related to the
receiver, as above; any other user, and a user id that does not exist, is refused with
`403` (`forbidden`), as SSF 1.0 §8.1.3.2 prescribes for a subject the receiver may not add:

```bash
curl -s https://auth.example.com/ssf/subjects/add \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"stream_id": "'"$STREAM"'", "subject": {"format": "iss_sub", "iss": "https://auth.example.com", "sub": "'"$USER_ID"'"}}'
```

A user's id is a UUID, and QAuth keeps it in lower case, as its SETs name the user: an upper-case
spelling is the same subject. A subject in another format, or with another issuer, is kept as sent
and matches no event. A stream holds at most 1000 subjects.

Some events reach fewer streams than the subject alone would say. A withdrawn consent, an RFC 7009
revocation and a replay's family revocation tell of the user's dealings with one client, and a
client secret or API key change is about one client's credentials, so only that client's stream
receives them. An emergency key retirement reaches every stream of the realm that requested it.

A replay is sent only when it revoked refresh tokens. An authorization code redeemed a second time
whose first redemption issued no refresh token (the user approved without remembering the
decision, so no consent was stored, say) revokes no family: QAuth still puts the access tokens the
code issued on the denylist, so introspection answers `active: false` for them, but no stream
receives a SET. Nor does one for a refresh token presented again after its family was revoked
already.

## Run the verification event

```bash
curl -s https://auth.example.com/ssf/verify \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"stream_id": "'"$STREAM"'", "state": "check-1"}'
```

QAuth answers `204`, records the request as a `ssf.stream.verification_requested` event, and the
delivery role POSTs a SET to the stream's endpoint with `Content-Type: application/secevent+jwt`:

```json
{
  "iss": "https://auth.example.com",
  "jti": "0199f2b4-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
  "iat": 1792927942,
  "aud": "risk-engine",
  "sub_id": { "format": "opaque", "id": "<stream_id>" },
  "events": {
    "https://schemas.openid.net/secevent/ssf/event-type/verification": { "state": "check-1" }
  }
}
```

The header names the signing key (`kid`) and `typ: secevent+jwt`. The `jti` is the event's id,
and a retry sends the same SET, so the receiver drops a duplicate by its `jti`. A second
verification request from the same receiver within 10 seconds (`min_verification_interval`)
answers `429`, even for a stream it deleted and created again.

## Errors

SSF 1.0 gives stream management statuses but no error body, so QAuth answers every refusal on
`/ssf/` and on the metadata the way it answers on every route that is not an OAuth protocol
endpoint: an RFC 9457 problem document, `application/problem+json`, with a stable `code` and the
`trace_id` the server logged the request under ([Problem types](/reference/problem-types/)).
Branch on the status and `code`, never on `detail`:

| Status | `code`                 | When                                                                                            |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------- |
| `400`  | `validation_error`     | The body or the query does not match the schema; `errors` names each field.                     |
| `400`  | `bad_request`          | The protocol refuses the request: poll delivery, a refused `endpoint_url`, a mismatched member. |
| `401`  | `unauthorized`         | The request carries no access token.                                                            |
| `401`  | `invalid_access_token` | The token is not valid, not the receiver's own, or for another audience or realm.               |
| `401`  | `access_token_expired` | The token has expired.                                                                          |
| `403`  | `forbidden`            | The token lacks `ssf:stream`, or the receiver may not add the user it named as a subject.       |
| `404`  | `not_found`            | No such stream for this receiver, or a realm that does not run the transmitter.                 |
| `409`  | `conflict`             | The receiver already has a stream in the realm.                                                 |
| `429`  | `too_many_requests`    | A verification within `min_verification_interval`; `Retry-After` says when to try again.        |

A `401` for a token that was presented carries
`WWW-Authenticate: Bearer realm="OAuth", error="invalid_token"`; one for a request with no token
carries `Bearer realm="OAuth"` alone (RFC 6750 §3.1). A `403` for a token without the scope
carries `error="insufficient_scope", scope="ssf:stream"` (RFC 6750 §3); one for a user the
receiver may not add carries `Bearer realm="OAuth"` alone, since no other token would let it
through. A realm that does not run the transmitter answers exactly what a path no route serves
answers.

## Watch deliveries

`GET /ssf/status?stream_id=…` returns the stream's status and, as QAuth's extension,
`delivery_status`: the deliveries still pending and the latest failed attempt.

```json
{
  "stream_id": "…",
  "status": "enabled",
  "delivery_status": {
    "pending": 1,
    "last_failure": {
      "event_id": "…",
      "attempts": 1,
      "status_code": 503,
      "error": "http_status",
      "time": "2026-10-25T10:00:01.000Z",
      "state": "retrying",
      "next_attempt_at": "2026-10-25T10:00:31.000Z"
    }
  }
}
```

A push is delivered when the receiver answers `2xx`. Any other answer, a timeout or a network
failure is retried on the delivery role's schedule (`EVENT_DELIVERY_*`), except a `400` with an
RFC 8935 `err` that says the SET itself is wrong (`invalid_request`, `invalid_issuer`,
`invalid_audience`, `invalid_state`), which ends the delivery. A `400` without a known `err`,
such as a proxy's error page, is retried. Attempts are counted in
`qauth_events_delivery_attempts_total{kind="ssf"}` (see [observability](/operate/observability/)).

`error` is the class of the failed attempt. An endpoint QAuth refused to reach (a private
address) and one it could not reach both read `destination_unreachable`, so the status does not
tell a receiver which names resolve to private addresses. The delivery history and the server's
log keep the exact class (`destination_blocked` or `network`).

`POST /ssf/status` sets the status. `paused` holds the stream's events, however long the pause.
Holding spends no attempt and records no failure: the delivery role looks at a held delivery
every 30 seconds, and sends it at the first look after the stream is `enabled` again. `disabled`
holds nothing. Deleting the stream ends its pending deliveries without sending them.

A held or retried delivery is sent as the stream is at that attempt, not as it was when the event
was queued: an event the receiver no longer requests, or about a subject it has removed since,
is not sent, and the delivery ends.

A held delivery is pending, so it holds back [event retention](/operate/observability/) as any
pending delivery does: no event of the realm from the oldest held one on is deleted. Disable or
delete a stream rather than leave it paused for good.

## Turning it off

Turning the realm's switch off stops its deliveries: each pending one ends at its next attempt.
Turning `SSF_TRANSMITTER_ENABLED` off leaves pending SSF deliveries in the queue, unsent. They
no longer hold back [event retention](/operate/observability/): with the switch off no node
serves SSF, so retention deletes their events at the realm's retention like any other, and the
deliveries go with them. A delivery whose event is still there when the switch is on again is
sent then. Set the switch the same on every node: a node with it off does not count SSF
deliveries for retention.

## In a distributed deployment

The delivery role reads the streams, the event subject each stream subject stands for, and the
columns that say whether a stream may receive events: `eventDeliveryGrantStatements()` in
`@qauth-labs/infra-db` grants them. It cannot read a subject as the receiver sent it, which may be
an email address or a phone number. It decrypts a receiver's `authorization_header` through the
signer as the `delivery` caller, which may decrypt but never encrypt; it holds no key.

---

# Service roles

URL: https://docs.qauth.dev/operate/service-roles/

The auth server is one codebase that starts as one or more **service roles**
(ADR-019 Decision 8). `SERVICE_ROLES` picks them. The default, `all`, runs
every role in one process: a single deployment, which needs no change and is
one trust domain. A distributed deployment starts each role on its own nodes,
so that a node that faces browsers or API clients holds no KEK and no private
key.

## The roles

| Role       | What the process registers                                                                                                                                                                                                                                                                          | Jobs                                                                                                                                                                                            |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `web`      | The browser-session endpoints: authorize, the sign-in, consent and wallet pages, the consent list and wallet linking.                                                                                                                                                                               | `interaction-expiry`: audits sign-in interactions that expired; `session-expiry`: marks browser sessions past their end; `session-purge`: deletes ended sessions after `SESSION_RETENTION_DAYS` |
| `api`      | Token, introspection, revocation, userinfo, dynamic registration, discovery, JWKS, the OID4VP endpoints a wallet calls, the account and developer APIs, the SSF transmitter and the legacy `/auth` routes.                                                                                          | `purge-expired`: expired codes, tokens and wallet state; `ssf-subject-sweep`: SSF user subjects whose relation ended                                                                            |
| `admin`    | The [admin listener](#the-admin-listener), the admin API's own, while `ADMIN_API_ENABLED` is on (off by default), on `ADMIN_API_HOST` and `ADMIN_API_PORT` (`127.0.0.1`, port `3002`, by default). No admin operation and no key operation has shipped yet, so it serves only its OpenAPI document. | `approval-expiry`: marks approvals for security operations that expired unused, and overwrites their nonce                                                                                      |
| `signer`   | The KEK, every private key and the signer. It runs the default realm's key boot step. While the roles are split, it also runs the [internal listener](#the-internal-listener), with mutual TLS.                                                                                                     | Key rotation, when it ships                                                                                                                                                                     |
| `delivery` | The event delivery reader, which sends the SSF streams.                                                                                                                                                                                                                                             | `event-retention`                                                                                                                                                                               |

Every role answers `/health` (liveness) and `/ready` (the checks its roles
need) for its own process on the public port, and serves its metrics on the
internal listener ([Health and readiness](/operate/observability/#health-and-readiness)).
Write the roles as a comma-separated list, such as `SERVICE_ROLES=web` or
`SERVICE_ROLES=api,signer,delivery`; `all` stands alone.

A process registers only what its roles use:

- the routes of its roles, from the route manifest
  (`apps/auth-server/src/app/route-manifest.ts`);
- the plugins those routes and roles call;
- the database repositories they read and write, and no other: a process
  without the `api` or `web` role never builds the clients repository, nor
  the users repository unless it holds `admin`, whose listener finds the
  admin's account there;
- the jobs placed on its roles. Run every role on at least one node, or its
  jobs never run.

Each role can also connect as a database user of its own, which holds only what
the role's repositories, boot steps and jobs read and write
([#498](https://github.com/qauth-labs/qauth/issues/498)). The migration runner
grants them; [Topology](/operate/topology/#one-user-per-role) shows how. A
process whose only role is `delivery` then skips the default realm's boot step,
since its user may not write `realms`.

## Keys stay on the signer

Only a process whose `SERVICE_ROLES` names `signer`, or is `all`, may hold key
material. Any other process refuses to boot, and names the variable, when one
of these is set:

- `KEK`, `KEK_PATH`, `KEK_PREVIOUS`, `KEK_PREVIOUS_PATH`, any other `KEK_*`
  setting of a KEK provider adapter, or `KEK_PROVIDER` naming an adapter rather
  than `local`;
- any `JWT_*_PRIVATE_KEY*` variable: `JWT_PRIVATE_KEY`, `JWT_RS256_PRIVATE_KEY`,
  `JWT_MLDSA_PRIVATE_KEY` and their `_PATH` forms;
- `OID4VP_VERIFIER_SIGNING_KEY` or `OID4VP_VERIFIER_SIGNING_KEY_PATH`.

A process without the signer reaches the signer service over mutual TLS, so it
needs `SIGNER_URL` (an `https` URL) and the internal TLS files
`INTERNAL_TLS_CERT_PATH`, `INTERNAL_TLS_KEY_PATH` and `INTERNAL_TLS_CA_PATH`,
or it refuses to boot. It needs no public key variable: a process with the
`web` or `api` role verifies each realm's tokens with the keys the realm
publishes in its key store (`realm_public_keys`), public material it reads
without a KEK, so its JWKS and discovery are the signer's own. A process that
holds the signer ignores `SIGNER_URL` and warns.

The check is by variable name. It cannot see the credentials a KEK provider
adapter takes from its cloud SDK's own settings or from the machine's identity:
grant the KMS permission to the signer nodes only. The wallet sign-in holds no
key either: the signer signs its request objects with the realm's OID4VP
request key, which the key boot step imports from
`OID4VP_VERIFIER_SIGNING_KEY` once, and seals each per-request response key
with the realm's `data_at_rest` key (`web` seals, `api` opens). The certificate
chain and its anchors stay public configuration on `web` and `api`.
`OID4VP_RESPONSE_KEY_SECRET` is read only to open the response keys a release
before 0.2 stored with it, which expire within 15 minutes of the upgrade;
remove it once every node runs this release. `SESSION_COOKIE_SECRET` is no
longer a secret of those processes either: the browser cookies are signed with
the realm's cookie key from the signer (below).

## The internal listener

A further HTTP server of the process, the internal listener, serves what only
other parts of the deployment call (ADR-019 Decision 8): a process that holds
`signer` while the roles are split serves the other roles' calls to the signer
service there, and every process serves its metrics there to a scraper while
`METRICS_ENABLED` is on (`GET /internal/metrics`, see
[Observability](/operate/observability/#who-can-read-the-metrics)). It binds
to `INTERNAL_HOST` and `INTERNAL_PORT` (`127.0.0.1`, port `3443`, by default):
set `INTERNAL_HOST` to an address the other nodes and the scraper reach. A
single process (`SERVICE_ROLES=all`) signs in-process and serves the metrics
alone there; without the internal TLS files it serves them in plain HTTP, on a
loopback address only.

With the internal TLS files it serves mutual TLS only, TLS 1.3 and HTTP/1.1:

- `INTERNAL_TLS_CERT_PATH` and `INTERNAL_TLS_KEY_PATH` hold the certificate it
  serves, and `INTERNAL_TLS_CA_PATH` the CA certificates that issue every
  peer's. A client that presents no certificate, or one another CA issued,
  gets no HTTP answer. The CA file must hold only the CA that issues QAuth's
  peers: one that holds a public root CA, as a system bundle does, is refused,
  and one with no certificate marked `CA:TRUE` is warned of. Make the key file
  readable by the server's user only (such as a Kubernetes secret's
  `defaultMode: 0400`): the server warns when its group or others may read it.
- `INTERNAL_PEER_ROLES` maps a subject alternative name (SAN) of a peer's
  certificate to the role the peer calls as, as a JSON object, or to
  `metrics` for a metrics scraper, which may read the metrics and nothing
  else. A key with a `:` is a URI SAN, such as a SPIFFE ID, compared exactly;
  any other key is a DNS SAN, compared without regard to case. Wildcards, IP addresses and the
  `signer` role are refused: the signer serves the listener and never calls
  it. A peer whose certificate holds no mapped SAN, or SANs mapped to two
  roles, gets `403` on every path.
- Each internal route admits only the peer roles its module names: a peer of
  another role gets `403` there.
- The listener reads its three files again every five seconds and serves new
  ones with no restart, once a rotation has written both the certificate and
  its key. A mesh's or a SPIFFE agent's certificates are files like any other,
  so either can issue them.
- The handshake checks a peer's certificate once per connection, so each
  request checks again: a request on a connection whose peer certificate has
  expired since, or that was made before the files were last reloaded (a CA
  replaced among them), gets `403`. Every `403` closes its connection, and the
  peer connects again under the files served then.
- It holds at most 1024 connections at once.

A process whose roles are split refuses to start, naming each setting, when
the three files or `INTERNAL_PEER_ROLES` are missing: neither the signer nor
the metrics are served without mutual TLS there. Map a scraper's SAN to
`metrics`, or set `METRICS_ENABLED=false` on a process no scraper reads. `INTERNAL_PORT` must differ from `PORT`, and from `ADMIN_API_PORT` where
the admin API runs. Every internal route sits under `/internal/`, and the
public listener serves none of them. The listener is not routed by host: an
internal route takes the realm from the request, not from the `Host` header.

The admin API keeps [its own listener](#the-admin-listener) and its own rule:
a peer certificate grants nothing there.

Until the signer service ships, `web` must sit with the signer: the settings
of the split that works today, with the internal listener, are in
[What a split deployment can do today](#what-a-split-deployment-can-do-today).

## What a split deployment can do today

The internal listener runs, but the signer service it is for is not built
yet (#497): no signer route answers on it. Until it is, a process without the
signer cannot sign anything, and warns at boot:

- a request that needs a signature, an encryption or a cookie secret, such as
  token issuance, an ID-JAG assertion, or a browser page that reads or sets a
  signed cookie (the sign-in, consent and wallet pages), answers `503` with
  `temporarily_unavailable`;
- an event delivery waits: the `delivery` role holds it without spending an
  attempt and offers it again every 30 seconds, until a signer answers;
- a mail of a realm whose transport needs a stored secret (`mail.smtp.password`
  or `mail.resend.apiKey`) is not sent, since the secret is decrypted through
  the signer: the request answers as it would otherwise, and the log names the
  realm. Send such mail from a process that holds the signer.

Token verification (with each realm's published keys), the realm JWKS,
`/ssf/jwks.json`, discovery and the endpoints that sign nothing keep working.
Hybrid signing (`HYBRID_SIGNING_ENABLED=true`) describes what the signer
issues, so every process of a hybrid deployment sets it: a process without the
signer verifies hybrid tokens with the realm's published ML-DSA-65 keys, and
answers `503` when asked to sign one.

The browser cookies are signed with the realm's cookie key, which only the
signer hands out (#493), so the browser-facing role needs a signer as much as
the roles that sign tokens do. So the split that works today keeps `web` with
every signing role, and only `admin`, which signs nothing, apart:

```bash
# The nodes that sign and serve the browser: the KEK and the private keys live
# here only, and the internal listener serves the other nodes over mutual TLS.
SERVICE_ROLES=web,api,signer,delivery
KEK_PATH=/run/secrets/qauth-kek
JWT_PRIVATE_KEY_PATH=/run/secrets/qauth-ed25519.pem
INTERNAL_HOST=0.0.0.0
INTERNAL_TLS_CERT_PATH=/run/secrets/signer.crt
INTERNAL_TLS_KEY_PATH=/run/secrets/signer.key
INTERNAL_TLS_CA_PATH=/run/secrets/internal-ca.crt
INTERNAL_PEER_ROLES={"spiffe://example.org/qauth/admin":"admin","spiffe://example.org/prometheus":"metrics"}

# Admin nodes: no KEK, no private key. Their certificate holds the SAN
# spiffe://example.org/qauth/admin, which the signer's nodes map to admin.
# Their own internal listener serves their metrics to the scraper.
SERVICE_ROLES=admin
SIGNER_URL=https://signer.internal:3443
INTERNAL_HOST=0.0.0.0
INTERNAL_TLS_CERT_PATH=/run/secrets/admin.crt
INTERNAL_TLS_KEY_PATH=/run/secrets/admin.key
INTERNAL_TLS_CA_PATH=/run/secrets/internal-ca.crt
INTERNAL_PEER_ROLES={"spiffe://example.org/prometheus":"metrics"}
```

Once the signer service ships (#497), a `web` node without the KEK gets the
cookie keys from it and keeps them in memory, reading them again every minute.

Wallet sign-in builds its signed request on the node that serves
`/ui/wallet-login`, a `web` node, which may not hold the verifier key: a
profile that signs its requests cannot offer wallet sign-in on a split
deployment until the signer service ships. Route browser paths
(`/oauth/authorize`, `/ui/*`, `/consents`, `/auth/link/wallet`, and
`GET /auth/verify`, the email verification page) to the `web` nodes and every
other path to the others at the reverse proxy. `POST /auth/verify` is the
API's and stays on `api`: route `/auth/verify` by method. The pages' stylesheet
and fonts, under `/assets/ui/`, are `api`'s too, like the discovery documents:
they are not browser paths, and the pages on the `web` nodes link them.

The `web` and `api` roles read the session cookie (`api` for `/auth/logout`),
with the realm's cookie key from the signer (#493). Only the browser-facing
role receives the cookie keys from a signer service (ADR-019 Decision 9): on a
process that cannot read them, `/auth/logout` still ends the user's sessions and
tokens, and leaves the request's cookie for the next page to clear.
`SESSION_COOKIE_SECRET` is optional on every process: only the key boot step, on
a process that holds the signer, reads it, to import it into the default realm's
key store or to replace the stored cookie key with it. `NODE_ENV=production`
refuses every value QAuth's examples published, on every process.

With `ENABLE_SWAGGER` on, only a process holding `api` serves the Swagger UI
and its spec under `/docs`.

## The admin listener

A process holding `admin` runs the admin API on a second listener, beside the
public one, while `ADMIN_API_ENABLED` is on. It is off by default. The listener
binds to loopback by default.
Every admin call carries a DPoP-bound admin token and a proof for
`ADMIN_API_BASE_URL` followed by the call's path (#520), so where the listener
runs, the boot requires `ADMIN_API_BASE_URL`, the URL clients address the admin
API at, and `DPOP_ENABLED=true`; a process that runs the token endpoint needs
`DPOP_ENABLED=true` too, to issue admin tokens. The listener may then sit on
any address, behind a load balancer that terminates TLS and forwards to
`ADMIN_API_HOST` and `ADMIN_API_PORT`: a proof binds an admin call to its
method and URL, not to its body, so in production `ADMIN_API_BASE_URL` must be
`https`, unless both it and `ADMIN_API_HOST` name loopback, for a listener
reached from the machine alone. It grants nothing for a caller's network position: every
admin call needs a DPoP-bound admin token, except
`GET /admin/v1-rc.0/openapi.json`
([API conventions](/reference/api-conventions/#the-admin-listener)). The public
listener never serves the admin API. `ADMIN_API_PORT` must differ from `PORT`.

## See also

- [Configuration](/operate/configuration/): every key, `SERVICE_ROLES` among
  the stable ones.
- [Keys](/operate/keys/): the key store and the KEK.
- [Reverse proxy](/operate/reverse-proxy/).

---

# Accounts

URL: https://docs.qauth.dev/operate/accounts/

An operator disables an account to stop whoever holds it, for example after
the account was taken over. The admin API has no operation for that yet, so
this page uses the operator tool, which talks to the database directly. An
operator also verifies an account that cannot confirm its address
([Verify an account](#verify-an-account)): through the admin API, or on the
server host where no admin API is set up.

## What disabling does

A disabled account cannot sign in and is issued no token. Everything it
already holds stops working at its next use:

- its browser sessions: the hosted pages send the browser to sign-in;
- its refresh tokens and authorization codes: `/oauth/token` answers
  `invalid_grant`;
- its access tokens: introspection reports them inactive, `/oauth/userinfo`
  answers `401`, and the developer API and token exchange refuse them.

The account keeps its credentials, consents and clients. Signing out still
works.

## After a takeover

Disabling ends what the account holds, not what whoever took it changed or
added. Enabling the account gives that back with it. Before you enable an
account that was taken over:

1. Find what the account did since the takeover. Its events name it, such as
   `wallet.linked`, `client.created`, `client.secret_rotated` and
   `api_key.created` ([Events](/reference/events/)):

   ```sql
   SELECT to_timestamp(time / 1000.0) AS at, type, subject_type, subject_id, client_id
   FROM events
   WHERE actor_id = '<user id>' AND time >= <takeover time, epoch ms>
   ORDER BY time;
   ```

2. Replace the password. QAuth has no password reset yet
   ([#642](https://github.com/qauth-labs/qauth/issues/642)): an account taken
   over with its password signs in with it again once it is enabled, so keep
   such an account disabled until its password can be replaced.
3. Remove every credential added since the takeover, such as a linked wallet.
   List the account's credentials and delete those you did not expect:

   ```sql
   SELECT id, provider_type, to_timestamp(created_at / 1000.0) AS added
   FROM user_credentials
   WHERE user_id = '<user id>'
   ORDER BY created_at;

   DELETE FROM user_credentials WHERE id = '<credential id>';
   ```

4. Suspend every client the account created since the takeover, and every
   client whose secret it rotated or to which it added an API key. A client
   lives on while its developer is disabled, and its secret and keys with it:

   ```sql
   SELECT c.client_id, to_timestamp(c.created_at / 1000.0) AS created
   FROM oauth_clients c
   WHERE c.developer_id = '<user id>'
   ORDER BY c.created_at;

   SELECT c.client_id, k.name, to_timestamp(k.created_at / 1000.0) AS created
   FROM api_keys k
   JOIN oauth_clients c ON c.id = k.client_id
   WHERE k.developer_id = '<user id>' AND k.revoked_at IS NULL
   ORDER BY k.created_at;
   ```

   ```bash
   DATABASE_URL=postgresql://qauth:pw@db:5432/qauth \
     pnpm nx run infra-db:db:suspend-oauth-client -- --realm=<realm name> --client-id=<client_id>
   ```

   Once the owner has signed in again, they rotate the secret
   (`POST /api/clients/:id/regenerate-secret`) and revoke the keys
   (`DELETE /api/clients/:clientId/api-keys/:keyId`) through the developer
   API, or delete a client they did not create. Then lift the suspension of
   the clients they keep, with `--lift`.

## Enabling an account again

Enabling an account lets its holder sign in again. It does not bring back what
was issued before the account was disabled: every browser session, refresh
token, authorization code and access token from before stays refused, whether
or not anyone used it while the account was disabled. Whoever held one,
the account's owner or someone who took it, must sign in. A refresh token
counts from the start of its family, the code exchange or sign-in that issued
its first token, so a rotation does not make it newer; an authorization code
counts from the sign-in behind it. An access token from before cannot sign the
owner out of the sessions started since.

The account records the time it was last disabled, `users.not_valid_before`
(epoch milliseconds, from the database's clock). Disabling sets it to the
time the disabling transaction commits: until then the account still reads as
enabled, and what it is issued meanwhile counts as issued before. The time is
taken just before the commit, so a commit that then waits, for a synchronous
standby for example, leaves the account readable as enabled a little longer
than the time says. Enabling
never clears it, and the database refuses an update that clears it or moves
it back. A session or token issued up to one second after that time counts
as issued before it, and an access token, whose issue time is kept to the
whole second, up to two seconds after. The margin allows for times kept to
the second and for a skew between the auth server's clock and the database's
of less than a second. Nothing is issued to a disabled account, so the margin
only matters for an account enabled again within those seconds.

Keep every auth server node's clock and the database's synchronised, for
example with NTP. A browser session's issue time is the node's clock, and the
disablement's time the database's: on a node whose clock runs more than a
second ahead of the database, a session issued just before the disablement
counts as issued after it, and survives the account being enabled again.

An ID-JAG assertion (the `jwt-bearer` grant) carries the issue time of the
identity provider that signed it, whose clock may run up to
`ID_JAG_CLOCK_SKEW_LEEWAY` (60 seconds by default) ahead of QAuth's, as its
validation allows. It counts as issued that much before its `iat`: an
assertion issued within that leeway after the disablement is refused too.

The margin bounds what slips through. A sign-in or a code exchange takes the
issue time of the session or the refresh family it starts before it reads
the account, so one whose read came before the disabling commit counts as
issued before it. An access token is signed after that read: one whose request
read the account as enabled before the commit, and was signed more than two
seconds after the time, survives the account being enabled again, until it
expires. A commit that waits more than a second for a synchronous standby
has the same effect on what is issued meanwhile. A database superuser or the
owner of the `users` table can turn the triggers off; QAuth does not guard
against them.

### Accounts from before the upgrade

Migration 0044 adds the column. An account that is disabled when it runs was
disabled at a time nothing recorded, so it gets the time of the migration:
nothing is issued to a disabled account, so everything it holds is older, and
stays refused once the account is enabled.

An account that was disabled and enabled again before the upgrade gets no
time: the migration finds it enabled, and nothing recorded that it was ever
disabled. The previous release brought back every browser session and refresh
token that nobody used while it was disabled, and they keep working after the
upgrade. For each account you enabled again after a takeover before
upgrading, once every node runs this release, disable the account with the
tool (`db:disable-user`), take the steps of [After a takeover](#after-a-takeover),
and enable it again (`db:disable-user --enable`). Disabling records the time
now and ends every session and token the account holds: whoever holds one,
its owner included, signs in again.

During a rolling upgrade, a node of the previous release still checks only
whether the account is enabled. Once the account is enabled again, such a node
accepts the account's old browser sessions and access tokens. Nodes of this
release refuse the refresh tokens it rotates from an old family and the codes
it mints from an old session. But from an old session it can also run a whole
code exchange, and the new refresh family that starts works at every node
until it ends, as does any access token such a node mints until it expires.
Enable an account that was disabled for a takeover only after every node runs
this release.

## Disable or enable an account

Find the user's id. For a password account, by the address it signs in with:

```sql
SELECT c.user_id
FROM user_credentials c
JOIN realms r ON r.id = c.realm_id
WHERE r.name = '<realm name>'
  AND c.provider_type = 'password'
  AND c.external_sub = lower('<address>');
```

From a checkout of the release you run, with dependencies installed, on a host
that holds the database credentials:

```bash
DATABASE_URL=postgresql://qauth:pw@db:5432/qauth \
  pnpm nx run infra-db:db:disable-user -- --realm=<realm name> --user-id=<user id>
```

Add `--enable` to enable the account again. The tool changes the account and
writes the event in one transaction, and prints the time before which sessions
and tokens stay refused. It changes nothing for an account that is already in
the state you ask for, or for a realm or a user it does not find, and says so.

| Event                                                                 | When                         |
| --------------------------------------------------------------------- | ---------------------------- |
| [`user.disabled`](/reference/events/#userdisabled-v1-rc0) (`warning`) | The tool disabled an account |
| [`user.enabled`](/reference/events/#userenabled-v1-rc0) (`info`)      | The tool enabled it again    |

Both are admin events, in the realm's hash chain, with the operating-system
user who ran the tool as the actor. The [SSF transmitter](/operate/ssf-transmitter/)
sends them as RISC 1.0 `account-disabled` and `account-enabled` to each stream
that requested them and has the user as a subject
([SSF events](/reference/ssf-events/)).

`UPDATE users SET enabled = false WHERE id = '<user id>'` by hand disables the
account just as well, and the database records the time the same way, but no
event is written. Use the tool.

## Verify an account

A realm that requires verified accounts (`accounts.requireVerifiedAccount`)
signs a password account in only once its address is confirmed, by the code
mailed to it. A deployment that cannot send mail, or an account whose mailbox
is gone, has another way: an operator verifies the account
([ADR-015](/reference/records/adr/015-agent-tree-hardening/), Decision 8, as
amended 2026-11-08). The verification:

- counts wherever QAuth asks for a verified account: signing in where the
  realm requires one, and owning an agent;
- claims the account if it is unclaimed: it is the operator's attestation, so
  another person's later mailbox proof of the address no longer ends the
  account;
- leaves `email_verified` as it is. The address stays unconfirmed, and QAuth
  asserts no address it did not confirm;
- does not open a password reset by mail while the address stays
  unconfirmed: the operator attested the account, not the address, so the
  mailbox's holder need not be the person verified. A reset code for it is
  answered as a wrong one;
- is recorded on the account with the operator who made it, and kept: an
  account an operator verified is not verified again;
- is refused for a disabled account, and for an account the realm does not
  hold (a deleted one).

### Through the admin API

`users.verify` is a security operation: it needs the permission
`users.security`, so a token with `qauth:admin:security`, and an approval
([security operations](/reference/security-operations/)). File the approval
with the account in `params` and an empty body. The approver sees the
account, its credentials with the proof each holds, and the reason you give:

```http
POST /admin/v1-rc.0/realms/<realm id>/approvals
Content-Type: application/json

{ "operation": "users.verify", "params": { "userId": "<user id>" }, "body": {},
  "reason": "No mail transport; the owner confirmed by phone." }
```

Once it is approved, send the verification with the approval:

```http
POST /admin/v1-rc.0/realms/<realm id>/users/<user id>/verification
Content-Type: application/json
If-Match: *
QAuth-Approval: <approval id>

{}
```

It answers the verification, with you as `verifiedBy`. The approval holds
only for the account as it stood when the approval was filed: when a
credential is added, removed or proved in between, it no longer matches, and
you file a new one. A disabled account, and one an operator already verified,
are refused with `409`.

### On the server host

A deployment with no admin API set up yet (no admin listener, or no admin
with a passkey to approve with) runs the migration runner's `verify-account`
command, on a host that holds the database credentials, as it runs the
[migrations](/operate/upgrades/):

```bash
docker compose run --rm migration-runner verify-account --realm <realm name> --user <user id>
```

The command runs only on a database whose migrations are all applied. It
records the verification and its event in one transaction, with the
operating-system user that ran it as the operator, and prints what it did.

| Exit | Meaning                                                                             |
| ---- | ----------------------------------------------------------------------------------- |
| `0`  | The account is verified now, or an operator verified it before (that is kept)       |
| `1`  | Migrations are pending: run the migration runner first. Nothing was changed         |
| `2`  | The arguments are wrong, or `DATABASE_URL` is not set                               |
| `3`  | The command could not run: the database unreachable, or the migrations unreadable   |
| `6`  | The realm holds no such account, there is no such realm, or the account is disabled |

| Event                                                                 | When                            |
| --------------------------------------------------------------------- | ------------------------------- |
| [`user.verified`](/reference/events/#userverified-v1-rc0) (`warning`) | An operator verified an account |

It is an admin event, in the realm's hash chain. Its `method` is `operator`
for `users.verify`, with the admin as its actor, and `operator_cli` for the
command, with the operating-system user as its actor.

During a rolling upgrade from 0.2, a node of 0.2 does not read the
verification: it still asks the account for its mailbox code. Verify accounts
once every node runs this release.

---

# Sandbox realm

URL: https://docs.qauth.dev/operate/sandbox-realm/

A live realm can have one **paired sandbox realm**. The sandbox is a realm in its own right, with
its own host, issuer, keys and passkey RP ID. Its environment ceiling is `staging`, so the developer
portal's flow test console works there while the live realm stays at `production`. The design is
[ADR-019 Decision 11](/reference/records/adr/019-deployment-topology-and-trust-boundaries/) and
[ADR-020 §4](/reference/records/adr/020-ui-surfaces-and-acceptance-criteria/).

## What the sandbox shares, and what it does not

The sandbox runs in the same deployment as its live realm. It shares what the deployment holds:

| Shared with the live realm            | Why                                                                                                                          |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| The database                          | Every realm's rows live in one database; each row names its realm, and every read is scoped to one.                          |
| The KEK                               | The sandbox's keys are wrapped with the deployment's key-encryption key, as every realm's are ([Keys](/operate/keys/)).      |
| The signer role                       | The same signer process holds both realms' keys and signs for each with that realm's own keys.                               |
| The trust domain                      | Whoever operates the deployment operates the sandbox. A sandbox is for testing configuration, not for isolating an attacker. |
| The deployment's environment switches | Process-wide variables, such as the listeners and the KEK provider, apply to every realm.                                    |

It shares nothing that belongs to a realm:

| Its own                   | What that means                                                                                                                                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Host                      | The sandbox has a primary host of its own. Hosts are unique across all realms, the sandbox twins included, so the sandbox's host is never the live realm's. You provision its DNS and TLS like any realm host.                       |
| Issuer                    | Its issuer is on its own host and is permanent, as every realm's is. Discovery and the JWKS at the sandbox host describe the sandbox.                                                                                                |
| Keys                      | It gets its own token signing keys (RS256 as well, as a new realm does), cookie key, event signing key and data-at-rest key when it is created. No key of the live realm is copied or shared.                                        |
| Passkey RP ID             | Its RP ID is its own host. A passkey enrolled for the live realm does not work in the sandbox.                                                                                                                                       |
| Users and sessions        | It starts with no users. A user of the live realm cannot sign in to the sandbox: realm isolation keeps every account in the realm that created it. Create test users in the sandbox.                                                 |
| Clients, consents, grants | It starts with none. Register the clients you test with in the sandbox.                                                                                                                                                              |
| Policies                  | It is seeded from the environment's defaults, like any new realm, and copies nothing from the live realm. Two values differ from the seeds: the environment ceiling is `staging`, and the mail transport is `mock`, which only logs. |
| Secrets                   | None is copied. Live secrets stay on the live realm.                                                                                                                                                                                 |
| Upstream providers        | Configure them with test accounts of the provider. That is configuration, not code.                                                                                                                                                  |

## The environment ceiling

A sandbox's ceiling (`posture.maxEnvironmentLaxity`, see
[Environment-aware authorization](/operate/environment-authorization/)) is `staging` when it is
created. A client is always held to the stricter of its own environment and the ceiling, so:

- a sandbox client set to `development` runs with the `staging` profile: PKCE required, https
  redirect URIs only, no static API keys, refresh-token rotation, lenient rate limits;
- a sandbox client set to `staging` or `production` keeps its own profile.

The ceiling can be tightened to `production`, and set back to `staging`. It can never be
`development`: the database refuses the value whoever writes it, and the server's realm policy
update answers a request for it with `422` and the problem type
[`sandbox_ceiling`](/reference/problem-types/#sandbox-ceiling). The admin API operation that updates
a realm's policies, `realms.policies.update`, calls that update.

## Tokens

A token the sandbox issues names the sandbox's issuer and is signed with the sandbox's keys. A
resource server of the live realm checks the issuer, as every resource server must, so it refuses a
sandbox token. No claim marks a token as a sandbox token: a same-issuer sandbox flag was rejected,
because every resource server would have to check it, and one that forgot would accept sandbox
tokens.

## Rules the database holds

Migration 0056 adds `realms.sandbox_of_realm_id`, which names a sandbox's live realm. The rules
hold for every writer, a hand-written SQL statement included:

| Rule                                                                               | Held by                                                 |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------- |
| A live realm has at most one sandbox.                                              | the unique index `idx_realms_sandbox_of_realm_id`       |
| A realm is not its own sandbox.                                                    | the CHECK `realms_sandbox_not_self`                     |
| A sandbox has no sandbox.                                                          | the trigger `realms_sandbox_pairing`                    |
| A sandbox's live realm exists before the sandbox, not later in the same statement. | the trigger, and the foreign key                        |
| The operator realm is no sandbox and has none.                                     | the CHECK `realms_sandbox_not_operator` and the trigger |
| The pairing is set when the sandbox is created and never changes.                  | the trigger                                             |
| A sandbox's ceiling is never `development`.                                        | the CHECK `realms_sandbox_ceiling`                      |
| A live realm cannot be deleted while its sandbox exists. Delete the sandbox first. | the foreign key, `ON DELETE RESTRICT`                   |

Because the operator realm has no sandbox, a deployment in single-realm simple mode, where the
default realm is also the operator realm, has none either. A sandbox needs a live realm of its own,
next to the operator realm
([ADR-019 Decision 1](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)).

One check reads rows other than the one written: moving the operator flag onto a realm looks for
that realm's sandbox. In a `REPEATABLE READ` transaction it looks in the transaction's snapshot,
which a sandbox committed in the meantime is not in. Move the operator flag by hand only under
`READ COMMITTED`, as the server does, under its realm provisioning lock.

## Creating a sandbox

The server creates a sandbox in one transaction: the realm and its primary host from the issuer you
choose, the pairing and the `staging` ceiling, its policies with the test mail transport, and its
keys. Either all of it is stored, or none of it.

The admin API operation that creates a sandbox and reads the pairing comes with the realm lifecycle
operations (#694). Creating a realm is a security operation. Until that operation ships, a sandbox
is created only from the server's code (`createSandboxRealm`). The admin API's realm representation
(`realms.get`) shows the pairing as two read-only fields: `sandboxOf`, the live realm's id on a
sandbox, and `sandbox`, the sandbox's id on a live realm; each is `null` otherwise.

Moving settings from the sandbox to the live realm goes through the realm file's diff, where fields
that describe the sandbox's environment (its ceiling, `http` redirect URIs, test upstreams, test
webhook receivers) move only when selected one by one. That comes with the realm file import.

---

# Clients

URL: https://docs.qauth.dev/operate/clients/

The admin API manages every client of a realm, whoever owns it: a
developer's, one the operator provisioned, one that registered itself. The
developer API still lists and changes a developer's own clients only. Every
route below is experimental and lives on the admin listener
([Service roles](/operate/service-roles/)).

| Route                                                        | Operation         | Needs                              |
| ------------------------------------------------------------ | ----------------- | ---------------------------------- |
| `GET /admin/v1-rc.0/realms/<realm id>/clients`               | `clients.list`    | `clients.read`                     |
| `GET /admin/v1-rc.0/realms/<realm id>/clients/<id>`          | `clients.get`     | `clients.read`                     |
| `POST /admin/v1-rc.0/realms/<realm id>/clients`              | `clients.create`  | `clients.security` and an approval |
| `PATCH /admin/v1-rc.0/realms/<realm id>/clients/<id>`        | `clients.update`  | by field, as the table below says  |
| `POST /admin/v1-rc.0/realms/<realm id>/clients/<id>/preview` | `clients.preview` | `clients.read`                     |
| `DELETE /admin/v1-rc.0/realms/<realm id>/clients/<id>`       | `clients.delete`  | `clients.security` and an approval |
| `POST /admin/v1-rc.0/realms/<realm id>/clients/<id>/disable` | `clients.disable` | `clients.write`, or as below       |
| `POST /admin/v1-rc.0/realms/<realm id>/clients/<id>/enable`  | `clients.enable`  | `clients.security` and an approval |

`<id>` is the client's `id`, a UUID, not its `client_id`. A client of another
realm answers `404`, as one that does not exist. No answer carries the
client's secret or its hash, and a key set shows its public members only: a
change or registration that sends a private member of a key (`d`, `p`, `k`
and the rest) answers `400`.

## Read the clients

`clients.list` answers every client of the realm, newest first, one page at a
time (`limit`, `cursor`). `q` keeps the clients whose `client_id` or name
holds the text, case ignored. `clients.get` answers one client with its
`ETag`, which a change, a suspension, a deletion and lifting a suspension
name in `If-Match`.

## Change a client

A change is a JSON Merge Patch (RFC 7396) with `Content-Type:
application/merge-patch+json` and the client's `ETag` in `If-Match`. `null`
gives a field its default; `name`, `tokenEndpointAuthMethod` and
`grantTypes` have none. The change is judged field by field, on the client
the patch makes:

| A change of                                                          | Needs                              |
| -------------------------------------------------------------------- | ---------------------------------- |
| the name, the description, `backchannelLogoutSessionRequired`        | `clients.write`                    |
| a scope removed or added, a grant type or response type removed      | `clients.write`                    |
| a stricter environment, PKCE or DPoP switched on, a shorter lifetime | `clients.write`                    |
| the redirect URIs, the post-logout redirect URIs                     | `clients.security` and an approval |
| the authentication method, `jwks`, `jwksUri`                         | `clients.security` and an approval |
| first-party trust, the verified domain, the agent fields             | `clients.security` and an approval |
| a grant or response type added, a `qauth:` scope added               | `clients.security` and an approval |
| a back-channel logout URI set, the `client_credentials` list widened | `clients.security` and an approval |
| a laxer environment, PKCE or DPoP switched off, a longer lifetime    | `clients.security` and an approval |

A patch of both kinds needs both permissions, and one approval. Every patch
needs `clients.read` too: it answers the client.

A client that holds a `qauth:admin:*` scope obtains admin tokens: whoever
changes it changes who administers the realm. Every change of one, a
narrowing too, needs `clients.security` and an approval, and so does
suspending it.

A member the patch does not name is left as stored, even where the rules of
a new registration would write it otherwise. A member the patch names may
change another: removing first-party trust clears its policy and reason.
Each such change is judged as its own. The generated
[security operations](/reference/security-operations/) page lists each
operation's effects.

`clients.preview` takes the same patch and answers what the save would
change and need, without saving it: each field before and after, which way
it moves, its class, and whether the save needs an approval. File the
approval with the client's id in `params` and the patch as the body, then
send the patch with the approval:

```http
POST /admin/v1-rc.0/realms/<realm id>/approvals
Content-Type: application/json

{ "operation": "clients.update", "params": { "clientId": "<id>" },
  "body": { "redirectUris": ["https://app.example.com/callback"] },
  "reason": "The app moved to its new host." }
```

```http
PATCH /admin/v1-rc.0/realms/<realm id>/clients/<id>
Content-Type: application/merge-patch+json
If-Match: "<etag>"
QAuth-Approval: <approval id>

{ "redirectUris": ["https://app.example.com/callback"] }
```

The approval holds only for the client as it stood when it was filed: any
change in between answers `412`.

An approver is shown every change whole: a list as each entry it removes and
adds, a key set as each key, any other field beside the value it replaces.
A change that needs approval and cannot be shown that way answers `422`
before it is filed: a value longer than one line of an approval shows (about
1000 characters), or more lines than the 50 an approval holds, the
client's name and owner among them. File it as smaller changes.
A registration answers `400` for the same reason. Removing first-party trust revokes every
refresh token of the client.

### Token lifetimes

`accessTokenLifespanSeconds` and `refreshTokenLifespanSeconds` give a client
lifetimes of its own, shorter than the realm's (`422` for a longer one);
`null` takes the realm's. A move to another environment is checked against
the lifetimes of that environment's tier. The token endpoint issues the shorter of the two,
so a client never outlives a realm whose lifetimes were shortened after it.

### A CIMD client

A client registered from a Client ID Metadata Document takes its settings
from that document, and every resolution rewrites them. A change, a preview
and a deletion of one answer `409`, naming the document: change the
document. A CIMD client can still be suspended and enabled.

## Register a client

`clients.create` registers a client no developer owns, provisioned by the
operator: the server makes its `id` and `client_id`, and for
`client_secret_basic` and `client_secret_post` its secret, which the answer
carries once, as `clientSecret`. The body takes the same fields as a patch;
`name`, `tokenEndpointAuthMethod` and `grantTypes` are required. The checks
of every registration path apply, the first-party rules and the lifetimes
too.

## Suspend, enable and delete

`clients.disable` suspends the client: it obtains no token, and its owner
cannot lift the suspension. It only takes tokens away, so it needs no
approval, unless the client obtains admin tokens (above). It names the
client's `ETag` in `If-Match`, so the approval of such a suspension holds for
the client it was filed for. `clients.enable` lifts the suspension, and
switches on a client no developer owns; a developer's own switch stays
theirs. It needs an approval, as `clients.delete` does, which removes the
client with its authorization codes, refresh tokens, consents and API keys.

The seed manifest writes a client it provisions again on each run, and the
server gives each realm's system client what it needs as it boots: change
such a client in the manifest, or the next run may undo an admin's change.

Each change records the client's events with the admin as their actor:
`client.created` (registration `admin_api`), `client.updated`,
`client.deleted`, `client.suspended`, `client.suspension_lifted`,
`client.first_party_changed` and `client.verified_domain_changed`
([Events](/reference/events/)).

---

# Extend

URL: https://docs.qauth.dev/extend/

This lane is for contributors working on QAuth itself.

If you are about to change the codebase, read these in order:

1. [Repository map](/extend/repo-map/) — the `apps/` and `libs/` layout, the Nx scope tags that
   decide where new code may live, and the Windows CRLF gotcha worth knowing on day one.
2. [Request lifecycle](/extend/architecture/) — how `apps/auth-server` boots, which registration
   orders are load-bearing, and the two security invariants a change can silently undo.
3. [Testing](/extend/testing/) — the tiers, what each one cannot catch, and the caching failures
   this repo has already had.
4. [Adding a credential provider](/extend/adding-a-credential-provider/) — the ADR-003 extension
   point, which is the main way this server is meant to grow.
5. [Adding an admin operation](/extend/adding-an-admin-operation/) — the five steps every admin API
   operation takes, with the realm operations as the worked example.

[Frontmatter contract](/extend/frontmatter/) covers this documentation site itself; read it before
adding a page.

---

# Frontmatter contract

URL: https://docs.qauth.dev/extend/frontmatter/

Every page in this docs site's `docs` content collection sets the same frontmatter fields.
The schema for these fields lives in `apps/docs-site/src/content.config.ts`, which extends
Starlight's built-in `docsSchema()` via its `extend` option.

## Fields

| Field           | Required         | Meaning                                                                       |
| --------------- | ---------------- | ----------------------------------------------------------------------------- |
| `title`         | yes — schema     | Page title; also the sidebar label.                                           |
| `lastVerified`  | yes — schema     | ISO date (`YYYY-MM-DD`) the page's claims were last checked against the tree. |
| `description`   | yes — convention | One sentence; used for the meta description and search.                       |
| `sidebar.order` | yes — convention | Position within its lane. Pages sort by this value, ascending.                |
| `unbuiltClaims` | no               | Declares that this page intentionally describes something not yet built.      |
| `experimental`  | no               | Marks the page that documents an experimental item; shows the banner.         |

Only two fields are enforced by a schema: Starlight requires `title`, and this project's
`extend:` requires `lastVerified` — omit either and the build fails. `description` and
`sidebar.order` are **optional** in Starlight's schema (`index.mdx` sets no `sidebar` block at all
and builds fine); they are required here by convention, and nothing mechanical enforces them.

`title`, `description`, and `sidebar.order` come from Starlight's own schema. `lastVerified`,
`unbuiltClaims` and `experimental` are added by this project's `extend:` — without that extension,
Zod would silently strip them from frontmatter instead of validating them.

## Quote `lastVerified`

YAML parses a bare `2026-07-26` as a date object, not a string, and the schema requires a
string — an unquoted value fails the build. Always quote it:

```yaml
# Wrong — parses as a Date, fails the schema
lastVerified: 2026-07-26

# Right — a string
lastVerified: '2026-07-26'
```

## `lastVerified` is recorded, not enforced

The schema requires every page to _set_ `lastVerified`; a page with no `lastVerified` field
fails the build. What the schema does not do is check whether the date is still accurate. A
staleness threshold — failing CI once a page's `lastVerified` passes some age — would break
unrelated pull requests for a problem they didn't cause, so there isn't one. Instead, the
Reference lane's status page surfaces the oldest `lastVerified` date across the site, so rot is
visible rather than silently accumulating. Do not turn this into a hard gate later: recording
the date and enforcing its freshness are deliberately different jobs.

## The `unbuiltClaims` marker

A guard fails any page that claims a feature is deferred, not implemented, or coming soon when
that feature's module or flag already exists in the tree — the guard's job is to catch
documentation that has drifted behind the code. Two pages legitimately need to describe
something unbuilt anyway: a specification for endpoints that don't exist yet, and honest notes
about a surface that is currently thin. Setting `unbuiltClaims: true` in a page's frontmatter
tells the guard to skip that page.

```yaml
---
title: Example
description: An example of the marker.
sidebar:
  order: 1
lastVerified: '2026-07-26'
unbuiltClaims: true
---
```

This is a narrow, page-level escape hatch for that one specific check, not a general-purpose
way to silence it. Reaching for `unbuiltClaims: true` because a guard failure is inconvenient,
on a page that isn't actually describing something unbuilt, is a defect — file it as one if you
see it.

## The `experimental` flag

An experimental item ships outside the stability promise, and the docs label it (ADR-018 §5).
The page that documents one sets `experimental: true`, and the site shows an "Experimental"
banner at its top that links [Experimental features](/reference/experimental-features/). The
banner comes from `src/experimental-banner.ts`, a Starlight route middleware; a `banner` the page
sets itself follows it.

```yaml
---
title: Example
description: An example of the flag.
sidebar:
  order: 1
lastVerified: '2026-10-25'
experimental: true
---
```

Flagged pages and the items of the experimental-feature registry (`libs/shared/stability`) match
one to one, and the registry's tests fail otherwise:

- each built item names its page in the registry (`docsPage`), and that page carries the flag;
- each flagged page is the page of exactly one item, and names that item's id in its text.

A page that only mentions an item, such as the configuration reference, does not set the flag.

---

# Request lifecycle

URL: https://docs.qauth.dev/extend/architecture/

The auth server is assembled in two files, and reading them in the order they execute is the
fastest way to understand what a request meets on its way in:

- `apps/auth-server/src/main.ts` builds the Fastify instance, installs the Zod compilers,
  registers OpenAPI, then registers the app and listens.
- `apps/auth-server/src/app/app.ts` — one plugin function — registers everything else, in
  source order.

Both files carry unusually precise comments, and this page quotes them rather than paraphrasing
wherever they are exact. Where a comment states an ordering **requirement**, this page says
whether Fastify actually enforces it — because two of them do not, and one requirement that
nothing documents does.

## Part 1 — `main.ts`: the instance, before any route exists

`main.ts` does four things that `app.ts` cannot do, because they are properties of the root
Fastify instance rather than of a plugin.

### 1. The instance options (`apps/auth-server/src/main.ts:36`)

`logger` (pino with secret redaction), `requestIdHeader` / `logController` / `genReqId`
(an inbound request id is honoured when present and generated otherwise, then attached to the
request-scoped logger as `reqId`), and `routerOptions.ignoreTrailingSlash`.

What is **not** in that options object is the point — see
[HTTP/1.1 only](#security-invariant-1--http11-only) below.

### 2. The global Zod validator and serializer compilers (`apps/auth-server/src/main.ts:61`)

`setValidatorCompiler(validatorCompiler)` and `setSerializerCompiler(serializerCompiler)` from
`fastify-type-provider-zod`, applied to the root instance so they are inherited by every route
in every plugin below. This is what makes `schema: { body: someZodSchema }` work, and it is also
a security control — see
[the global Zod compiler](#security-invariant-2--the-global-zod-validator-compiler) below.

### 3. OpenAPI, before the app (`apps/auth-server/src/main.ts:103`)

`@fastify/swagger` is registered **before** `server.register(app)` at
`apps/auth-server/src/main.ts:112`, and the comment there says why: routes must be added after
swagger so they are collected into the generated spec. The Swagger **UI** at `/docs` is gated on
`ENABLE_SWAGGER`, which defaults to `true` outside production and `false` in production
(resolved at the bottom of `apps/auth-server/src/config/env.ts`). The spec itself is registered
either way; the flag only suppresses the `/docs` route.

If you add a route and it does not appear in `openapi.json`, check that it is reachable from
`app()` rather than registered directly on the server after `listen`.

### 4. Signal handling and `listen`

`SIGTERM` / `SIGINT` both call `shutdown`, which awaits `server.close()` before
`process.exit(0)`. Anything you add that holds a resource open should be closed by a Fastify
`onClose` hook rather than by extending this function.

## Part 2 — `app.ts` in execution order

Every line below is `await`ed except where noted, so the order in the file is the order at boot.

| #   | Registration                                                        | What it contributes                                   |
| --- | ------------------------------------------------------------------- | ----------------------------------------------------- |
| 1   | `databasePlugin`, `apps/auth-server/src/app/app.ts:660`             | Postgres pool + the `repositories` decorator          |
| 2   | `cachePlugin`, `apps/auth-server/src/app/app.ts:824`                | Redis (`lazyConnect: true`) as `fastify.redis`        |
| 3   | `passwordPlugin`, `apps/auth-server/src/app/app.ts:872`             | argon2id hasher + strength scoring                    |
| 4   | `pkcePlugin`, `apps/auth-server/src/app/app.ts:888`                 | PKCE challenge verification helpers                   |
| 5   | `assertTrustedIssuersUsable`, `apps/auth-server/src/app/app.ts:312` | **Boot check** — not a plugin                         |
| 6   | `federationPlugin`, `apps/auth-server/src/app/app.ts:436`           | The ADR-003 `providerRegistry` decorator              |
| 7   | `emailPlugin`, `apps/auth-server/src/app/app.ts:490`                | Resend / SMTP / mock provider                         |
| 8   | `jwtPlugin`, `apps/auth-server/src/app/app.ts:539`                  | Signing keys, JWKS, revocation callback               |
| 9   | `rateLimitPlugin`, `apps/auth-server/src/app/app.ts:931`            | `@fastify/rate-limit` wiring                          |
| 10  | `securityHeadersPlugin`, `apps/auth-server/src/app/app.ts:947`      | Helmet: CSP, HSTS, frame options                      |
| 11  | `requestIdPlugin`, `apps/auth-server/src/app/app.ts:809`            | Echoes the request id back on the response            |
| 12  | `metricsPlugin`, `apps/auth-server/src/app/app.ts:954`              | Prometheus registry                                   |
| 13  | `corsPlugin`, `apps/auth-server/src/app/app.ts:1141`                | Fail-closed in production when `CORS_ORIGIN` is unset |
| 14  | `formbody`, `apps/auth-server/src/app/app.ts:1162`                  | Form-encoded body parsing                             |

Then three registrations whose **relative** order is the subject of the rest of this page, so this
table deliberately does not pin them to line numbers:

- `errorHandler` — the global error handler, which must be registered **before** the routes
  (issue [#365]).
- The route manifest's loop — every route module of the process's service roles, each
  `await`ed; see [below](#the-route-manifest).

[#365]: https://github.com/qauth-labs/qauth/issues/365

## Which orders are load-bearing, and why they differ

There is no single rule here, and "register it before the routes" is not one. Fastify binds
different extension points at different moments, and that is what decides whether a line's
position matters:

| Extension point                                | Bound when                                                                | Position relative to routes                                  |
| ---------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Content-type parsers (`formbody`)              | Per encapsulation context, as each child plugin is created                | **Must precede routes**                                      |
| `onRoute` hooks (`@fastify/rate-limit`)        | Fire only for routes registered after the hook exists                     | **Must precede routes**                                      |
| The error handler                              | Captured into each route's context when that route's plugin finishes load | **Must precede routes** — see [below](#the-error-handler)    |
| Request/response hooks (`onRequest`, `onSend`) | Collected at Fastify's `preReady`, after every plugin has loaded          | Position does not change behaviour                           |
| Decorators (`fastify.repositories`)            | Resolved through the prototype chain at request time                      | Matters only for code that reads them at _registration_ time |

Steps 1–8 are ordinary dependency ordering of the last kind: `rateLimitPlugin` reads
`fastify.redis` while it is registering, so the cache plugin must already have decorated the
instance — and that specific dependency is enforced rather than assumed, by
`dependencies: [CACHE_PLUGIN_NAME]` in the plugin's own `fastify-plugin` options
(`apps/auth-server/src/app/plugins/rate-limit.ts`). Reach for that mechanism when you add a
plugin with a hard prerequisite; it turns a silent misordering into a boot failure that names
the missing plugin.

### `formbody` must precede routes — verified

`@fastify/formbody` at `apps/auth-server/src/app/app.ts:1162`, with its own comment:

> RFC 6749 §3.2 (token endpoint) and RFC 7662 §2.1 (introspection) both mandate
> `application/x-www-form-urlencoded` for request bodies. Fastify ships with a JSON parser by
> default — without formbody, every OAuth-spec-compliant client gets 415 Unsupported Media Type.
> Register before routes so /oauth/\* receives decoded form bodies.

This is real, and it has the widest blast radius of any ordering mistake in the file. Content-type
parsers belong to an encapsulation context: an encapsulated child plugin gets the parser set that
existed when it was created, so a parser registered on the parent afterwards never reaches that
child's routes. Move this line below the route sweep and the symptom is not a test failure — it is
`415 Unsupported Media Type` for every client that follows the spec, while any client that happens
to send JSON keeps working.

**The failure would be uniform, and that is the one merciful thing about it.** Every route file
under `apps/auth-server/src/app/routes/` exports a plain plugin function
(`export default async function (fastify: FastifyInstance)`), so the route manifest registers each
as its own encapsulated plugin and none would pick up a parser registered afterwards. Nothing in that tree is wrapped
in `fastify-plugin` — the one file without a default export,
`apps/auth-server/src/app/routes/clients/api-keys.ts`, is registered by hand from its sibling
`index.ts` and shares that directory's context, so it is covered too.

That uniformity is worth stating explicitly, because the alternative would be worse. If some route
files were `fp`-wrapped they would be un-encapsulated, would share the parent's parser set, and
would keep working — leaving `/oauth/token` healthy while `/oauth/introspect` returned 415, which
is a far harder thing to diagnose than a server that rejects every form-encoded request. If you are
adding a route and reaching for `fastify-plugin` to escape encapsulation, understand that you are
also opting that route out of this failure mode, and out of the uniformity that makes it obvious.

**Loud is not the same as safe.** This is the ordering constraint whose breakage is easiest to
notice — the first spec-compliant client to call `/oauth/token` gets a 415 — and it is the only one
of the three that announces itself. The other two are silent, which is what makes them more
dangerous despite affecting less of the surface.

The registration has a dedicated test at `apps/auth-server/src/app/plugins/formbody.test.ts`. It is
a test of the _plugin's behaviour_, deliberately built on a bare `Fastify()` instance: it pins the
parsing the OAuth endpoints rely on, such as a repeated parameter becoming an array in the order
sent. It does not check where `app.ts` registers the plugin. The ordering is guarded at runtime by
`apps/auth-server/src/app/error-handler-wiring.test.ts` instead: its form-encoded `/oauth/token`
tests answer `415` instead of `400` when the registration is moved below the route manifest
(verified by doing so).

### `rateLimitPlugin` must precede routes — verified, and undocumented

Nothing in `app.ts` flags this one, so it is the easiest to break by tidying.

`@fastify/rate-limit` reads each route's `config.rateLimit` through an **`onRoute` hook**, and
`onRoute` is the one Fastify hook that is not retroactive: it fires as routes are added, so a
route registered before the hook exists is never seen. Routes across the app set per-route limits
this way — `apps/auth-server/src/app/routes/auth/login.ts:44` is the one that matters most — and
`/health` and `/ready` (`apps/auth-server/src/app/routes/health.ts`, `routes/ready.ts`) opt out
with `config: { rateLimit: false }`, counting in the process's memory instead.

Move step 9 below the route sweep and rate limiting stops applying to any of them. There is no
error, no warning, and no failing test: the endpoints simply answer every request. Treat this line
as being under the same "do not move" rule as `formbody`, even though it carries no comment saying
so.

### Security headers, request-id, metrics, CORS — the comments overstate this

`securityHeadersPlugin` at `apps/auth-server/src/app/app.ts:947` carries a comment saying to
register before routes

> so every response — including the server-rendered login/consent pages and error responses —
> carries the CSP, HSTS, frame-options and related hardening headers.

and `apps/auth-server/src/app/app.ts:949` says request-id propagation and the metrics registry
"must be available before routes are loaded".

**Fastify does not require this.** `onRequest` / `onSend` hooks are collected at `preReady`, after
every plugin in the boot has loaded, so a hook added to the parent instance applies to routes that
were registered before it. All four of these plugins are `fastify-plugin`-wrapped — so whatever
they add, hooks or decorators, lands on the app instance rather than in a private child scope — and
moving any of them after the route sweep changes nothing observable: the CSP header is still set,
`reply.cspNonce` is still populated on the login and consent pages, the request id is still echoed,
and CORS still applies. (`metricsPlugin` adds no hook at all; it only decorates.)

The intent behind the comments is sound and the current order is the right convention — a reader
should not have to reason about hook collection to be confident the headers are global. But the
comments describe a guarantee stronger than the framework gives, so **do not infer the converse**:
"it is before the routes" is not evidence that something is safe to move, and it is not evidence
that a plugin registered after routes is broken. Decide per extension point, using the table above.

What genuinely matters about the security headers plugin is inside it, not around it:

- **The nonce.** The server-rendered pages link the design system's stylesheet and fonts, which
  the auth server serves itself under `/assets/ui/` (`helpers/ui-assets.ts`): same-origin files
  that `style-src 'self'` and `font-src 'self'` allow. A page that adds rules of its own, such as
  the login and consent pages, ships an inline `<style>` and stamps `reply.cspNonce.style` onto it
  rather than weakening the policy with `'unsafe-inline'`. Add an inline `<style>` without the
  nonce and the browser refuses it.
- **The `/docs` exception.** Swagger UI bundles its own inline scripts and cannot use the nonce,
  so that one prefix is served a relaxed policy. The exception is scoped to the prefix; every
  other route keeps the strict policy (`apps/auth-server/src/app/plugins/security-headers.ts`).

## The route manifest

```ts
// apps/auth-server/src/app/app.ts
for (const entry of routeModulesFor(roles)) {
  await fastify.register(async (scope) => {
    scope.addHook('onRoute', (route) => {
      route.config = { ...route.config, serviceRoles: entry.roles };
    });
    const { default: plugin } = await entry.load();
    await scope.register(plugin, entry.prefix === undefined ? {} : { prefix: entry.prefix });
  });
}
```

`apps/auth-server/src/app/route-manifest.ts` lists every route module with the service roles
that register it ([#495], ADR-019 Decision 8), its URL prefix, the plugins its routes call and
the repositories they read. It replaced two `@fastify/autoload` sweeps, over `plugins/` and over
`routes/`: a module the manifest does not list is never registered, and a process registers only
the modules of the roles in `SERVICE_ROLES` (all of them by default). Each module is imported
only when its role is held. Every route is tagged with its roles in `config.serviceRoles`, and the
boot is refused for a route registered in the app without one. See
[Service roles](/operate/service-roles/) for the roles.

The prefix is the one the autoload used to derive: a module's **directory**, not its filename —
`routes/auth/login.ts` registering `'/login'` serves `/auth/login` — or, for a directory whose
entry file exports `autoPrefix`, that string (see
`apps/auth-server/src/app/routes/clients/index.ts`). `route-manifest.test.ts` pins that rule, the
completeness of the list, and each entry's plugins and repositories against what its import
graph reaches. If you add a route file and it 404s, check its manifest entry first.

[#495]: https://github.com/qauth-labs/qauth/issues/495

## The error handler

`apps/auth-server/src/app/plugins/error-handler.ts` is what turns the domain errors from
`@qauth-labs/shared-errors` into the wire shapes the rest of the docs describe: OAuth error codes,
RFC 6750 `WWW-Authenticate` challenges with a sanitized `error_description`, a `feedback` array for
weak passwords, `retryAfter` for rate limits, and — importantly — suppression of the message and
stack for unknown errors when `env.NODE_ENV === 'production'`. Routes throw
(`throw new InvalidGrantError(...)` and friends) and never build these bodies themselves.

> **⚠️ This registration must come before the routes, and it is load-bearing.** It is the
> third entry in the binding-time table above and the least obvious of the three, because a
> misordering here produces error responses rather than no response — so it looks like it works.
> [#365] found it misordered, fixed it, and left a guard behind; the section below records what
> it cost while it was wrong.

### The mechanism

A route does not look the error handler up when a request throws. In Fastify 5, each route's
context captures the error handler of its **enclosing instance** inside an `after()` callback that
runs when that route's plugin finishes loading — `node_modules/fastify/lib/route.js`, where
`context.errorHandler` is assigned from the instance's current handler — and
`node_modules/fastify/lib/error-handler.js` reads that already-captured `context.errorHandler` at
request time. There is no later re-resolution.

The capture is therefore a **snapshot**, taken per route plugin, at load time. A `setErrorHandler`
that runs after a route plugin has loaded does not reach that plugin's routes: they keep whichever
handler was in effect at the moment they loaded, which — if the application's handler has not been
registered yet — is Fastify's built-in default. Nothing throws, nothing warns, and the routes still
return an error response. Just the wrong one.

This is also why "register it last so it catches everything" is an appealing but wrong intuition.
It is the correct instinct for a `catch` block and the wrong one for Fastify: `register` enqueues
rather than executes, and the thing being ordered is not the moment errors are handled but the
moment each route decides who will handle them.

### What silently regresses when it is wrong

> **Fixed in [#365]; kept because the failure mode is the point.** `app.ts` now registers the
> error handler ahead of the routes, and `error-handler-wiring.test.ts` fails if it moves back.
> What follows is what the misordering actually cost, which is the argument for the guard.

`app.ts` used to register the error handler after both folder-autoload sweeps, under a comment
saying that is what makes it catch everything. It did the opposite — the plugin reached no route in
the application. Three consequences, all confirmed against the real assembled app in [#365]:

- **Validation failures returned `FST_ERR_VALIDATION`**, Fastify's raw internal error code, instead
  of the application's error shape.
- **`GET /oauth/userinfo` answered 401 with no `WWW-Authenticate` header at all** — an RFC 6750 §3
  violation, since a 401 rejecting a bearer token must carry the challenge.
- **A duplicate `POST /auth/register` returned the database constraint name** in its `message`.
  That is exactly the account-enumeration oracle `error-handler.ts` sanitizes — a control that
  shipped as security finding F-01, was reviewed, was merged, and had been inert ever since,
  because the sanitizing handler was never the one answering.

That third one is why this belongs in the same category as `formbody` rather than in a style guide.
An ordering mistake here does not break a feature; it disables a security control while leaving
every visible behaviour intact.

### The guard that landed with the fix

`apps/auth-server/src/app/error-handler-wiring.test.ts` builds the **real assembled app** — not a
hand-rolled Fastify instance — and asserts that the application's handler is the one answering. Its
`[#365 ORDERING GUARD]` cases are mutation-checked: moving the registration back below the routes
flips every one of them to Fastify's built-in envelope.

The same file also pins the two orderings that have **no** runtime signal at all — `rateLimitPlugin`
before the route sweep, and `errorHandler` before `cors` — by reading the registration order out of
`app.ts` itself. That is a blunt instrument used deliberately: breaking either produces no throw, no
warning and no failed boot, so a guard that reads the declaration beats no guard.

Regardless: if you are adding a route whose contract includes a specific error body, assert that
body end-to-end. A passing unit test proves the handler _can_ produce the shape, not that your
route reaches it.

### Why it went unnoticed for so long

Every test that exercises the handler's mapping —
`apps/auth-server/src/app/plugins/error-handler.test.ts`,
`apps/auth-server/src/app/routes/oauth/userinfo.test.ts`,
`apps/auth-server/src/app/routes/oauth/signature-verification.test.ts` — builds its own Fastify
instance and registers `errorHandler` **before** the routes under test. Each is a correct test of
the mapping logic against a correctly composed app, so none of them could ever observe how the
production app was composed. The wiring test [#365] added is the answer to that specific gap.

Generalise the lesson rather than the fix: a test that constructs its own wiring can only ever
verify the wiring it constructs. See [Testing](/extend/testing/#the-honest-limitation) for how much
of `apps/auth-server`'s suite is in that position.

## The fail-closed boot checks

Four things in the bootstrap answer configuration questions at startup rather than at request
time. They are not symmetrical, and the difference is worth getting right.

### `assertTrustedIssuersUsable` — refuses the boot, ungated

`assertTrustedIssuersUsable(env.OID4VP_TRUSTED_ISSUERS)` at
`apps/auth-server/src/app/app.ts:312`, implemented at
`libs/server/federation/src/trust/assert-trusted-issuers.ts:63`, throws
`InvalidConfigurationError` on an `OID4VP_TRUSTED_ISSUERS` map the runtime could not use.

**What it refuses, and why refusing is right.** The variable is validated twice by two different
rule sets that did not agree: `server-config`'s schema checks each entry is a syntactically valid
HTTPS URL and caps its length, while the runtime additionally reduces the same entry with
`canonicalizeIssuerIdentifier`, which refuses userinfo, a query string, and a fragment. Because
per-realm trust resolution is deliberately **all-or-nothing**, a single entry the canonicalizer
refuses collapsed that realm's entire allowlist to deny-all. The module's own comment names the
consequence precisely:

> The result was the worst shape a security control can take: no boot failure, no log, no signal of
> any kind, and every Verifiable Presentation to that realm rejected — indistinguishable, by design
> (`issuer-trust-rejection.ts`), from an untrusted issuer. The operator sees a realm that trusts
> nobody and a configuration that says otherwise.

So the check runs the runtime's own reduction at startup — the same function, not a second
implementation that could drift. It is **not** gated on `WALLET_FEDERATION_ENABLED`: a typo is a
typo whether or not those flows are on today. An absent or empty map is not a fault; it means no
realm trusts any issuer, which is the intended fail-closed default, and it starts.

### `assertCredentialStatusConfigUsable` — refuses the boot, ungated

`resolveStatusListTrustAnchorPems(env)` followed by `assertCredentialStatusConfigUsable(...)` in
`app.ts`, immediately after the issuer check. It validates the Token Status List revocation
configuration (#297/#378) — the trust anchors and the URI allowlist — and, like the issuer check,
is **ungated**: a malformed anchor bundle is malformed whether or not wallet flows are on today.

It exists for the same reason as its sibling. Revocation checking that cannot resolve its anchors
does not fail loudly at the point of use; it refuses credentials, and a refusal is
indistinguishable from a legitimately revoked credential. Catching it at boot converts a silent,
permanent deny-all into a startup error an operator can act on. The resolved anchors are then
passed into `federationPlugin` as `credentialStatusProvisioned`, which is what the wallet-provider
gate #5 below consults.

### `createConfiguredProviders` — refuses the boot, but only when the flag is on

`createConfiguredProviders`, `apps/auth-server/src/app/app.ts:437`, implemented at
`libs/fastify/plugins/federation/src/lib/configured-providers.ts:302`, is a **pure function of
config** — no I/O, no Fastify, no database — that returns the provider list the registry is seeded
with. `PasswordProvider` is unconditional
(`libs/fastify/plugins/federation/src/lib/configured-providers.ts:305`). Everything else is gated.

With `WALLET_FEDERATION_ENABLED` at its default of `false`, this function **cannot throw** — the
entire gate sits inside `if (options.walletFederationEnabled === true)` at
`libs/fastify/plugins/federation/src/lib/configured-providers.ts:317`. (Strict `=== true`, not
truthiness, because the string `'false'` — what an unparsed `process.env` value would hand it — is
truthy in JavaScript.) When the flag _is_ on, five questions must all be answered before a wallet
provider may exist:

1. **Is a `VerifierProfile` selected?** `resolveVerifierProfile` returns `undefined` when none
   usable is. The refusal that follows is built by probing every shipped profile with the real
   guards rather than describing them in prose, so the values it advertises as settable are
   exactly the ones that would actually start in this deployment.
2. **Is that profile's verifier identity provisionable here?** The same `resolveVerifierProfile`
   call throws for this case; the assertion is folded into the resolver, so there is no path that
   obtains a profile without it having been checked.
3. **Can this deployment's crypto layer honour the profile's mandates?** —
   `configured-providers.ts` (`assertCryptoCapabilities`), the first of three the resolver cannot
   make, because it is a property of this build rather than of the profile.
4. **Can we establish the key-storage assurance it requires (#308)?** —
   `assertKeyStorageAssuranceProvisioned`. Also a property of the deployment: it asks what the
   **operator** configured, not what the profile declares.
5. **Can we establish the credential status it requires (#297/#378)?** —
   `assertCredentialStatusProvisioned`, the same shape as the fourth. A profile whose
   `requireCredentialStatus` is true, with no status anchors and no URI allowlist, would boot
   cleanly and then refuse every single login — the worst possible place to discover a
   configuration mistake.

No profile is named in checks 3–5 by design: adding one must mean editing the profile table and
nothing else.

### `deriveCryptoCapabilities` — a descriptor, not an assertion

This is the subtle one, and the most common place to get the mental model wrong.

The capabilities are derived twice in `apps/auth-server/src/app/app.ts` (`cryptoCapabilities`):
while `app()` registers the plugins, with the EdDSA key the key boot step guarantees, and again in
an `onReady` hook after that step, from the token keys the default realm's key store holds (#491).
`deriveCryptoCapabilities`,
`apps/auth-server/src/app/crypto-capabilities.ts:61`, **never throws**. It answers a question; the
answer is then read by the gate in step 3 above. Calling it a boot assertion is shorthand — the
refusal lives in `configured-providers.ts`, and this function is what makes that refusal correct.

The question it answers is deliberately narrower than the obvious one. From the module's own
JSDoc:

> - `@qauth-labs/core-crypto` EXPORTING an algorithm means the code to compute it exists.
> - This deployment being able to SIGN WITH it means a key for it has been provisioned and there
>   is a code path that uses it.

`deriveCryptoCapabilities` answers the second. Concretely, at `HEAD`:

| Entry                | Value   | Why                                                                                                                                                                                                                      |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `EdDSA`              | derived | `true` when the default realm's key store holds an active EdDSA `token_signing` key, which the key boot step guarantees or refuses to start                                                                              |
| `RS256`              | derived | `true` only when the default realm's key store holds an active RS256 `token_signing` key: a fresh deployment's, an imported `JWT_RS256_PRIVATE_KEY` or one `auth-server:keys:create` made                                |
| `ES256`              | `false` | The crypto layer _can_ compute an ES256 signature. What is missing is provisioning: no env var, no schema field, no JWKS entry, no code path (`apps/auth-server/src/app/crypto-capabilities.ts:79`)                      |
| `responseEncryption` | `false` | The JWE primitives exist and nothing in the workspace calls them — no `direct_post.jwt` response mode, no published encryption JWK, no intake route to decrypt at (`apps/auth-server/src/app/crypto-capabilities.ts:95`) |

Two `false` entries for algorithms the crypto library implements is the whole point. Deriving them
from "does the library export it" would lift the gate: a profile mandating ES256 would boot on a
deployment that cannot produce an ES256 signature, and the misconfiguration would surface as every
wallet rejecting every request in production — the worst possible place to find it.

**If you are the contributor who provisions P-256 key material**, the corresponding entry flips to
a real predicate over that configuration in the same change. The inner record is pinned with
`satisfies Record<JwsAlgorithm, boolean>` at
`apps/auth-server/src/app/crypto-capabilities.ts:80`, so widening the crypto layer's algorithm
union stops the literal compiling until the new algorithm is given an answer. The descriptor
cannot go stale by silence.

## Security invariant 1 — HTTP/1.1 only

`apps/auth-server/src/main.ts:30`, immediately above the `Fastify({...})` call:

> **SECURITY INVARIANT — HTTP/1.1 only.** Do NOT add `http2: true` (or `http2SessionTimeout`, or
> an HTTP/2 `serverFactory`) here without first clearing the `find-my-way` advisory. Fastify's
> router is `find-my-way`, and CVE-2026-47219 (DoS) is HTTP/2-specific; serving HTTP/1.1 is the
> only reason it is inert.

The mitigation is a property of the _protocol this process serves_, not of a version constraint or
a configuration flag — which is exactly why it is easy to undo. Enabling HTTP/2 on this instance
reactivates the advisory.

There is a second, independent line of defence: `pnpm-workspace.yaml` pins
`find-my-way: '>=9.7.0'` under `overrides`, and the comment there is explicit that this is "a
floor against a future http2 switch, not a live fix". So an HTTP/2 switch is safe only as long as
that floor — or a later fixed version — is what actually resolves. Verify with:

```bash
pnpm why find-my-way
```

A reverse proxy that terminates HTTP/2 in front of the server and forwards HTTP/1.1 does not
reactivate anything; the router only ever sees HTTP/1.1 requests. The invariant is about what this
process serves.

## Security invariant 2 — the global Zod validator compiler

`apps/auth-server/src/main.ts:48`, immediately above the two `set*Compiler` calls:

> **SECURITY INVARIANT — this global Zod validator compiler is load-bearing beyond typing.** It
> replaces Fastify's default `ajv` compiler for _every_ route, and `ajv` is what pulls `fast-uri`,
> which carries two unfixed-in-tree host-confusion advisories (CVE-2026-13676, CVE-2026-16221).
> Because no request is ever parsed by ajv, those advisories are inert.

State the mitigation carefully, because its shape is what tells you how to avoid breaking it. The
defence is **not** that `fast-uri` has been removed from the dependency tree — it is still there,
reachable through `ajv`. The defence is that **no request is ever parsed by ajv**, so no
attacker-controlled string reaches `fast-uri`'s URI parser. That property holds because the
compiler is set once, on the root instance, and inherited by every route below it.

Three ways to break it, all named in the comment:

- **Removing the line.** Every route falls back to ajv.
- **Scoping it to a subset of routes** — for example calling `setValidatorCompiler` on a child
  instance instead of the root, leaving sibling contexts on the default.
- **Adding a route that opts back into ajv validation**, e.g. a raw JSON Schema `schema` on an
  instance without this compiler.

Each silently reactivates host confusion inside an OAuth server. Nothing fails; nothing logs.

**The version floors exist so this is not the only mitigation.** `pnpm-workspace.yaml` pins
`fast-uri: '>=3.1.8 <4'` under `overrides`, and its comment says so directly — the advisories are

> Inert today — main.ts sets a global Zod validator compiler so ajv never parses a request, and
> redirect_uri matching is an exact string comparison with no URI parser in the decision — but
> floored so that stops being load-bearing.

The upper bound is deliberate: a bare `>=3.1.8` resolves to 4.x, turning a security floor into an
unreviewed major bump. Treat the floor as defence in depth, not as permission to remove the
compiler.

`apps/auth-server/src/main.ts:58` names **the second leg of the same invariant**, and it lives
somewhere a contributor would not think to look: `redirect_uri` matching is an exact string
comparison (`client.redirectUris.includes(...)`, per RFC 9700) with **no URI parser in the
security decision** — see `apps/auth-server/src/app/helpers/oauth-redirect.ts`. Introducing a
parse-then-compare there would put a URI parser back into the one decision the invariant protects,
even with the Zod compiler intact.

## Before you change the bootstrap

- **Adding a plugin routes depend on:** register it before the route manifest's loop, `await` it,
  and if the dependency is hard, declare it with `dependencies:` in the plugin's `fastify-plugin`
  options rather than relying on line order. If only some roles need it, add it to
  `ROLE_PLUGINS` and register it under `plugins.has(...)`.
- **Adding a route:** add its module to the route manifest with its roles; nothing else in
  `app.ts` changes. The directory determines the prefix, and `route-manifest.test.ts` tells you
  which plugins and repositories the entry must name.
- **Adding a credential provider:** nothing in `app.ts` changes either — see
  [Adding a credential provider](/extend/adding-a-credential-provider/).
- **Moving anything:** check the binding-time table above first, and do not trust the comment above
  the line. Two of this file's comments claim an ordering requirement Fastify does not enforce; a
  third claimed one it does enforce but described it backwards ([#365]); and `rateLimitPlugin`,
  which has a real requirement, carries no comment at all and fails silently.
- **Touching `main.ts`:** re-read both `SECURITY INVARIANT` comments in full first. They are there
  because the code they protect looks removable.

## See also

- [Repository map](/extend/repo-map/) — where new code belongs, and the tag constraints that decide
  it.
- [Testing](/extend/testing/) — what each tier can and cannot catch, including why the route tests
  would not notice a bootstrap-ordering regression.
- [Adding a credential provider](/extend/adding-a-credential-provider/) — the ADR-003 extension
  point that `createConfiguredProviders` gates.
- [Frontmatter contract](/extend/frontmatter/) — the fields every page in this site sets.
- [Status](/reference/status/) — what has shipped and what is flag-gated, rendered from the single
  status source.

---

# Repository map

URL: https://docs.qauth.dev/extend/repo-map/

QAuth is an Nx monorepo with two trees: `apps/` for deployable entry points and `libs/` for
everything they compose. Which layer a new file belongs in is not a matter of taste here — it is
enforced by `@nx/enforce-module-boundaries` in `.oxlintrc.json`, which Oxlint runs through
@nx/oxlint's bridge, and getting it wrong surfaces as a lint error naming the tag you violated.

## `apps/`

| Directory               | Nx project         | What it is                                                                 |
| ----------------------- | ------------------ | -------------------------------------------------------------------------- |
| `apps/auth-server`      | `auth-server`      | The OAuth 2.1 / OIDC authorization server. Fastify.                        |
| `apps/developer-portal` | `developer-portal` | The client-management UI. TanStack Start + React.                          |
| `apps/docs-site`        | `docs-site`        | This site. Astro + Starlight, plus the drift-guard invariants.             |
| `apps/migration-runner` | `migration-runner` | The migration runner: one bundled Node program and the image that runs it. |
| `apps/wire-suite`       | `wire-suite`       | The black-box HTTP suite that tests a running server. Ships nothing.       |
| `apps/upgrade-test`     | `upgrade-test`     | The checks of the upgrade test, run against released and new servers.      |

The auth server, the portal and this site are tagged `scope:app` (e.g. `apps/auth-server/project.json:6`).
`apps/wire-suite` is tagged `scope:wire-suite` and `type:testing` instead, because it must import
**nothing** from the workspace — see [the wire suite](#the-wire-suite-imports-nothing) below.
`apps/upgrade-test` is tagged `scope:upgrade-test` and `type:testing` for the same reason: it drives
a released server and the new build from outside, over HTTP and `pg`, and imports no workspace
project (`.oxlintrc.json:298`, and `.oxlintrc.json:302` stops anything importing it).
Nothing in `apps/` may be imported by anything — the app layer is the top of the graph.

Some projects live outside both trees. One is `deploy/reference/proxy` (`reference-proxy`), the
reference reverse-proxy configuration and the container test that runs it in front of stub
upstreams. It is tagged `scope:reference-proxy` and `type:testing`, and imports no workspace
project (`.oxlintrc.json:318`).

Another is `graphs/` (`graphs`), with no tags: it holds the flow graphs of ADR-021 and no code, so
nothing can import it. Its one target, `graphs:check`, runs delurio's pinned checker over the
directory (`graphs/README.md`).

`apps/migration-runner` is tagged `scope:migration-runner`, and may depend only on the database
library (`type:db`) and, in its container suite, the testing library. Its build bundles
`src/main.ts`, `pg` and `drizzle-orm` into one file, `dist/apps/migration-runner/main.js`, beside a
copy of the migrations, which its image runs with Node alone. The logic itself, the lock, the
pending-migration rule and the boot check's wait, lives in `libs/infra/db/src/lib/migrations`,
which the package exports as `@qauth-labs/infra-db/migrations` so the bundle loads nothing else.

## `libs/`

Directory nesting under `libs/` is a readability convention. **The `scope:` tag in each
`project.json` is what the boundary rules actually read**, and the two do not always agree — see
[the crypto-native exception](#a-directory-is-not-a-tag) below.

| Directory                             | Package                                     | Tag                                    |
| ------------------------------------- | ------------------------------------------- | -------------------------------------- |
| `libs/core/crypto`                    | `@qauth-labs/core-crypto`                   | `scope:core`                           |
| `libs/core/crypto-native`             | `@qauth-labs/crypto-native`                 | `scope:server`                         |
| `libs/shared/errors`                  | `@qauth-labs/shared-errors`                 | `scope:shared`                         |
| `libs/shared/validation`              | `@qauth-labs/shared-validation`             | `scope:shared`                         |
| `libs/shared/testing`                 | `@qauth-labs/shared-testing`                | `scope:shared`                         |
| `libs/shared/test-vectors`            | `@qauth-labs/shared-test-vectors`           | `scope:shared`                         |
| `libs/shared/stability`               | `@qauth-labs/shared-stability`              | `scope:shared`                         |
| `libs/shared/interaction-contract`    | `@qauth-labs/shared-interaction-contract`   | `scope:shared`                         |
| `libs/shared/interaction-client`      | `@qauth-labs/shared-interaction-client`     | `scope:shared` + `type:sdk`            |
| `libs/ui`                             | `@qauth-labs/ui`                            | `scope:ui`                             |
| `libs/infra/db`                       | `@qauth-labs/infra-db`                      | `scope:infra`                          |
| `libs/infra/cache`                    | `@qauth-labs/infra-cache`                   | `scope:infra`                          |
| `libs/server/config`                  | `@qauth-labs/server-config`                 | `scope:server` + `scope:server-config` |
| `libs/server/federation`              | `@qauth-labs/server-federation`             | `scope:server`                         |
| `libs/server/jwt`                     | `@qauth-labs/server-jwt`                    | `scope:server`                         |
| `libs/server/keys`                    | `@qauth-labs/server-keys`                   | `scope:server` + `type:key-custody`    |
| `libs/server/password`                | `@qauth-labs/server-password`               | `scope:server`                         |
| `libs/server/pkce`                    | `@qauth-labs/server-pkce`                   | `scope:server`                         |
| `libs/server/dpop`                    | `@qauth-labs/server-dpop`                   | `scope:server`                         |
| `libs/server/realm-policy`            | `@qauth-labs/server-realm-policy`           | `scope:server`                         |
| `libs/server/egress`                  | `@qauth-labs/server-egress`                 | `scope:server`                         |
| `libs/server/breached-passwords`      | `@qauth-labs/server-breached-passwords`     | `scope:server`                         |
| `libs/server/email`                   | `@qauth-labs/server-email`                  | `scope:server`                         |
| `libs/server/step-grammar`            | `@qauth-labs/server-step-grammar`           | `scope:server`                         |
| `libs/server/sign-in-engine`          | `@qauth-labs/server-sign-in-engine`         | `scope:server`                         |
| `libs/server/upstream-oidc`           | `@qauth-labs/server-upstream-oidc`          | `scope:server`                         |
| `libs/fastify/plugins/db`             | `@qauth-labs/fastify-plugin-db`             | `scope:fastify`                        |
| `libs/fastify/plugins/cache`          | `@qauth-labs/fastify-plugin-cache`          | `scope:fastify`                        |
| `libs/fastify/plugins/jwt`            | `@qauth-labs/fastify-plugin-jwt`            | `scope:fastify`                        |
| `libs/fastify/plugins/password`       | `@qauth-labs/fastify-plugin-password`       | `scope:fastify`                        |
| `libs/fastify/plugins/pkce`           | `@qauth-labs/fastify-plugin-pkce`           | `scope:fastify`                        |
| `libs/fastify/plugins/email`          | `@qauth-labs/fastify-plugin-email`          | `scope:fastify`                        |
| `libs/fastify/plugins/federation`     | `@qauth-labs/fastify-plugin-federation`     | `scope:fastify`                        |
| `libs/fastify/plugins/signer`         | `@qauth-labs/fastify-plugin-signer`         | `scope:fastify`                        |
| `libs/fastify/plugins/dpop`           | `@qauth-labs/fastify-plugin-dpop`           | `scope:fastify`                        |
| `libs/fastify/plugins/egress`         | `@qauth-labs/fastify-plugin-egress`         | `scope:fastify`                        |
| `libs/fastify/plugins/sign-in-engine` | `@qauth-labs/fastify-plugin-sign-in-engine` | `scope:fastify`                        |
| `libs/sdk/resource-guard`             | `@qauth-labs/resource-guard`                | `scope:sdk` + `type:sdk`               |

## The layering

Every rule below is a `depConstraints` entry in `.oxlintrc.json:155`, and the comments there are
the source of record. `onlyDependOnLibsWithTags` lists what a project carrying that source tag may
import **from inside the workspace**; external npm packages are never restricted.

| Source tag               | May import (workspace)                                                           | In `.oxlintrc.json`  |
| ------------------------ | -------------------------------------------------------------------------------- | -------------------- |
| `scope:core`             | nothing — strict leaf                                                            | `.oxlintrc.json:170` |
| `scope:shared`           | nothing — strict leaf                                                            | `.oxlintrc.json:160` |
| `scope:ui`               | nothing — strict leaf                                                            | `.oxlintrc.json:177` |
| `scope:infra`            | `scope:core`, `scope:infra`, `scope:shared`                                      | `.oxlintrc.json:211` |
| `scope:server`           | `scope:core`, `scope:server`, `scope:shared`                                     | `.oxlintrc.json:219` |
| `scope:fastify`          | `scope:core`, `scope:fastify`, `scope:server`, `scope:infra`, `scope:shared`     | `.oxlintrc.json:227` |
| `scope:app`              | `scope:core`, `scope:fastify`, `scope:shared`, `scope:server-config`, `scope:ui` | `.oxlintrc.json:240` |
| `type:testing`           | see [the dead rule](#the-typetesting-rule-cannot-grant-anything)                 | `.oxlintrc.json:196` |
| `type:key-custody`       | `scope:core`, `scope:shared`                                                     | `.oxlintrc.json:274` |
| `scope:migration-runner` | `type:db`, `type:testing`                                                        | `.oxlintrc.json:255` |
| `scope:wire-suite`       | nothing — and nothing may import it                                              | `.oxlintrc.json:187` |
| `scope:upgrade-test`     | nothing — and nothing may import it                                              | `.oxlintrc.json:298` |
| `type:kek-adapter`       | `scope:core`, `scope:shared`, `type:key-custody` — and nothing may import it     | `.oxlintrc.json:284` |
| `scope:sdk`              | nothing — an SDK is installed outside the workspace                              | `.oxlintrc.json:309` |
| `scope:reference-proxy`  | nothing — it tests the shipped proxy configuration from outside                  | `.oxlintrc.json:318` |

### Key custody has a second, path-based rule

The `type:key-custody` row limits what `@qauth-labs/server-keys` imports. Who imports it is a
separate rule, because ADR-019 Decision 9 provisions the key-encryption key to the signer alone.
The package has two entry points: `@qauth-labs/server-keys`, with the `Signer` interface that any
project may use, and `@qauth-labs/server-keys/custody`, with the KEK provider, envelope encryption,
the key factory and the in-process signer. Module boundaries work per project and cannot tell the
two apart, so a block in `.oxlintrc.json` (the key custody guard: `no-restricted-imports`, plus
`qauth/no-restricted-syntax` from `tools/oxlint/qauth-plugin.mjs` for `require()` and the other
forms an import rule does not see) refuses `/custody`, and any deep path into the package,
everywhere except `libs/server/keys`, the signer's wiring, `libs/fastify/plugins/signer`, and the
KEK adapter packages under `libs/keys/`, which implement its `KekProvider` and run in the signer's
process. Sign through `fastify.signer`; do not widen the list beyond a new KEK adapter.

A KEK adapter (`type:kek-adapter`) reaches only the key library and the core and shared layers, and
no project may depend on one: `KEK_PROVIDER=<name>` imports `@qauth-labs/keys-<name>` by name at run
time, so the auth server and its image ship without it.

### Outbound calls go through the egress client

Server code makes its outbound HTTP calls through the SSRF-safe egress client (`fastify.egress`,
ADR-019 Decision 8), which checks every destination. A block in `.oxlintrc.json` (the egress guard,
`qauth/no-direct-network` from `tools/oxlint/qauth-plugin.mjs`) refuses the global `fetch` and
`request`/`get` of `node:http` and `node:https` in the auth server, the migration runner and the
core, shared, infra, server and fastify libraries. Its exceptions are `libs/server/egress` itself,
tests and their fixtures, and the wallet status-list fetcher, which has not moved yet; the KMS
adapters under `libs/keys/` are outside it.

### Why `scope:core` and `scope:shared` are strict leaves

Both are declared `onlyDependOnLibsWithTags: []`, and the comment at `.oxlintrc.json:164`
explains `scope:core`:

> Core libraries provide low-level, framework-agnostic primitives (crypto, encoding). Like the
> shared layer, they depend on nothing internal (leaf) and are consumable by every layer above
> (infra, server, fastify, app). Kept a strict leaf on purpose: a crypto primitive must not reach
> up into domain/error libs.

That last sentence is the design. A signing primitive that imported `@qauth-labs/shared-errors`
would make the crypto layer's behaviour depend on the domain error taxonomy, which is exactly
backwards — and once the cycle exists, "which layer owns this?" stops having an answer. The same
argument applies to `scope:shared` (pure utilities, errors, common types) and `scope:ui` (React
components).

The practical effect: if you find yourself wanting to import something into `libs/core/crypto` or
`libs/shared/*`, the answer is almost always to invert the dependency — take the value as a
parameter, or return data the caller interprets — rather than to loosen the tag. `libs/core/crypto`
and every `libs/shared/*` library import **no** workspace package today; keep it that way.

Note one sharp edge in how Nx implements an empty list: it reports a violation only when the
imported project **has at least one tag**. A brand-new lib whose `project.json` you forgot to tag
would therefore slip past every leaf constraint. Tag every new lib as the first thing you do.

### The consequence you will actually hit: `scope:app` cannot import `scope:server`

`scope:app`'s allowlist (`.oxlintrc.json:240`) contains `scope:fastify` but **not**
`scope:server`. So `apps/auth-server` cannot import `@qauth-labs/server-federation`,
`@qauth-labs/server-jwt`, or any other `libs/server/*` package directly, even though it is
obviously the consumer of all of them. The only sanctioned route is through the matching
`scope:fastify` plugin.

That is why `libs/fastify/plugins/federation/src/index.ts` is, in large part, a **re-export shim**
rather than only a plugin. Its own comment at `libs/fastify/plugins/federation/src/index.ts:5`
says so:

> Re-exported provider surface: app code (scope:app) may only depend on fastify plugins
> (scope:fastify), never on server libs directly — routes and bootstrap reach the ADR-003 provider
> API through here.

Three things worth understanding about that file before you add to it:

- **The re-export list is a deliberate allowlist, not a convenience.** The comment at
  `libs/fastify/plugins/federation/src/index.ts:16` calls out the asymmetry: `createPasswordProvider`
  is re-exported and `createWalletProvider` is not, so no bootstrap can put a wallet provider in
  the registry while bypassing `WALLET_FEDERATION_ENABLED`. Adding an export here can remove a
  security control. Read the comment above the line you are adding to.
- **Boot-time checks get re-exported for the same reason.**
  `libs/fastify/plugins/federation/src/index.ts:28` re-exports `assertTrustedIssuersUsable`
  precisely because the bootstrap must call it and cannot import `scope:server` to reach it.
- **`server-config` is the one exception, and it is a second tag rather than a hole in the rule.**
  `libs/server/config/project.json:6` carries both `scope:server` and `scope:server-config`, and
  `scope:app`'s allowlist names the latter. Nx's check passes if the imported project has **any**
  of the allowed tags, so the extra tag is what makes `@qauth-labs/server-config` importable from
  an app while every other `libs/server/*` package stays out of reach.

The comment at `libs/fastify/plugins/federation/src/lib/configured-providers.ts:22` records a real
consequence of this arrangement: because `server-config` carries no dependency on `server-federation`
(config is the lowest server layer), the config schema's `OID4VP_VERIFIER_PROFILE` enum duplicates
the federation lib's `VerifierProfileId` union, and `apps/auth-server` is the only place in the
workspace that can see both — which is why the cross-lib pin between the two lists lives in the
app's env test. Verified: nothing under `libs/server/config/src` imports `server-federation`. All
15 references to it there are prose — 13 in comments, two in test description strings.

### A second tag can also narrow

`server-config`'s second tag widens who may import it. `type:key-custody` works the other way.
`libs/server/keys/project.json` carries it beside `scope:server`, and Nx applies every constraint
whose source tag a project carries, so both must pass. The library that opens stored keys may
therefore import only `scope:core` and `scope:shared` libraries, never another `scope:server` one
such as `server-config` (ADR-019 Decision 9). Its configuration keys are declared in
`server-config`'s `kekEnvSchema`, and the key library reads them from the environment itself.

### A directory is not a tag

`libs/core/crypto-native` sits under `libs/core/` and is tagged `scope:server`, not `scope:core`
(`libs/core/crypto-native/project.json:6`). Two consequences that surprise people:

- It is **not** a strict leaf, which is what lets it import `@qauth-labs/core-crypto` (a
  `scope:server` source may depend on `scope:core`).
- `apps/auth-server` **cannot** import it, because `scope:app` does not allow `scope:server`. The
  native backend is reached through `@qauth-labs/core-crypto`'s backend registry, not directly.

So do not infer a project's layer from its path. Read its `project.json`.

### The `type:testing` rule cannot grant anything

`.oxlintrc.json:196` declares that a `type:testing` project may depend on `scope:core`,
`scope:shared`, `scope:ui`, `scope:infra`, `scope:server` and `scope:fastify` — a deliberately
broad allowance, so test helpers can reach whatever they need to build fixtures.

It does not currently do that. Nx collects **every** `depConstraints` entry whose `sourceTag` the
source project carries and requires **all** of them to pass. Three projects carry `type:testing`,
and each pairs it with a strict leaf: `libs/shared/testing` (`libs/shared/testing/project.json:6`)
is also tagged `scope:shared`, `apps/wire-suite` is also tagged `scope:wire-suite`, and
`apps/upgrade-test` is also tagged `scope:upgrade-test`. The constraints intersect to "nothing", so
the broad allowance grants no import at all.

This is inert today because `libs/shared/testing` imports no workspace package. It stops being
inert the moment someone adds a fixture there that imports, say, `@qauth-labs/infra-db` — which
the `type:testing` rule appears to bless and lint will reject. If you hit that, the fix is a
decision about tags, not a cast or a disable comment; raise it rather than working around it.

### The wire suite imports nothing

`apps/wire-suite` tests a running server over HTTP (see [Testing](/extend/testing/)). It may use
`fetch`, `jose` and its own helpers, and no workspace project, because a helper shared with the
server could carry the same encoding bug on both sides and hide it. Two constraints hold that
down. `scope:wire-suite` depends on nothing (`.oxlintrc.json:187`). A second entry with
`sourceTag: '*'` and `notDependOnLibsWithTags: ['scope:wire-suite']` (`.oxlintrc.json:192`)
stops every project from importing the suite. The suite is an application, so Nx's "Imports of apps
are forbidden" check stops that too; the tag rule still holds if it ever becomes a library.

An import of `@qauth-labs/shared-errors` into the suite fails `nx lint` with:

```text
A project tagged with "scope:wire-suite" cannot depend on any libs with tags
```

A relative import of `apps/auth-server` source fails with:

```text
Projects cannot be imported by a relative or absolute path, and must begin with a npm scope
```

## Where new code belongs

| You are adding…                                      | Put it in                                           |
| ---------------------------------------------------- | --------------------------------------------------- |
| A pure crypto or encoding primitive                  | `libs/core/crypto` (no workspace imports allowed)   |
| An error class or a shared type                      | `libs/shared/errors` / `libs/shared/validation`     |
| Domain logic with no Fastify and no I/O              | `libs/server/<area>`                                |
| A database table, migration, or repository           | `libs/infra/db`                                     |
| The graph of a flow or a screen (ADR-021)            | `graphs/flows/<area>/<flow>/` (`graphs/README.md`)  |
| A shared test vector (ADR-018 §6)                    | `test-vectors/<area>/` (`test-vectors/README.md`)   |
| The Fastify wiring that exposes the above to the app | `libs/fastify/plugins/<area>`                       |
| An HTTP route                                        | `apps/auth-server/src/app/routes/<dir>`             |
| Configuration schema an app must read                | `libs/server/config` (already dual-tagged for this) |

Two rules of thumb that follow from the layering:

1. **If an app needs something from a `libs/server/*` lib, the answer is a `scope:fastify`
   re-export, not a tag change.** The plugin layer exists to be that seam.
2. **If a lib needs something from a layer above it, invert the dependency.** Pass it in. Every
   fail-closed check in this codebase is built that way — see
   [Request lifecycle](/extend/architecture/) for `createConfiguredProviders` taking a crypto
   capability descriptor rather than probing the crypto layer itself.

## Local development gotcha: CRLF on Windows

`.gitattributes` sets `* text=auto eol=lf` ([#363](https://github.com/qauth-labs/qauth/issues/363)),
so a fresh checkout has LF line endings in every text file, whatever `core.autocrlf` says. A clone
made before that rule landed can still hold CRLF copies of files it has not rewritten since, and
`git status` stays **clean** for them, because Git normalizes line endings on the way into the
index.

Oxfmt's config sets `endOfLine: "lf"` (`.oxfmtrc.json`), so the format check lists each of those
files as unformatted:

```console
$ pnpm format:check
Checking formatting...

apps/developer-portal/src/client.tsx (0ms)

Format issues found in above 1 files. Run without `--check` to fix.
```

The confusing part is the surrounding silence: the files look untouched, `nx lint` passes (Oxlint
does not check formatting), and CI stays green, because Linux runners check out LF.

**Do not fix this by running `pnpm format` across the tree.** That rewrites every affected file,
and the diff is invisible to you (`git status` clean) but not to reviewers. Check
`git config core.autocrlf` instead: if it is `true` and the checkout predates the rule, a fresh
clone has none of this.

## See also

- [Request lifecycle](/extend/architecture/) — how `apps/auth-server` composes the plugins above.
- [Frontmatter contract](/extend/frontmatter/) — required reading before adding a page to this
  site.

---

# Testing

URL: https://docs.qauth.dev/extend/testing/

QAuth has three test tiers, a fourth that guards this documentation site, and a fifth that tests
the built server from outside, over HTTP. Knowing what each one **cannot** catch matters more than knowing what it can, because the gaps are where the two
worst incidents in this repo's history came from: a suite that passed while running zero tests,
and a schema change no unit test could see.

| Tier                 | Command                                      | Runs in CI                | Catches                                                       |
| -------------------- | -------------------------------------------- | ------------------------- | ------------------------------------------------------------- |
| Unit                 | `pnpm exec nx run-many -t test --all`        | the `affected (test)` job | Handler and helper logic, in isolation                        |
| Integration          | `pnpm exec nx run infra-db:test-integration` | the `integration` job     | Real Postgres DDL, migrations, repositories                   |
| Repo-wide coverage   | `pnpm exec vitest run --coverage`            | the `coverage` job        | Coverage regression across the whole fast suite               |
| Documentation guards | `pnpm exec nx test docs-site`                | part of the unit tier     | Drift between this site and the tree it describes             |
| Docs checks          | `pnpm exec nx test docs-checks`              | part of the unit tier     | Generated pages and docs links out of step with the libraries |
| Wire suite           | `pnpm nx run wire-suite:run`                 | the `wire-suite` job      | What a client sees over HTTP from the built image             |
| Stable surface       | `pnpm stable-surface`                        | the `stable-surface` job  | A surface out of step with the code or the last release       |

## Tier 1 — unit

The fast suite. Vitest, no containers, no network. Every project has an inferred `test` target
(`nx.json:107`), so `pnpm exec nx test auth-server` runs one project's suite and
`pnpm exec nx run-many -t test --all` runs all of them.

Root config: `vitest.config.mts`. Each project's own `vitest.config.mts` merges it, which is why
`nx.json:164` lists the root config under `sharedGlobals` — a change to the exclude globs or the
coverage thresholds must invalidate every project's cached `test` result, and the inferred targets
do not list it themselves.

### The honest limitation

**`apps/auth-server`'s route tests do not boot the app.** Read one before you trust one — take
`apps/auth-server/src/app/routes/auth/login.test.ts`. It mocks the environment module wholesale
(`apps/auth-server/src/app/routes/auth/login.test.ts:10`) and builds a hand-written stand-in for
the Fastify instance (`apps/auth-server/src/app/routes/auth/login.test.ts:59`) whose
`withTypeProvider().post()` simply captures the handler function so the test can call it directly.
Repositories, the password hasher, and the JWT utilities are all `vi.fn()` stubs.

That design is fine for what it targets — it makes handler logic testable without Postgres, Redis,
or a valid environment — but be clear about what it therefore does **not** verify:

- **Nothing about `app.ts`'s composition.** Plugin registration order, content-type parsing, the
  active error handler, whether rate limiting applies to the route — none of it is exercised. This
  is not hypothetical: issue [#365] was a real ordering defect that left the application's error
  handler unreachable from every route, and this tier reported green throughout, because each test
  composes its own instance correctly before testing it. See
  [Request lifecycle](/extend/architecture/#the-error-handler) for the mechanism and for two
  further ordering claims in that file that are not what they appear.
- **Nothing about schema validation.** The stub never runs Fastify's validator, so a route's Zod
  `schema` is not applied to the payload the test passes in.
- **Nothing about the real environment schema.** `vi.mock('../../../config/env')` replaces it with
  an object literal, so a new required variable does not fail these tests.

The [wire suite](#tier-5--the-wire-suite) is the one tier that sees none of these stand-ins: it
talks to the image CI builds, over HTTP.

There are two stronger patterns in the tree, and the difference between them is worth knowing:

- **A real `Fastify()` instance, composed by the test** — for example
  `apps/auth-server/src/app/routes/oauth/signature-verification.test.ts`, which registers `formbody`
  and the JWT plugin so it can exercise the same parsers production wires up. Better than a stub,
  but it still only proves the wiring the test itself built.
- **The real assembled app** — the pattern [#365] introduced as
  `apps/auth-server/src/app/error-handler-wiring.test.ts`. It boots the actual application
  composition, asserts a property of it, and is mutation-checked so it fails if the registration
  order regresses. It also pins the two orderings with no runtime signal — `rateLimitPlugin` before
  the route sweep, and `errorHandler` before `cors` — by reading the registration order out of
  `app.ts` itself.

When you add a test whose subject is _wiring_ rather than _logic_, the second pattern is the one
that caught #365; the first would not have. `formbody`'s ordering requirement is guarded the second
way: the assembled app's form-encoded `/oauth/token` tests answer `415` when it is registered after
the routes.

[#365]: https://github.com/qauth-labs/qauth/issues/365

### Shared test vectors

`test-vectors/` holds language-neutral test vectors
([ADR-018 §6](/reference/records/adr/018-1-0-scope-and-stability/#6-sdks-and-the-rust-core)):
plain JSON files of cases, each an `input` and the `expected` result. Every SDK runs them, in
whatever language it is written, and the server's unit tests run them against its own code. The
first files cover PKCE S256 (`libs/server/pkce`), the RFC 9068 access token checks
(`libs/server/jwt`), `act` chain reading with the delegation depth cap
(`apps/auth-server/src/app/helpers/agent-audit.ts`), and Standard Webhooks signatures. The server
has no webhook signer to run the last file against, so the vector library checks it with
`node:crypto` in the meantime.

A test reads a file with `loadVectors(id)` from `@qauth-labs/shared-test-vectors` and rebuilds each
case's whole `expected` object from the code under test, so a wrong value anywhere in a case fails
that case. `pnpm exec nx run test-vectors:validate` checks every file against the `qauth-vectors/1-rc.0`
format. The `test-vectors` project's `test` target depends on it, so it runs in this tier.

Vectors are append-only: changing a case's expected result takes a new case id. The
[`test-vectors` README](../../../../../../test-vectors/README.md) describes the format, how a reader
in another language uses the files, and the versioning rule.

## Tier 2 — integration (testcontainers)

```bash
pnpm exec nx run infra-db:test-integration
# or, directly:
pnpm test:integration
```

Defined at `libs/infra/db/project.json:8`, running `vitest.integration.config.mts`, which includes
only `**/*.integration.test.ts` and allows 60s per test for a cold image pull. Every project with
such suites carries its own `test-integration` target; `libs/infra/db` (repositories and migration
suites) and `apps/auth-server` hold most of them. Since #240 the auth server's E2E suites boot the
real server against testcontainers Postgres **and** Redis.

Files run side by side, on servers the config's global setup
(`libs/shared/testing/src/integration-global-setup.ts`) starts once per `vitest` run: a Postgres
server per worker slot, each with a template database migrated once, and one Redis server. Each file
gets a database of its own (a copy of the template, or an empty one for a suite that applies
migrations itself) and a pair of logical Redis databases, so no file sees another's rows or keys.
Postgres is per slot rather than one server for the run because a server's transaction horizon spans
its databases and the event store reads it. A suite that stops a server or creates roles asks for a
private container (`privateContainer`). `QAUTH_INTEGRATION_WORKERS` sets how many files run at once:
3 on CI by default, half the cores (at most 4) locally. The
[`shared-testing` README](../../../../../../libs/shared/testing/README.md#docker-integration-testing)
has the details.

**This is the only tier that exercises real DDL, and that is not a nice-to-have.** The comment
above the `integration` job in `ci.yml` states the reasoning better than a paraphrase would:

> The `affected` and `coverage` jobs above can never exercise real DDL: every unit suite mocks the
> repositories, and both vitest.config.mts and the coverage gate exclude `*.integration.test.ts`.
> So the testcontainers suites are the ONLY assertion that the generated migrations produce the
> schema the code expects — e.g. that `authorization_codes.state`/`.nonce` are unbounded `text`
> and not the varchar(255) that broke long opaque `state` (#316). Left unwired, a lost migration
> file or a re-narrowed column would sail through a fully green CI.

Both exclusions it names are real and worth seeing for yourself: `vitest.config.mts:23` keeps these
suites out of the fast run, and `vitest.config.mts:62` keeps them out of the coverage report. A
migration that never got committed, or a column quietly re-narrowed by a schema edit, produces no
failure anywhere else.

### It cannot pass vacuously

Locally, an integration suite skips when Docker is not running. On CI it does not: inside
`requireDockerOrSkip` there is a CI branch that throws instead of skipping
(`libs/shared/testing/src/lib/pg-testcontainer.ts:361`), with a message explaining that skipping
"turns the run into a green no-op". The `integration` job in `ci.yml` runs on
a GitHub-hosted runner, which ships a Docker daemon, so the throw is unreachable in practice — it
exists so that a runner _without_ one fails loudly instead of reporting success.

The job is affected-scoped by task: like every `nx affected` run, it runs each `test-integration`
task whose inputs a change reaches, so a schema, migration, or repository change runs it. A pull
request that changes only docs runs no suite, since no `test-integration` input names a docs file.
The inputs are the `integration` named input in `nx.json`, plus what a project's suite reads beyond
it, named in that project's `project.json`. A suite that starts reading a file outside them, such as
a published document or another app's source, must name the file there too, or a change to that
file alone will not run the suite.

Three runners share the suites. Each runs every affected project's `test-integration` with its own
shard of the files (`QAUTH_INTEGRATION_SHARD`, which `vitest.integration.config.mts` reads), so
every file runs exactly once, and the `integration` check passes when all three shards do. To run
one shard locally, set the variable: `QAUTH_INTEGRATION_SHARD=2/3 pnpm exec nx run auth-server:test-integration`.

## Tier 3 — the repo-wide coverage gate

```bash
pnpm exec vitest run --coverage
```

Thresholds live in the root config at `vitest.config.mts:69` — statements 70, branches 55,
functions 65, lines 70 — and the comment there is explicit that they sit comfortably below today's
numbers so the gate passes now and fails on a real regression, to be ratcheted up as the
container-backed suite grows.

CI runs this in its **own job**, `coverage`, separate from the affected per-project
`test` targets, which the `affected (test)` job runs. The reason, from that job's
comment: the per-project runs write per-project coverage directories, so the threshold has to be
evaluated once across the whole fast unit suite rather than per project. Running
`nx affected -t test` locally therefore tells you nothing about the gate; run the command above
before assuming a large deletion is safe.

## The two caching lessons

Both are about Nx's cache, and both are re-breakable by an edit that looks like tidying.

### #285 — `nx test` passed while running zero tests

`nx.json:171` carries the post-mortem in full:

> #285: this was `["sharedGlobals"]`, dropping Nx's built-in `{projectRoot}/**/*` entry. Every
> `default`-hashed target (test, build) therefore hashed only ci.yml and ignored the project's own
> sources, so a cached green `test` result was replayed even after a failing spec was added. Keep
> `{projectRoot}/**/*` first — it is what makes a source edit invalidate the task.

The fixed value is at `nx.json:177`. The failure mode is the dangerous kind: nothing errors,
nothing warns, and the output says the target succeeded — because it did, once, before your code
existed. If you ever see a suite pass suspiciously fast after a change you expected to break it,
re-run with `--skip-nx-cache` before concluding anything.

### The docs-site target's extra `inputs`

`apps/docs-site/project.json:32` overrides the inferred `inputs` array, and the description at
`apps/docs-site/project.json:46` explains every entry. The short version: several of this
project's guards read files **outside** `apps/docs-site` at runtime — `README.md`, `docs/*.md`,
the auth-server route tree, and (coarsely) every `.ts` file under `apps/` and `libs/`. Nx hashes
only what a target declares, so without those declarations, editing the thing a guard checks left
the hash unchanged and Nx replayed a stale cached pass.

Two things to know before touching that array:

- **Setting `inputs` on an already-inferred target replaces the inferred array rather than merging
  into it.** The first six entries are the inferred defaults re-declared, not additions. Delete one
  and its whole category of input silently stops being hashed.
- **A blanket workspace-wide glob was rejected deliberately.** Hashing every file in the workspace
  would also hash `dist/` and `coverage/`, for no benefit an anchor could ever point at.

## Tier 4 — the documentation invariants

`apps/docs-site/src/invariants/` holds four guards that run as part of the ordinary unit tier
(`pnpm exec nx test docs-site`). They are not documentation _about_ the docs — they are executable
assertions that this site has not drifted from the tree.

| Guard               | Entry point                                              | Fails when                                                                      |
| ------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Link resolution     | `apps/docs-site/src/invariants/link-resolution.ts:177`   | A link points at a route, heading anchor, or repository file that is not there  |
| `path:line` anchors | `apps/docs-site/src/invariants/anchor-validity.ts:81`    | A quoted `path:line` names a missing file, or a symbol quoted beside it is gone |
| Endpoint coverage   | `apps/docs-site/src/invariants/endpoint-coverage.ts:127` | The route tree, `openapi.json`, and the API reference page disagree on paths    |
| Status claims       | `apps/docs-site/src/invariants/status-claims.ts:21`      | Prose calls a feature unbuilt while its evidence path exists on disk            |

### What they protect

Each one closes a specific class of rot:

- **Links** rot when a page is renamed or a heading is reworded. The guard resolves internal links
  against the real content tree, including heading anchors, and resolves repo-relative links
  against the filesystem.
- **`path:line` anchors** rot when a file is renamed or a function is deleted. The guard checks the
  file exists and, when a plain identifier is quoted immediately beside the anchor, that the symbol
  still appears in it.
- **Endpoint coverage** rots in both directions — an endpoint added to the spec but never
  documented, or a documented endpoint removed from the spec.
- **Status claims** rot when a feature ships and the prose describing it as future work does not
  get updated. The guard works from an evidence table (`apps/docs-site/src/invariants/status-claims.ts:21`)
  mapping a feature to paths whose existence proves it shipped — deliberately not a list of
  forbidden sentences, because "a sentence list rots the moment prose is reworded, while a path
  either exists or it doesn't".

### What they do not protect — read this before trusting a green run

These are the limits **by construction**, not gaps waiting to be filled:

- **They only reason about this repository.** Every check bottoms out in "does this path exist in
  the tree" or "does this route exist on this site". A claim about how an **external** tool
  behaves — a client library's defaults, a browser's cookie policy, what a specification requires —
  has nothing in the repo to check it against and is outside their reach entirely. Those claims are
  carried by `lastVerified` and human review, nothing else.
- **Line numbers in anchors are not checked.** `apps/docs-site/src/invariants/anchor-validity.ts:77`
  says so directly: they "drift on every unrelated edit above them, and a guard that fails on
  innocent edits gets disabled". A wrong line number survives a green run silently — so when you
  write one, open the file and count. This has already produced a round of corrections on another
  lane.
- **Endpoint coverage proves path-set equality only.** The guard's own comment at
  `apps/docs-site/src/invariants/endpoint-coverage.ts:144` states that the HTTP method is matched
  only to be skipped and never captured, so `` `GET /oauth/revoke` `` would satisfy the check for a
  POST-only endpoint exactly as well as the correct method. It also "cannot tell a real explanation
  from a passing mention": a path named once in a see-also list counts as documented. What legs 2
  and 3 prove, per `apps/docs-site/src/invariants/endpoint-coverage.ts:152`, is that the **set** of
  path strings on the reference page equals the **set** of path keys in `openapi.json` — real
  anti-rot value, but not a correctness check on what the page says about any one of them.
- **`lastVerified` is recorded, not enforced.** Nothing fails when it goes stale; the Reference
  lane's status page surfaces the oldest date instead. See
  [the frontmatter contract](/extend/frontmatter/).
- **`unbuiltClaims: true` disables the status guard for a whole page.** It is a narrow escape hatch
  for pages that legitimately describe something unbuilt, not a way to silence an inconvenient
  failure.

### If a guard fails on your page

The failure message names the page and the offending link, anchor, or phrase. Fix the **content**,
not the guard. If you genuinely believe the guard is wrong rather than your page, that is worth
raising as its own issue — bending content to satisfy a guard has already produced one real defect
in this site's history, and a guard nobody trusts gets deleted.

## Tier 5 — the wire suite

```bash
pnpm nx run wire-suite:run    # against a running server; setup in apps/wire-suite/README.md
```

`apps/wire-suite` talks to a **running** QAuth over HTTP and nothing else. It guards the
wire-level stability promise of [ADR-018 §5](/reference/records/adr/018-1-0-scope-and-stability/):
the contract is what a client sees on the wire, whatever the server is written in.

The `wire-suite` CI job builds the auth-server and migration-runner
images from the pull request, starts them with Postgres 18 and Redis 7, seeds the clients in
`apps/wire-suite/seed/clients.json`, and runs the suite with the rate limits raised. It is not
affected-scoped, for the same reason as the image smoke test: almost any change can break the
image. Its JSON report joins the unit suite's in the spec-conformance matrix, so a wire test that
cites a registered spec section counts as evidence for that row.

Four rules keep it honest:

- **It shares no code with the server.** `nx lint` fails an import of any workspace project into
  the suite, and an import of the suite from anywhere (`scope:wire-suite` in `.oxlintrc.json`).
  A helper used on both sides could carry the same encoding bug and hide it.
- **It refuses to start without `QAUTH_WIRE_ALLOW_WRITES=1`**, because it registers users and uses
  clients on the server it targets.
- **Its `*.wire.test.ts` files never run in the fast tier.** The root config excludes them; only
  `apps/wire-suite/vitest.wire.config.mts` includes them. The suite's own unit tests — the
  configuration guard and the helpers — run with Tier 1.
- **Every stable operation has a wire test.** A wire test's `describe` or `it` title carries the
  operation it checks, as the published OpenAPI document lists it: `[POST /oauth/token]`. After
  the run, `scripts/wire-coverage.mjs` fails when a stable operation has no passing test that tags
  it. An experimental operation is exempt, and so is a stable one that
  `apps/wire-suite/exempt-operations.json` lists with a reason and an issue; that list may only
  shrink, and CI fails a pull request that adds to it. Before any server runs, a unit test,
  `apps/wire-suite/src/operation-coverage.test.ts`, fails when an `/oauth/*` or `/.well-known/*`
  operation has no `call('METHOD /path', …)` in any wire test.

What it cannot catch: anything a client cannot observe. It sees responses, not the database or
the logs, so a write that should not have happened, or a secret in a log line, is outside it.

## The stable-surface guard

The `stable-surface` CI job keeps the files that carry the ADR-018 §5 stability promise in step with
the code and with the last release. It regenerates every surface registered in
`stable-surface/surfaces.json` — today the auth server's OpenAPI document, exported once under
default flags and once with every route switch on — and fails when:

- a committed copy differs from what its generator writes;
- an OpenAPI operation has no `x-qauth-stability`, an operation only a switch registers is not
  `experimental`, or the default-flag export has an `experimental` operation at all;
- a stable surface breaks since the latest release tag — a removed operation or response field, a
  new required request field, a narrowed enum, a changed type, a new required scope — and
  `stable-surface/approved-breaks.json` does not approve that exact change.

`stable-surface/README.md` defines a break in full and says how to register a surface and how to
approve a break. Experimental operations are never compared.

## Before you open a pull request

```bash
pnpm exec nx affected -t lint dependency-checks typecheck test build
pnpm format:check                               # Oxfmt, as the `format` job runs it
pnpm exec vitest run --coverage
pnpm exec nx run auth-server:openapi-export     # if you changed a route; commit both exports
pnpm stable-surface                             # drift, tags and breaks since the last release
pnpm exec nx run infra-db:test-integration      # if you touched schema, migrations, or repositories
pnpm exec nx run auth-server:test-integration   # if you touched wallet federation or credential status
pnpm nx run wire-suite:run                      # against a running server (apps/wire-suite/README.md)
pnpm wire-coverage                              # after a full wire run with the JSON reporter
```

If you changed anything under `apps/docs-site`, add:

```bash
pnpm exec nx run docs-site:typecheck
pnpm exec nx build docs-site
```

On Windows, expect `pnpm format:check` noise unrelated to your change — see the
[CRLF gotcha](/extend/repo-map/#local-development-gotcha-crlf-on-windows).

## See also

- [Request lifecycle](/extend/architecture/) — what the unit tier's stubs stand in for.
- [Repository map](/extend/repo-map/) — the boundary rules `nx lint` enforces.
- [Frontmatter contract](/extend/frontmatter/) — what the docs-site schema requires of a page.

---

# Adding a credential provider

URL: https://docs.qauth.dev/extend/adding-a-credential-provider/

A **credential provider** is how QAuth learns that a user is who they say they are. Password
today; a wallet-backed presentation and upstream OIDC federation are the next two. ADR-003's
promise is that adding one is a **registration**, not a change to the authentication engine — no
new branch in a route, no `if (providerType === …)` anywhere.

This page is the practical version of
[ADR-003](/reference/records/adr/003-credential-provider-interface/). Read the ADR for the decision and its
alternatives; read this for what the code actually does at `HEAD`.

> **A sign-in method with screens or an upstream?** A method that needs Interaction API steps or
> routes of its own, such as an upstream OpenID Connect provider, implements the
> [AuthMethod contract](/extend/auth-method-contract/) instead, which extends `CredentialProvider`.
> That contract is the experimental plugin API, and such a method ships as a plugin package the
> operator installs and an admin enables per realm, with no change to QAuth's own code. This page
> is about the in-tree providers.

## The contract

`libs/sdk/plugin-sdk/src/lib/credential-provider.ts:74`:

```ts
export interface CredentialProvider {
  readonly type: string;
  verify(input: unknown): Promise<VerifiedIdentity>;
  extractAttributes(result: VerifiedIdentity): UserAttribute[];
}
```

Three members, and each carries more meaning than its signature suggests.

### `type`

The discriminator. It is simultaneously the registry key and the value written to
`user_credentials.provider_type`, so it is a **database value**, not just an in-process label.
Changing it after rows exist orphans them.

### `verify(input: unknown): Promise<VerifiedIdentity>`

Takes provider-specific input and returns a normalized identity
(`libs/sdk/plugin-sdk/src/lib/credential-provider.ts:33`):

| Field            | Meaning                                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `externalSub`    | The subject as the **upstream** knows it. Never used as the token `sub` — the engine maps it to `users.id`.    |
| `assuranceLevel` | `'low'` \| `'substantial'` \| `'high'`, aligned to eIDAS LoA / ISO 29115. Propagated downstream as OIDC `acr`. |
| `rawClaims`      | Whatever the provider observed, before normalization.                                                          |

`input` is typed `unknown` on purpose: each provider owns its own input schema and parses it
itself. `'low'` carries no `acr` claim per ADR-003.

Implementations **reject** on verification failure. Returning a placeholder is not an option —
see [fail closed](#the-fail-closed-pattern) below.

### `extractAttributes(result): UserAttribute[]`

Turns a successful verification into rows for `user_attributes`
(`libs/sdk/plugin-sdk/src/lib/credential-provider.ts:53`): a `source`, an
`attrKey`, an `attrValue`, a `verified` flag, and an optional `expiresAt`. `source` is what claim
resolution ranks by, so it decides which value wins when two providers assert the same attribute.

## The registry

`libs/server/federation/src/providers/provider-registry.ts:14` is a `type → provider` map with
three methods and two deliberate throws:

- `register()` throws `ProviderAlreadyRegisteredError` when a `type` is already taken
  (`libs/server/federation/src/providers/provider-registry.ts:51`). That is a fail-fast against
  provider-confusion shadowing: two providers sharing a `type` must not silently resolve to
  whichever registered last.
- `resolve()` throws `ProviderNotRegisteredError` for an unknown `type`
  (`libs/server/federation/src/providers/provider-registry.ts:58`).

Seeding is not a separate code path: `createProviderRegistry` loops the initial providers through
that same `register()` method
(`libs/server/federation/src/providers/provider-registry.ts:68`), so a duplicate in the configured
list fails the boot rather than being silently deduplicated.

`federationPlugin` builds the registry from its `providers` option
(`libs/fastify/plugins/federation/src/lib/federation-plugin.ts:37`) and decorates the instance with
it (`libs/fastify/plugins/federation/src/lib/federation-plugin.ts:39`), which is why routes can
write `fastify.providerRegistry.resolve('password')`.

## The single registration point

`createConfiguredProviders`
(`libs/fastify/plugins/federation/src/lib/configured-providers.ts:302`) is where "which upstreams
exist" is decided, and `apps/auth-server/src/app/app.ts:437` is the only place that calls it.

Two properties make it worth understanding before you extend it:

- **It is a pure function of config.** No I/O, no Fastify, no database. That is what makes the
  flag-to-registry contract unit-testable without booting the auth-server, which would need
  Postgres and Redis.
- **Its option fields are required, not optional.**
  `libs/fastify/plugins/federation/src/lib/configured-providers.ts:78` explains why: a bootstrap
  that gains a new upstream must make a deliberate decision about it rather than inheriting a
  default from the library, and **typecheck** — not code review — is what enforces that. The single
  exception is `provisionedVerifierMaterial`, and only because omitting it _is_ the fail-closed
  answer.

`PasswordProvider` is unconditional
(`libs/fastify/plugins/federation/src/lib/configured-providers.ts:305`) — the authentication method
every deployment depends on, never flag-gated. Everything after it sits behind a flag.

> **How strong is "single registration point"?** It is a convention held up by two things, not by
> the registry API. First, the export allowlist: `libs/fastify/plugins/federation/src/index.ts:16`
> notes that `createPasswordProvider` is re-exported and `createWalletProvider` deliberately is
> **not**, so no bootstrap can construct a wallet provider at all, let alone register one. Second,
> the layering — `apps/auth-server` is `scope:app` and cannot import `libs/server/federation`
> directly (see [Repository map](/extend/repo-map/)). But
> `libs/fastify/plugins/federation/src/types.ts:11` does document
> `fastify.providerRegistry.register()` as an imperative alternative, and that method is public on
> the decorator. Treat imperative registration as an escape hatch that bypasses the config gate,
> and prefer extending `createConfiguredProviders`.

## Why routes never change

The engine resolves a provider by `type` and delegates. Both production call sites look the same:

- **Login** — `apps/auth-server/src/app/helpers/credential-auth.ts:80` resolves the provider and
  `apps/auth-server/src/app/helpers/credential-auth.ts:81` calls `verify()`. It does not call
  `extractAttributes()`; login reads the attributes that already exist.
- **Registration** — `apps/auth-server/src/app/routes/auth/register.ts:228` resolves,
  `apps/auth-server/src/app/routes/auth/register.ts:229` verifies, and
  `apps/auth-server/src/app/routes/auth/register.ts:234` extracts the attributes, which are then
  upserted inside the same transaction as the user and credential rows
  (`apps/auth-server/src/app/routes/auth/register.ts:283`).

Neither site names a provider implementation. Both name a `type` constant. That is the whole
property: a new upstream adds a file and one line in `createConfiguredProviders`, and the routes
above are untouched.

## Worked example — `PasswordProvider`

`libs/server/federation/src/providers/password.provider.ts:93`. Stateless, dependency-free, safe
to construct once at bootstrap.

### The precondition that surprises everyone

**`verify()` does not check the password.** For `type='password'` the secret comparison happens in
the route layer — the caller must have already argon2-verified the presented plaintext against
`credential_data.password_hash` and may only call `verify()` after that succeeded. The module
JSDoc states it, and the input schema enforces it structurally: the contract is
`verify({ email, passwordHash, emailVerified })`
(`libs/server/federation/src/providers/password.provider.ts:51`), which **carries no plaintext at
all**, so there is nothing for the provider to compare even if it wanted to.

This is deliberate — it keeps `libs/server/federation` framework-free — and password is the one
type whose secret check already had a home in the route layer. A wallet or upstream-OIDC provider
verifies its own cryptography inside `verify()`.

If you are writing a caller: `apps/auth-server/src/app/helpers/credential-auth.ts` is the pattern
to copy. It parses `credential_data`, calls `verifyPassword`, and only then resolves the provider.

### What it actually does

```ts
// libs/server/federation/src/providers/password.provider.ts:107
async verify(input: unknown): Promise<VerifiedIdentity> {
  const parsed = passwordVerifyInputSchema.safeParse(input);
  // …
}
```

- **Parses its input strictly.** `.strict()`, because callers construct this object in-process — an
  unknown key is a programming error, not forward-compatible data. A shape violation throws a plain
  `Error`; it is an internal invariant breach and is never mapped to a wire error.
- **Normalizes `externalSub` itself**
  (`libs/server/federation/src/providers/password.provider.ts:118`). `normalizeEmail` is
  idempotent, which guarantees `externalSub === user_credentials.external_sub` regardless of caller
  discipline. Login asserts that equality and fails closed if it ever diverges.
- **Returns `assuranceLevel: 'low'`**
  (`libs/server/federation/src/providers/password.provider.ts:121`) — self-asserted email and
  password is the lowest eIDAS LoA, and `'low'` emits no `acr`.
- **`extractAttributes` throws rather than returning `[]`** when `rawClaims.email` is missing
  (`libs/server/federation/src/providers/password.provider.ts:132`). An empty array would be
  indistinguishable from a credential that legitimately carries no claims.

### Shape ownership

The module is the **single owner** of the `credential_data` JSONB shape for
`provider_type='password'`: `passwordCredentialDataSchema`
(`libs/server/federation/src/providers/password.provider.ts:66`) and
`buildPasswordCredentialData` (`libs/server/federation/src/providers/password.provider.ts:77`),
`{ password_hash, email_verified }` with snake_case keys. Nothing else may hand-roll that object —
a camelCase drift would pass every database constraint and strand every login. Note the asymmetry
with the input schema: this one is deliberately **not** `.strict()`, because later work may add
sibling keys and today's binary must keep parsing then.

If your provider stores anything in `credential_data`, give it the same treatment: one schema, one
constructor, both exported from the provider module.

## The fail-closed pattern

`WalletProvider` (`libs/server/federation/src/providers/wallet.provider.ts`, `createWalletProvider`)
is registered with its two halves in **different** states, and the split is the most useful thing on
this page: **you can land a provider in that state on purpose.**

- **`verify()` still throws unconditionally** (`walletSkeletonError`). It is the non-functional
  skeleton issue #232 shipped, and it must keep throwing — see below.
- **`extractAttributes()` is implemented** as of issue #235. It parses the envelope with
  `walletRawClaimsSchema` and returns real attribute rows via `extractWalletAttributes`; it throws
  only on a **malformed** envelope, not unconditionally.

The module's own header says exactly this — read "Why `verify()` still throws while
`extractAttributes()` works" in the source before assuming either half is a mistake.

### Why a provider like this exists

Epic #231 splits wallet federation across issues that must be developable in parallel. ADR-003's
promise is that adding a provider is a registration rather than an engine change, so the file, the
`type` discriminator, and the registry entry are established up front and the follow-ups fill in
the two method bodies against a stable shell. The module deliberately contains no protocol logic.

### Why throwing is a security property, not laziness

`libs/server/federation/src/providers/wallet.provider.ts:43-78` states both halves:

> - A stub that resolved a placeholder `VerifiedIdentity` would be an authentication-bypass
>   primitive the moment `WALLET_FEDERATION_ENABLED` is flipped or a route wires up
>   `resolve('wallet')` — the auth engine upserts whatever `externalSub` it is handed and mints a
>   token for it, with no provider-specific second guess (that is exactly ADR-003's design).
> - A stub that returned `[]` from `extractAttributes()` would look identical to a working provider
>   handed a credential carrying no claims, silently dropping identity data instead of failing
>   loudly.

The second bullet is now recorded in the source as **#232's original reasoning**, not as a live
description: `extractAttributes()` shipped in #235. It survives as the explanation for why the
implemented method still throws on a malformed envelope rather than degrading to `[]`.

Both failure modes exist **because** the engine is provider-agnostic. The abstraction that makes
new providers cheap also means the engine will not second-guess a provider that lies to it. So the
provider is the only place that can fail closed, and a skeleton must.

The comment ends with an instruction worth repeating: do **not** soften these into no-ops or
placeholder returns to make a caller compile or a test go green.

### The error type is chosen, too

`walletSkeletonError` (`libs/server/federation/src/providers/wallet.provider.ts:494`) builds a
plain `Error`, not a `@qauth-labs/shared-errors` domain error. Domain errors carry
`statusCode`/`code` for the global error handler to map onto the wire — and reaching
for one here would frame this as a reachable, client-facing outcome with a stable error contract. It
is not one. Reaching it means QAuth is mis-wired, and a generic 500 plus a server-side stack trace
is the right signal — minting a dedicated error class in the shared library would create permanent
public wire surface for a condition that must never occur, and would invite treating the condition
as a normal authentication outcome.

### Constants can be load-bearing

`WALLET_SOURCE` (`libs/server/federation/src/providers/wallet.provider.ts:188`) is `'wallet'`, and
its comment flags that `claims/attribute-trust.ts` ranks that literal above every other attribute
source. Changing the constant without changing `rankAttributeSource` would silently demote every
wallet-issued attribute to the bottom rank. `wallet.provider.test.ts` pins the pair — if you add a
provider whose `source` participates in trust ranking, pin yours the same way.

## Flag gating

`WALLET_FEDERATION_ENABLED` is declared at
`libs/server/config/src/lib/schemas/federation.ts:41` and **defaults to `false`**
(`libs/server/config/src/lib/schemas/federation.ts:43`). The schema's comment is explicit that
every capability flag in this workspace defaults off, so a deployment that never sets the variable
gets the behaviour it had before the capability existed.

Inside `createConfiguredProviders` the check is a strict `=== true`
(`libs/fastify/plugins/federation/src/lib/configured-providers.ts:317`), not truthiness — the
string `'false'`, which an unparsed `process.env` value would supply, is truthy in JavaScript. Copy
that pattern for any flag you add; the env schema returns a real boolean, so the strict comparison
only ever fires for a caller that bypassed it, and when one does the flag must read as off.

Turning the flag on is also gated on posture: see
[the fail-closed boot checks](/extend/architecture/#the-fail-closed-boot-checks).

## Adding one: the checklist

1. **Write the provider** in `libs/server/federation/src/providers/<name>.provider.ts`. Export a
   `create<Name>Provider()` factory, a `<NAME>_PROVIDER_TYPE` constant, and — if it writes
   `credential_data` — the schema and constructor for that shape. Keep it stateless and
   dependency-free so it is safe to construct at bootstrap.
2. **Own your input contract.** A Zod schema parsed inside `verify()`, `.strict()` if callers build
   the object in-process.
3. **Decide the assurance level**, and remember `'low'` suppresses `acr`.
4. **Export it from `libs/server/federation/src/index.ts`.**
5. **Re-export what the app genuinely needs** from
   `libs/fastify/plugins/federation/src/index.ts` — and no more. `apps/auth-server` cannot import
   `scope:server` libraries directly, so this file is the seam; the comment at
   `libs/fastify/plugins/federation/src/index.ts:16` is the precedent for leaving a factory out
   when the flag is what should decide.
6. **Add it to `createConfiguredProviders`**, behind a flag if it is incomplete or optional. Add
   the flag to `libs/server/config/src/lib/schemas/federation.ts` with a default of `false`.
7. **Write the unit tests next to the provider.** The registry contract, the fail-closed paths, and
   any constant that another module ranks or matches on.
8. **Change no routes.** If you find yourself editing a route to accommodate the provider, that is
   the signal that something belongs inside `verify()` or `extractAttributes()` instead.

It is entirely acceptable for step 1 to produce a provider whose methods throw. That is a shipped,
reviewed, registered shell that the protocol work fills in later — and it is safer than a partial
implementation, because a provider that fails closed cannot authenticate anyone by accident.

## A note on ADR-003's header

`docs/adr/003-credential-provider-interface.md` opens with a status note from 2026-06-24 saying the
design had no implementation and that federation was pushed to a later phase. **That note is
superseded** by the correction immediately below it (2026-07-21, #304): the interface and registry
shipped in PR #227, the engine calls `provider.verify()` in production, and a second provider has
since landed as a skeleton. Read the correction, not the note above it — and if you are checking
another ADR, look for the same pattern before trusting its header.

## See also

- [Request lifecycle](/extend/architecture/) — where `createConfiguredProviders` is called and what
  it refuses to boot on.
- [Repository map](/extend/repo-map/) — why the fastify plugin re-exports the provider surface.
- [Testing](/extend/testing/) — which tier would notice if you got this wrong.

---

# The AuthMethod contract

URL: https://docs.qauth.dev/extend/auth-method-contract/

> **Experimental.** The AuthMethod contract is QAuth's plugin API, the experimental item
> [`plugin-api`](/reference/experimental-features/#plugin-api). It is public and documented, so
> others can write methods against it, but it is outside the 1.0 stability promise: it may change
> in a minor release without a deprecation window. It becomes stable in 1.x, once QAuth's own
> plugins have matured on it ([ADR-018](/reference/records/adr/018-1-0-scope-and-stability/) §4).

An **AuthMethod** is a sign-in method that plugs into QAuth's engine, such as an upstream OpenID
Connect provider. It extends the [`CredentialProvider`](/extend/adding-a-credential-provider/)
interface of [ADR-003](/reference/records/adr/003-credential-provider-interface/):
`CredentialProvider` stays the verification half, and AuthMethod adds what a method needs beyond
verification. The contract is the npm package `@qauth-labs/plugin-sdk` (`libs/sdk/plugin-sdk/`):
a plugin is written against it in its own repository
([below](#write-a-plugin-in-your-own-repository)), and the server imports it from there.

## What exists today

The contract and its test kit, in the package `@qauth-labs/plugin-sdk`, the registry entries, the
route mount, the plugin runtime and the first method on the contract. With the plugin runtime, a deployment installs plugin packages, the
server loads them at boot, and an admin enables, configures and disables each one per realm
([below](#installing-and-enabling-a-plugin)). The first method is the generic OpenID Connect
upstream client (#601, [below](#the-generic-openid-connect-client)): a library that builds one
method per configured provider, not a plugin package, so nothing registers it in a running server
until provider administration (#714). The upstream sign-in flow (#639) offers the step and acts
on its outcome: each plugin a realm has enabled is one of the realm's upstream providers, and an
account a plugin creates counts as verified. `WalletProvider` is not an
AuthMethod and stays a plain provider whose `verify()` rejects; wallet sign-in keeps its own seam.

## The contract

`libs/sdk/plugin-sdk/src/lib/auth-method.ts` (`AuthMethod`):

| Member                | What it is                                                                                                                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`                | From `CredentialProvider`: the registry key, the `user_credentials.provider_type` value, the `source` of every attribute, and a segment of the route prefix.                                           |
| `verify()`            | From `CredentialProvider`: turns the result the method's own callback returned into a `VerifiedIdentity`, and rejects anything else.                                                                   |
| `extractAttributes()` | From `CredentialProvider`: the attributes of a verified identity.                                                                                                                                      |
| `contract`            | The contract version the method is written against: `qauth-auth-method/1-rc.0`. Its presence is what makes a registered provider an AuthMethod.                                                        |
| `id`                  | The stable name of the method's implementation. Instances of one implementation, one per configured provider, share it; `type` tells them apart.                                                       |
| `display`             | Default display data: `name` (at most 64 characters, under the Interaction API's display rule) and an optional `icon` (a PNG of at most 16 KiB). An admin may override both.                           |
| `configSchema`        | A Zod object schema of the method's config for one realm. A secret member is marked `.meta({ writeOnly: true })`.                                                                                      |
| `steps`               | The Interaction API steps the method contributes, by versioned URN. Today only the upstream step, `urn:qauth:ia:upstream:v1-rc.0`.                                                                     |
| `routes`              | The routes the method mounts below its prefix.                                                                                                                                                         |
| `start()`             | Starts an upstream transaction: where the browser goes, the transaction the method needs back, and the binding the provider carries back.                                                              |
| `secretDestination()` | Optional. Where the config's secret members are sent, as a stable string for a parsed config. The admin API asks for a kept secret again when it changes ([below](#installing-and-enabling-a-plugin)). |

The type rules are strict because `type` lands in four places: lower-case ASCII letters, digits
and `_`, starting with a letter, at most 63 characters. A type with `:` or `/` (an ID-JAG issuer
type, `oidc_<issuer URL>`) never matches, and the types QAuth writes itself (`password`, `wallet`,
`webauthn`, `self_reported`, `totp`, `recovery_code`, `email_code`) are reserved.

## The upstream step

```text
engine offers the upstream step ──► person picks the method
        │
        ▼
start({ uiLocales }, context)  ──► { redirectTo, transaction, binding }
        │  the engine keeps the transaction and its binding server-side,
        │  bound to the interaction and its flow cookie, and sends the
        │  browser on
        ▼
provider ──► GET /upstream/<type>/callback?code=…&state=<binding>
        │  the host compares the binding with the pending transaction's
        │  (constant time) BEFORE it takes the transaction; with none, or
        │  a binding that does not match, it answers transaction_mismatch,
        │  the transaction stays pending and the method never runs.
        │  Otherwise it takes the transaction (once) and hands the
        │  callback the query and the transaction; no header, no cookie
        ▼
callback ──► result | declined | failed (reason)   (a throw: a fault)
        │
        ▼
engine: verify(result) ──► VerifiedIdentity, checked, assurance capped
        extractAttributes() ──► attributes, each with source = type
```

1. **Start.** The engine calls `start()`. The method answers where the browser goes, the
   transaction it needs back (a fresh `state`, a `nonce`, a PKCE verifier) and the **binding**: a
   fresh random value the authorization request carries to the provider and the provider carries
   back, usually the `state` itself. The engine checks the answer (`startUpstreamStep`): the
   redirect is an absolute `https` URL with no credentials and no fragment, the transaction is an
   object of JSON data of at most 4096 bytes, and the binding is 22 to 512 base64url characters
   (22 is the length of 128 random bits; the check is of length and alphabet, the method makes it
   random). The host keeps the transaction with its binding (`PendingUpstreamTransaction`).
2. **Callback.** The provider sends the browser back to one of the method's callback routes. The
   host reads the pending transaction the flow cookie names without taking it, and compares the
   binding the callback carries with its binding, in constant time (`upstreamBindingMatches`). The
   callback carries it in the route's `bindingParameter`, `state` unless the route names another:
   a query parameter of a `GET` route, a form member of a `POST` one, exactly once. With no pending
   transaction (no flow cookie, another interaction, a replay) or a binding that is missing,
   empty, repeated or another start's, the host answers `transaction_mismatch` itself: the method
   never runs, so it never spends the code, and the transaction stays pending, so a request from
   another site cannot cancel the sign-in. Otherwise the host takes the transaction, once, checks
   the binding of what it took again, and hands the transaction to the route's handler, which
   checks the provider's answer and answers one of three outcomes: `result`, `declined` (the
   person cancelled at the provider, `access_denied`), or `failed` with a reason from a closed set
   (`transaction_mismatch`, `provider_error`, `invalid_response`, `upstream_unavailable`). A
   handler may compare `state` with its transaction again; it costs nothing. A handler that
   throws, or a context the host cannot build (an `AuthMethodConfigError`), is a fault: the mount
   hands the engine an `AuthMethodFaultError` with the error as its cause, through the same
   completion as every other outcome, never a raw 500.
3. **Identity.** The engine (`completeUpstreamStep`) passes a `result` to `verify()`, checks the
   identity it resolves (an `externalSub` of 1 to 255 characters of well-formed text with no
   control character, an assurance level, raw claims of JSON data within 64 KiB, which it copies
   and freezes; a claim that is `undefined` or a `Date` is not JSON data and makes the answer a
   fault), then takes the attributes. The raw claims name the issuer that assigned
   `externalSub`, as `rawClaims.iss`: a subject is unique only within its issuer (OpenID Connect
   Core 1.0 §5.7), so the upstream sign-in flow (#639) stores the issuer with the credential,
   refuses a later sign-in under another one, and refuses an identity that names none. The assurance level is capped: `completeUpstreamStep` takes
   `{ maxAssurance }` and lowers the method's level to it, `low` when the caller names none, since
   an upstream sign-in ranks with a password until an operator raises the ceiling for a provider
   it trusts more. Every attribute's `source` must equal the method's `type`: a method cannot
   write attributes under another source, such as `wallet`, which outranks every other in claim
   resolution. An attribute value is well-formed text too (Postgres stores a lone surrogate as
   U+FFFD, which would make two values one), and the engine builds the checked list and copies
   each `expiresAt` itself. A `verify()` rejection ends the step as `verification_refused`; any
   other broken answer is an `AuthMethodFaultError`, and the engine acts on none of it.

The graph of this step is `graphs/flows/federation/upstream-step/flow.yaml`.

## What a method is handed

Plugin code is trusted code that runs in-process
([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/) Decision 12), and
the contract hands it only what it needs. `createAuthMethodContext`
(`libs/sdk/plugin-sdk/src/lib/context.ts`) builds the context, with five members:

- `config`: the realm's config of the method, parsed by `configSchema`, copied and deep-frozen.
  It must be plain data (objects, arrays and primitives): a parsed config that holds a `Map`,
  `Set`, `Date` or other class instance is refused with an `AuthMethodConfigError` naming the
  member, since none of them freezes;
- `egress`: `request()` over the egress client, so every outbound call is checked (ADR-019
  Decision 8). It passes on only `method` (`GET` or `POST`), `url`, `headers`, `body`, `purpose`
  and `source` (`operator`, `admin` or `remote_document`, never a destination a client or an end
  user chose), and adds the realm's name itself: a method cannot pick another realm's allowlist
  entries or lift the client's caps. `operator` and `admin` are the labels the realm's allowlist
  applies to, for non-public addresses, so the adapter keeps them only for a URL whose origin is
  the origin of a URL among the plain members of the method's parsed config, never a secret
  member; any other call goes as `remote_document`.
  `redirect: 'error'` makes a redirect answer reject the call before anything goes to its target
  (the host client's `maxRedirects: 0`, the one cap a method may set, since it can only tighten);
  a call that carries a credential in its body uses it, or a `307` would send that body on.
  `follow`, the default, follows each redirect after the same checks as the first URL;
- `signer`: `signClientAssertion()` and `getUpstreamJwks()` over the signer role, with the realm,
  the provider and the caller role fixed by the host. Signatures, never a key (ADR-019 Decision 9).
  An assertion gets `iat` when its claims carry none (a future one is refused), and its `exp` is
  lowered to at most five minutes from now;
- `log`: a logger's four levels, with a fields object and a message. The fields are nested under
  `authMethod`, so a method cannot overwrite the line's `reqId` or `realm`, as a copy in which
  `code`, `code_verifier`, `client_secret`, `client_assertion`, `refresh_token`, `access_token`,
  `id_token`, `nonce` and `password` are redacted at any depth, matched without regard to case,
  `_` or `-` (`clientSecret` matches `client_secret`). The last segment of each of the method's
  secret paths is redacted the same way, and each secret's value is cut out of every string and
  of the message;
- `routeUrl(path)`: the absolute URL of one of the method's own routes on the realm host, for a
  `redirect_uri`. Only a path the method's `routes` declare.

Each member is an adapter the builder writes, not a bound copy of the host's function, so the host
can hand over its whole egress client, signer and logger and the method still reaches nothing
more. No database or cache handle, no private key, no Fastify instance, no request header and no
cookie.

The plugin runtime builds the context for the request's realm
(`apps/auth-server/src/app/helpers/auth-method-plugins.ts`): the realm's stored config with its
secret members decrypted back into place, the method's `type` as the signer's provider, and the
request's logger with the plugin's name. The context signs and decrypts as `api`: its grant holds
`signClientAssertion`, and among the stored secrets it may decrypt are a plugin secret's
`auth-method-plugin:<plugin>:<package>:<type>:<path>` contexts, beside a realm's mail secrets and
an upstream OpenID Connect client's secret. `web`, which serves a plugin's routes, may neither decrypt nor sign
a client assertion, and `local` would open every stored secret. The admin API seals a value for a
configure (`secrets.seal`) and opens it as `admin`, whose grant encrypts and decrypts only
`admin-sealed-value:` contexts; it stores a plugin secret sealed again as `local`, as the realm
secret store does, and opens a stored one as `api`. In a single deployment every role shares the
signer's process. A deployment that runs the signer apart (#497) still needs a grant for the admin
API's storing, since the signer service takes the role from the caller's certificate and never
accepts `local` from a peer; until then a process without the signer refuses the call.

## Routes

A method declares its routes as data and never touches Fastify. `authMethodRoutesPlugin`
(`libs/fastify/plugins/federation/src/lib/auth-method-routes.ts`) mounts each registered method's
routes under its own prefix, `/upstream/<type>`, as `browser` routes: they answer on the realm's
primary host only, where the flow cookie lives. A route path is one to four lower-case segments,
such as `/callback`; no dot segment, encoded character, parameter or wildcard can match, so a
route cannot leave its prefix, and the mount checks the joined path again. Each provider gets its
own callback URL, so a response meant for one provider cannot be replayed at another.

There are two kinds of route:

- a **callback** route gets the query, the form and the taken transaction, once its binding
  matched, and answers an outcome that goes to the engine. It may name the parameter that
  carries the binding back (`bindingParameter`, `state` by default);
- a **bounce** route gets no transaction and no context, and may only send the browser to one of
  the method's own `GET` callback routes on the same origin, with a query that is a plain object
  of strings. It is for a provider's `form_post`, which arrives cross-site without the
  `SameSite=Lax` flow cookie. Anyone can send that POST, so the code it runs holds no egress
  client, no signer and no config. A bounce that throws or goes elsewhere is a fault, handed to
  the engine like a callback's.

A route has no `HEAD` twin, a `POST` route reads only a urlencoded form (a JSON body reaches the
method as an empty form), and a method sees at most 64 parameters, each at most 8192 characters,
a repeated one as a list of at most 16, in a frozen object with no prototype
(`authMethodParameters`; the test kit hands a method the same objects). The request log censors
the value of a `code`, `id_token` or `access_token` parameter in the logged URL: an upstream
authorization code rides there, and a bounce may carry a provider's tokens on.

The path carries no version: the callback URL is registered at the provider, and a path that
changed at 1.0 would break every registration.

## Registration

The provider registry holds AuthMethods beside plain providers, in one `type` space
(`libs/server/federation/src/providers/provider-registry.ts`). `resolveAuthMethod(type)` finds
only an AuthMethod, `findAuthMethod(type)` answers `undefined` for a type that came from a
request and names none, and `authMethods()` lists them for the mount. `resolve(type)` answers a
plain provider as registered, and for an AuthMethod's type a fail-closed stand-in whose
`verify()` rejects and `extractAttributes()` throws: an AuthMethod's `verify()` resolves for its
own callback's results, so it is handed out only to the engine's upstream step.
The registry keeps a frozen snapshot of each method, read once and validated as kept: the `type`
it checked, the routes it mounts and the members the engine calls cannot change afterwards. A
provider that carries a `contract` member is held to the whole contract at registration, so a
method written against another contract version, with a route that could leave its prefix, or
under a reserved type, fails the boot, and so does a duplicate `type`.
`createConfiguredProviders` takes the methods to register (`authMethods`), holds every entry to the
whole contract (one with no `contract` member too, which the registry alone would take for a plain
provider) and appends them after the built-in providers; leaving them out registers none. The
auth server passes the methods of the plugins it loaded at boot.

## Packaging a plugin

A plugin is an npm package that exports its method as `authMethod`
(`AUTH_METHOD_PLUGIN_EXPORT`; a CommonJS package may put it under `default`):

```ts
// index.ts of @example/qauth-plugin-corp-sso


export const authMethod: AuthMethod<CorpSsoConfig, CorpSsoTransaction> = {
  contract: AUTH_METHOD_CONTRACT, // 'qauth-auth-method/1-rc.0'
  type: 'corp_sso',
  id: 'corp-sso',
  // display, configSchema, steps, routes, start, verify, extractAttributes
};
```

A package for an OpenID Connect provider may export an `upstreamOidcPreset` instead, whose method
the server builds on its own client ([Preset plugins](#preset-plugins-on-the-generic-client)). It
exports one of the two, never both: the loader refuses a package with both, or with neither.

One package holds one method. Its `id` is the name the admin API gives the plugin, and stays the
same across versions of the package; its `type` is the segment of its routes,
`/upstream/<type>/…`, and the value written to `user_credentials.provider_type`. A realm's state
of the plugin belongs to the package and the type that wrote it: keep both across versions, or
every realm has to configure the plugin again
([The plugin that wrote the state](#the-plugin-that-wrote-the-state)).

**Taken names.** A plugin's `type` may not be a type QAuth writes itself
(`RESERVED_AUTH_METHOD_TYPES`), which the registry and the kit refuse. Nor may it start with
`oidc_`, and its `id` may not be `oidc`: the namespace belongs to the
[generic OpenID Connect client](#the-generic-openid-connect-client). The kit lets these two pass,
since it checks that client's methods too; the plugin loader refuses them, and the boot fails.

**Secret members.** A member of the config schema marked `.meta({ writeOnly: true })` is a secret,
such as a client secret. The runtime reads the marks from the schema's JSON Schema, from its input
side and from its output side. A secret is a string, or a nullable one, at any depth of nested
objects, marked on the input side or on the output side of a pipe that keeps its path and its
string. It may sit inside a union whose branches are all objects, such as a discriminated union of
client authentication methods, when every branch with a member at its path marks it there, on the
same side of the schema: a branch without the member (`private_key_jwt` beside
`client_secret_basic`) takes no secret. The
runtime puts a stored secret back at its path whatever branch the plain config takes, so a
configure that switches to a branch without the member clears the secret in the same request
(`"secrets": { "<path>": null }`), or a plugin whose branches are strict objects refuses the
config. A schema that is not an object, that holds a part JSON Schema cannot describe (a `Set`, a
`Map`, a date, a custom check), or that marks a member inside a list, a record, a recursive part
or a union with a branch that is not an object (a nullable object among them), in one branch of a
union and as a plain member of another, behind a pipe that reshapes or renames it, or one that is
not a string, is refused at boot: the runtime could not keep it write-only. So is a schema built with a Zod copy that keeps
a metadata registry of its own (Zod 4.6 shares one between copies): build a plugin against the
server's Zod, as a peer dependency.

## Installing and enabling a plugin

**Installing.** The operator installs the package with the deployment, as any other dependency
of the auth server ([into the published image](/operate/images/#add-a-plugin-to-the-image)), and
lists it in `AUTH_METHOD_PLUGINS` by package name, comma-separated. A
path, a URL or a `file:` or `git+` specifier is refused: the server never fetches code, and the
admin console never uploads or edits it.

```sh
AUTH_METHOD_PLUGINS=@example/qauth-plugin-corp-sso
PLUGIN_API_ENABLED=true
```

**At boot**, a process that serves the sign-in pages or the admin API imports each listed package,
checks the contract version its method declares first (a plugin built for another version says
so, whatever else it breaks), holds the method to the whole contract, reads its secret members and
registers it after the built-in providers. A package that is not installed, throws as it is
imported, exports no `authMethod`, is written against another contract version, or repeats another
plugin's `id` or `type` stops the boot. The boot logs one line per plugin it loads.

**The switch.** A plugin outside QAuth's first-party list loads only while
`PLUGIN_API_ENABLED=true`, and then the server logs the experimental warning of `plugin-api` at
every boot; a process that loads plugins and holds the `signer` role, as a single deployment
does, logs one more line saying that plugin code runs beside the signing keys and the KEK. With it
off, such a package is never imported, and the boot logs a warning saying why.
A plugin on QAuth's first-party list loads whatever the switch says. The list is fixed in the
server's code (`FIRST_PARTY_AUTH_METHOD_PLUGINS`), never a setting, and it is empty: a first-party
plugin released from its own repository, such as the GitHub one, loads like any other package until
it joins the list ([ADR-018](/reference/records/adr/018-1-0-scope-and-stability/) §3). Discovery
has no member for plugins, and their routes
are left out of the OpenAPI documents.

**Per realm**, every plugin starts off. The admin API's plugin operations, under
`/admin/v1-rc.0/realms/{realmId}/plugins`, list the installed plugins with the realm's state of
each (`plugins.list`, `plugins.get`), replace a
plugin's config (`plugins.update`, `POST …/plugins/{plugin}/config`) and turn it on and off
(`plugins.enable`, `plugins.disable`). `{plugin}` is the plugin's `id`. The three writes change
which upstream credentials sign users in, so each is a
[security operation](/reference/security-operations/) with the effect `credential-path`: it needs
`qauth:admin:security` (the permission `plugins.security`) and an approval, and
`qauth:admin:write` reaches none of them. Each of the three names in its body the `version` of
the state it acts on, as its read gave it (`{ "version": 1 }` for an enable or a disable), so the
approval binds it and the approver sees it, and a state that moved since answers 412: two approved
configures never overwrite each other unseen, and an approved enable never turns on a config its
approver never saw. Each may carry `If-Match` too.

**Secrets.** A plugin's secret members follow the rule of every security operation: the operation
takes a secret only sealed ([API conventions](/reference/api-conventions/#approvals)). A secret's
value reaches the server in one request only: `secrets.seal`
(`POST /admin/v1-rc.0/realms/{realmId}/secrets/seal`), for the operation `plugins.update`, the
member `/secrets/<path>` (the path written as a JSON Pointer token: `~` as `~0`, `/` as `~1`) and
the params `{ "plugin": "<id>" }`, which encrypts it with the realm's `data_at_rest` key, bound to
that operation, member, plugin, the package and type installed under it, and the realm, and
answers the ciphertext. It changes nothing, so it is a write under `secrets.seal`. A configure request then sends the plain members
under `config` and names each secret member under `secrets`, by path: `{ sealed }` sets one to the
sealed value, `null` clears it, and one it does not name keeps its value, unless the configure
sends the plugin somewhere new: a configure that keeps a stored secret while a member whose value
is an http(s) URL is added or changes origin is refused with `400`, naming the secrets to seal
again, so a kept secret never follows a destination it was not set for (as the upstream OpenID
Connect client refuses a changed issuer or token endpoint). So the request an
approval stores until it is used, and the digest it is bound by, hold a ciphertext, never the
value. The handler opens each sealed value for `plugins.update`, its member, the plugin of the path with
the package and type installed under it, and this realm (a value sealed for another operation,
member, plugin, package, type or realm is refused with `400`, so a secret sealed while one package
was installed is never handed to another), and stores it sealed
again under the plugin's own context, bound to the plugin, its package and type, and the member:
what the approval bound is never what is stored. The whole config, secrets included, must pass the
plugin's own schema; a plugin is
enabled only with a config that does. A secret member sent under `config`, however it is spelled,
is refused. No response, audit row, event or log line holds a value: the representation says only
which secret members hold one, and the audit row of a configure names the secrets it set or
cleared. A member that a newer version of a plugin marks secret is never shown or handed to the
plugin from the plain config an older version stored, and leaves it at the next write.

**A plugin's own destination** (#1031). The URL rule above holds every plugin, and reads only the
URLs among the plain members, and only their origins. A plugin whose destination depends on
another member, such as a tenant that shapes an issuer's path, or on a URL's path, names it with
`secretDestination(config)`, and is held to that too: once the new config passes the plugin's
schema, the handler calls it for the stored config, parsed with the secrets it was stored with,
and for the new one, parsed with those the realm will hold, and a configure that keeps a stored
secret while the two differ is refused with the same `400`. So a secret member the plugin routes
by, replaced while another is kept, moves the kept one too; a stored value the configure replaces
or clears is opened for this comparison alone. A configure for which either destination cannot
be told is refused as well: a stored value that does not open, a stored config the plugin's
schema no longer takes, or a hook that throws or answers no string. The hook only
adds a refusal; it never lifts the URL rule. Its result is compared, never logged, stored or
answered. It is a check made at each configure: the stored secret's context does not name the
destination, as the upstream OpenID Connect client's does, so a new version of a plugin that maps
the same config elsewhere sends the stored secret there without asking for it again.

```http
POST /admin/v1-rc.0/realms/{realmId}/secrets/seal
{ "operation": "plugins.update", "member": "/secrets/clientSecret",
  "params": { "plugin": "corp-sso" }, "value": "…" }
→ 200 { "operation": "plugins.update", "member": "/secrets/clientSecret", "sealed": "v1.…" }

POST /admin/v1-rc.0/realms/{realmId}/plugins/corp-sso/config
QAuth-Approval: {approvalId}
{ "version": 0,
  "config": { "issuer": "https://idp.example", "clientId": "qauth" },
  "secrets": { "clientSecret": { "sealed": "v1.…" } } }
```

**A disabled plugin's routes** answer `404` with the `not_found` document of a path no route
serves, before the request's body is read and without the rate limit's headers; disabling keeps
the config. They are checked after the rate limit, so a flood past it answers 429 where an unknown
path answers 404: that tells a plugin of that type is installed, never which realms have it on.

### The plugin that wrote the state

A realm's state of a plugin is keyed by the plugin's `id`, and it records the npm package and the
`type` of the plugin that wrote it. A secret is sealed under a context that names both
(`auth-method-plugin:<id>:<package>:<type>:<path>`). So when the deployment puts another package
behind the same `id`, or a version of the package changes its `type`, the new plugin inherits
nothing from the realm: neither the switch, the config nor the secrets. Until the realm configures
it again:

- its routes answer `404`, as for a disabled plugin, and the sign-in page offers no button for it;
- its stored secrets do not open, and count as unset;
- `plugins.get` and `plugins.list` show it as off, with `configuredBy`, the package and type that
  wrote the state, and `mismatch`, why the state is not this plugin's: `package_changed`,
  `type_changed`, or `package_unrecorded` for a state written before QAuth recorded the package;
- `plugins.enable` is refused with `400`.

A configure (`plugins.update`) under the installed plugin writes the state again for it, off, with
each secret sealed again for it: a secret it does not send again is not kept. An approved enable
then turns it on. `plugins.disable` turns the stored switch off and keeps the rest, so the state
stays off if the other package comes back.

A new version of the same package, with the same `id` and `type`, keeps the realm's state as it is:
it stays on, and its secrets open.

A realm state written by QAuth 0.2, which recorded no package, reads as `package_unrecorded` after
the upgrade: configure and enable each plugin again in each realm that used it. During a rolling
upgrade, such a plugin stays on at the nodes of 0.2 and is off at the new ones; configure no plugin
until every node runs the new release, since a node of 0.2 neither records the package nor seals
under the new context, and opens no secret the new nodes sealed.

## The generic OpenID Connect client

`libs/server/upstream-oidc` (`@qauth-labs/server-upstream-oidc`) is the relying-party client QAuth
uses toward an upstream OpenID Provider: `createUpstreamOidcMethod({ type, display })` builds one
AuthMethod per configured provider, with the `id` `oidc`. It makes no account decision; the
upstream sign-in flow (#639) looks the identity up by `(realm, type, externalSub)` and decides.

**Callback path.** A provider's `type` is `oidc_` and a lower-case alias (`oidc_corp`), so its
callback is `/upstream/oidc_<alias>/callback` on the realm host, one per provider, and the
`redirect_uri` an operator registers at the provider is
`https://<realm host>/upstream/oidc_<alias>/callback` (`upstreamOidcRedirectUri`). The same path
answers `GET` (a `query` response) and `POST` (a `form_post` response, which the bounce sends on to
the `GET` callback on the same origin, so the browser brings the `SameSite=Lax` flow cookie).

**Config** (`upstreamOidcConfigSchema`): `issuer`, `clientId`, `clientAuthentication`
(`client_secret_basic` or `client_secret_post` with a `writeOnly` `clientSecret`, or
`private_key_jwt` with the key's `signingAlgorithm`), `scopes` (with `openid`; `openid email
profile` by default), `responseMode` (`query` or `form_post`), `idTokenSigningAlgorithms`
(asymmetric only, never `none` or `HS*`), `fetchUserinfo`, and optional `endpoints`.

What it does:

- **Discovery** reads `<issuer>/.well-known/openid-configuration` through the egress client, as an
  `admin` destination. The document's `issuer` must equal the configured one byte for byte, every
  URL it names is an `https` URL with no credentials or fragment, and each goes out as a
  `remote_document` destination, which the egress allowlist never opens: a discovered endpoint
  never reaches a private or loopback address, whatever the allowlist says. A provider on a
  private address sets `endpoints` by hand instead (authorization, token, JWKS, optional userinfo,
  and whether it sends `iss`); those are `admin` destinations, which an allowlist entry naming the
  realm may open, and no discovery document is read.
- **The authorization request** carries `response_type=code`, the client id, the provider's own
  `redirect_uri`, the scopes, a fresh `state` (the binding), a fresh `nonce` and PKCE with S256.
- **The callback** checks the transaction is this provider's (its type, issuer and
  `redirect_uri`), checks `iss` (RFC 9207: a response naming another issuer is refused, and so is
  one without `iss` from a provider that says it sends it), ends as `declined` on
  `access_denied`, and redeems the code with the verifier.
- **Client authentication** at the token endpoint is `client_secret_basic` (each part
  form-urlencoded first, RFC 6749 §2.3.1), `client_secret_post`, or `private_key_jwt`: the signer
  role signs the assertion with the realm's `upstream_client_assertion` key for the provider
  (`iss` and `sub` are the client id the signer's upstream configuration names, `aud` the issuer,
  with a fresh `jti` and a 60-second `exp`). The method sends the string it gets back and never
  sees a key.
- **The ID token** is checked against the provider's key set (fetched through the egress client,
  kept at most five minutes, fetched again for an unknown `kid` at most once a minute) with an
  allowlist of algorithms, then `iss`, `aud`, `azp` (required when there are several audiences),
  `exp`, `iat` (at most ten minutes old) and `nonce`, with 30 seconds of clock tolerance.
- **Userinfo**, when `fetchUserinfo` is set, must carry the ID token's `sub`. The identity's
  `externalSub` is the provider's `sub`, and its `rawClaims` are the ID token's claims over the
  userinfo claims, `iss` among them. The protocol claims (`acr`, `amr`, `auth_time`, `sid`, `nonce`,
  the validity claims and the hashes) come from the signed ID token alone; userinfo's are dropped. `extractAttributes()` takes the standard profile claims that
  are plain text; `email` and `phone_number` are verified only when the provider's own
  `*_verified` claim is `true`.
- **Every call** asks for `redirect: 'error'` (no redirect is followed) and has its own deadline
  and response cap: 5 seconds and 64 KiB for discovery, the key set and userinfo, 10 seconds and
  64 KiB for the token request. These only stop the method waiting and reading: they abort no
  call and limit nothing the egress client fetches. The host egress client's own limits,
  `totalTimeoutMs` and `maxResponseBytes`, bound the underlying call.

**The stored client secret.** `sealUpstreamOidcConfig` encrypts it with the realm's
`data_at_rest` key through the signer role, under the context
`upstream-oidc:client-secret:<realm id>:<type>:<destination>`, where `<destination>` is the
SHA-256 of the issuer and, for endpoints set by hand, the token endpoint. So a ciphertext moved to
another provider or realm does not decrypt, and neither does one whose config was pointed at
another host: an admin who cannot read the write-only secret cannot send it elsewhere by changing
`issuer` or `endpoints.token`. `openUpstreamOidcConfig` refuses such a config with
`UpstreamClientSecretDestinationChangedError`, and provider administration (#714) asks for the
secret again whenever either value changes. The signer lets the `api` role decrypt a context under
`upstream-oidc:client-secret:`, and neither `web` nor `delivery`. `openUpstreamOidcConfig` decrypts
the secret for the method's context, and `describeUpstreamOidcConfig` is the view an API or event
may carry, with neither the secret nor its ciphertext. Where the stored form lives is provider
administration's (#714): the client is not a plugin package, so the plugin runtime's
`realm_auth_method_plugins` (#600), which seals a plugin's secrets under contexts of its own, does
not hold it.

**How the sign-in flow ties the subject to its issuer.** `externalSub` is the provider's bare
`sub`, and the type `oidc_<alias>` does not name the issuer, while only `iss` and `sub` together
identify a person (OpenID Connect Core 1.0 §5.7). `rawClaims.iss` is always the checked issuer,
and the upstream sign-in flow (#639) stores it with the credential and refuses a later sign-in
under another issuer, so a provider re-pointed at another issuer never hands its subjects the
old accounts. The host opens the stored
config and builds the method's context as a signer caller that may decrypt the client secret and
sign client assertions: `api` may do both, and `web`, which serves the sign-in pages where a
method's routes mount, may do neither. So in a single deployment the host calls as `local`, as the
plugin runtime does ([above](#what-a-method-is-handed)); which role calls once the signer runs
apart is #497's.

**At registration.** `checkUpstreamOidcProvider(egressClient, realmName, config)` runs discovery
and the egress client's address checks on every endpoint without calling it, and answers one
finding: `invalid_config`, `discovery_unavailable`, `invalid_document` or `destination_refused`.
Each use checks again, since every call goes through the egress client.

## Preset plugins on the generic client

A preset is a plugin for one named provider that runs the generic client's code under its own id,
type and config (#951). It lives in its own repository and depends only on the SDK (#671): its
package exports the preset as `upstreamOidcPreset`, made with `defineUpstreamOidcPreset`, and the
plugin loader builds its AuthMethod on the server's client (`createUpstreamOidcPresetMethod`). The
protocol code is the server's, so the plugin carries none of it.
[Write a preset plugin](/extend/preset-plugins/) is the guide:

```ts



export const upstreamOidcPreset = defineUpstreamOidcPreset({
  id: 'example-idp',
  type: 'example_idp',
  display: { name: 'Example IdP' },
  origins: ['https://idp.example.com'],
  configSchema: z.strictObject({
    clientId: z.string().min(1).max(255),
    clientSecret: z.string().min(1).max(1024).meta({ writeOnly: true }),
  }),
  upstreamConfig: (config) => ({
    issuer: 'https://idp.example.com',
    clientId: config.clientId,
    clientAuthentication: { method: 'client_secret_basic', clientSecret: config.clientSecret },
  }),
});
```

- **Its own names.** Its `id` is never `oidc` and its `type` never starts with `oidc_`, so the plugin
  loader takes it as any plugin: it loads only while `PLUGIN_API_ENABLED` is on, as no provider
  plugin is on the server's first-party list. Its callback is `/upstream/<type>/callback` on the
  realm host: the `redirect_uri` to register at the provider.
- **Its own config.** An admin configures it with the plugin operations
  ([above](#installing-and-enabling-a-plugin)). `upstreamConfig` turns the parsed config into the
  generic client's config at every use; discovery, PKCE with S256, the callback, the ID token
  checks, `verify()` and the attributes are the generic client's, under the preset's type.
- **Its client secret stays write-only.** It is a member the preset's schema marks `writeOnly`,
  inside a discriminated union of client authentication methods if the preset offers several, so
  the runtime seals it under the plugin's own context and no response, event or log line shows it.
  A config whose client secret is not the value of such a member is refused: it would be stored in
  the clear.
- **Its secret is bound to its provider.** The generic client binds a stored secret to the issuer
  and token endpoint it was entered for; a plugin's secret is bound to the plugin. So a preset
  names the `https` origins its provider answers on (`origins`), every host its endpoints are on
  included, and the client calls no endpoint off them. A config whose issuer, or any endpoint set
  by hand, is on none of them is refused where the host parses it: at the configure (400, naming
  no value) and at every use. A discovery document that names an endpoint off them is refused at
  the sign-in, before any call to it. Whatever a realm's admin sets, the secret goes to that
  provider's origins and to no other host. A provider whose host the admin chooses is a generic
  provider, not a preset.
- **A configure that moves its secret asks for it again.** Within those origins, the preset's
  `secretDestination` names the issuer and the token endpoint set by hand that `upstreamConfig`
  makes for a config, as the digest the generic client binds its stored secret to
  (`upstreamClientSecretDestination`). A configure that changes either and keeps the stored secret,
  through a member that shapes the issuer's path such as a tenant, or through a token endpoint's
  path, is refused with `400` ([above](#installing-and-enabling-a-plugin)): the secret is sealed
  again, as the generic client asks for it again. A discovered token endpoint is not part of it,
  since discovery reads the issuer's own document. The URL rule still holds the preset too, so a
  URL member that moves to another of its origins asks for the secret again as well.
- **No secret elsewhere.** A config whose provider config carries a secret member's value anywhere
  but in the client secret (the client id, a scope, a URL) is refused: it would go out, and be
  logged, in the clear.
- **No allowlisted address.** Every call goes out as a `remote_document` destination unless the
  preset's own config names its origin (the context's rule, [above](#what-a-method-is-handed)), so
  a preset whose config names no URL never reaches a private address the egress allowlist opens.

- **What only a preset sets.** A client secret the signer signs (`signed_client_secret`), a
  multi-tenant issuer template (`tenantIssuer`), response members its `form_post` bounce carries,
  identity claims and attribute rules ([Write a preset plugin](/extend/preset-plugins/)). A realm's
  admin, who writes the generic client's config, sets none of them.
- **Its attributes rank with `oidc_*`.** Claim resolution ranks the attributes of a method the
  loader built from a preset with an `oidc_*` provider's, since the server's client checked the ID
  token. A plugin that exports its own `authMethod` keeps an unknown rank, whatever its type.

A preset's method passes the contract test kit as the generic client does, and
`checkUpstreamOidcPreset` of the SDK's `/testing` entry point checks the preset itself
([Write a preset plugin](/extend/preset-plugins/#check-it-with-the-preset-kit)).

## Checking a method: the contract test kit

`checkAuthMethod(method, scenario)` is the one function a method's author calls, in any test
runner. The author plays the provider: the scenario gives a config, answers the method's
outbound calls, and says what the browser comes back with. It is test support: it comes from the
SDK's `/testing` entry point, never the main one, and it refuses to run with
`NODE_ENV=production`, because it replaces the global `fetch` while it runs.

```ts


it('meets the AuthMethod contract', async () => {
  await checkAuthMethod(myMethod, {
    config: { clientId: 'kit-client', clientSecret: 'kit-secret' },
    egress: (request) => fakeProvider.answer(request),
    callback: (authorizationRequest) => fakeProvider.signIn(authorizationRequest),
    declined: (authorizationRequest) => fakeProvider.decline(authorizationRequest),
  });
});
```

It resolves with the checks it ran and rejects with an `AuthMethodContractError` that lists every
check the method failed:

- the static checks the registry runs, and a config schema that renders as JSON Schema;
- `start()` answers a valid redirect, transaction and binding, and two starts answer different
  transactions;
- two starts answer different bindings, and each sends its binding to the provider, in the
  redirect or in a body the method posted (as a pushed authorization request does);
- the provider's callback carries the binding back in the route's `bindingParameter`: the kit
  compares it as the host does, and calls the handler only when it matches. The callback ends in
  an identity whose `rawClaims.iss` names its issuer and whose attributes carry the method's
  `type`, and a second sign-in of the same person resolves the same `externalSub`;
- PKCE with S256: an authorization request that asks for a code (`response_type=code`) carries
  `code_challenge_method=S256` and a `code_challenge`, and every token request the callback makes
  (`grant_type=authorization_code`) carries the `code_verifier` whose S256 is that challenge;
- `verify()` rejects inputs no callback produced: a well-formed identity, a copy of a real result,
  and a result it has already verified;
- a declined callback ends as `declined`, when the scenario gives one;
- the method never calls the global `fetch` while the kit runs it (the kit cannot see
  `node:https`, `undici` or a `fetch` kept from before; the lint rule `qauth/no-direct-network`
  refuses those in QAuth's own code);
- no log line carries the value of a `writeOnly` config member: any string inside such a member,
  found through `properties`, `items`, `additionalProperties`, `anyOf`, `oneOf`, `allOf` and local
  `$ref`s, as it is, in base64 or base64url, percent-encoded, or as HTTP Basic credentials with
  another string of the config, in a field, a message, or an error's message, stack, cause or own
  fields. Every secret is looked for, however short, so give the scenario's secrets a realistic
  length: a short one can match text that is no leak. It is a check for common leaks, not a proof
  that none exists.

`libs/sdk/plugin-sdk/testing/sample-auth-method.fixture.ts` is a sample method that passes;
`libs/sdk/plugin-sdk/src/testing/contract-kit.test.ts` shows the broken methods the kit refuses,
each with the problems it reports.

## Write a plugin in your own repository

A plugin needs nothing of QAuth's own repository. The contract, its errors and static checks, and
the test kit are the npm package `@qauth-labs/plugin-sdk`, which depends on no other QAuth package.
It is experimental, like the contract it carries. Its README and its `api-report.md` list what
each entry point exports. `libs/sdk/plugin-sdk/examples/minimal-plugin` is a complete plugin for an
OAuth 2.0 provider with PKCE: QAuth's release dry run installs the packed SDK into an empty
project on every pull request, and builds and tests the example there.

For example, QAuth's GitHub plugin is the example of a plugin in its own repository:
`@qauth-labs/plugin-github`, from the example repository [qauth-labs/plugin-github](https://github.com/qauth-labs/plugin-github).
It depends only on the published SDK, runs the kit in its CI, and runs an end-to-end suite against
the released server image with the plugin added on top, as an operator adds it. QAuth makes and
releases it, yet it is not on the server's first-party list: like any other package, it loads only
while `PLUGIN_API_ENABLED` is on.

QAuth's preset plugins are built the same way, each in its own repository:
[qauth-labs/plugin-google](https://github.com/qauth-labs/plugin-google) and
[qauth-labs/plugin-microsoft](https://github.com/qauth-labs/plugin-microsoft)
([Write a preset plugin](/extend/preset-plugins/)). [QAuth's provider plugins](/operate/images/#qauths-provider-plugins)
lists all three, with their packages and the redirect URI each one registers.

**Install the SDK.** The package carries QAuth's own version: install the version of the QAuth
release the plugin is for. A release is on npm's `latest` dist-tag, the first being `0.2.0`,
and a release candidate is on `next`. Zod is a peer dependency, so install it beside the SDK:

```sh
npm install @qauth-labs/plugin-sdk@0.2.3 zod
```

**Export the method.** The package's entry point exports its method as `authMethod`
([above](#packaging-a-plugin)):

```ts



const configSchema = z.object({
  clientId: z.string().min(1),
  clientSecret: z.string().min(1).meta({ writeOnly: true }),
});

export const authMethod: AuthMethod<z.output<typeof configSchema>, CorpSsoTransaction> = {
  contract: AUTH_METHOD_CONTRACT,
  type: 'corp_sso',
  id: 'corp-sso',
  display: { name: 'Corp SSO' },
  configSchema,
  steps: [UPSTREAM_STEP_URN],
  // routes, start, verify, extractAttributes
};
```

`AUTH_METHOD_CONTRACT` is the contract version of the SDK release you install. A server refuses a
plugin written against another version, so pin the SDK to the QAuth release you build for.

**Run the kit.** `checkAuthMethod` comes from `@qauth-labs/plugin-sdk/testing` and works in any
test runner ([above](#checking-a-method-the-contract-test-kit)). Under Node's own:

```ts






test('meets the AuthMethod contract', async () => {
  await checkAuthMethod(authMethod, scenario);
});
```

**Publish.** Publish the compiled JavaScript and its declarations: Node does not strip TypeScript
types under `node_modules`. List `@qauth-labs/plugin-sdk` under `dependencies`, because the
contract's constants are part of the method at run time. List `zod` under `peerDependencies`, so
the method's schema is built with the server's Zod ([secret members](#packaging-a-plugin)):

```json
{
  "name": "@example/qauth-plugin-corp-sso",
  "type": "module",
  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
  "files": ["dist"],
  "dependencies": { "@qauth-labs/plugin-sdk": "0.2.3" },
  "peerDependencies": { "zod": "^4.6.7" }
}
```

**What the operator does** ([above](#installing-and-enabling-a-plugin)):

1. installs the package with the deployment, as any other dependency of the auth server: on top
   of the published image, as [Published images](/operate/images/#add-a-plugin-to-the-image) shows;
2. lists it by package name in `AUTH_METHOD_PLUGINS`;
3. turns on `PLUGIN_API_ENABLED=true`. A plugin outside QAuth's first-party list loads only while
   the switch is on. With the switch off, the boot logs a warning that names the package and says
   why it was not loaded;
4. enables and configures it per realm through the admin API's plugin operations.

```sh
AUTH_METHOD_PLUGINS=@example/qauth-plugin-corp-sso
PLUGIN_API_ENABLED=true
```

A plugin is trusted code that runs in the server's process, beside its keys in a single
deployment. Install only a package you trust as you trust the server.

---

# Write a preset plugin

URL: https://docs.qauth.dev/extend/preset-plugins/

> **Experimental.** A preset is a plugin on the AuthMethod contract, QAuth's plugin API, the
> experimental item [`plugin-api`](/reference/experimental-features/#plugin-api). It may change in
> a minor release without a deprecation window
> ([ADR-018](/reference/records/adr/018-1-0-scope-and-stability/) §4).

A **preset** is a plugin for one named OpenID Connect provider. It holds the provider's facts (its
issuer, its origins, how QAuth authenticates to it) and its claim rules, and nothing of the
protocol. The server builds its sign-in method on its own
[generic OpenID Connect client](/extend/auth-method-contract/#the-generic-openid-connect-client):
discovery, PKCE with S256, `state` and `nonce`, the ID token and key set checks, the token request
and the signer call are the server's. A fix to that code reaches every preset with a server
release, and no plugin carries its own copy.

Every provider plugin lives in its own repository, depends only on the published plugin SDK,
`@qauth-labs/plugin-sdk`, and has its own version line
([ADR-018](/reference/records/adr/018-1-0-scope-and-stability/) §3). The server's code names no
provider.

## A minimal preset

The package's entry point exports the preset as `upstreamOidcPreset`, made with
`defineUpstreamOidcPreset`:

```ts



export const upstreamOidcPreset = defineUpstreamOidcPreset({
  id: 'example-idp',
  type: 'example_idp',
  display: { name: 'Example IdP' },
  origins: ['https://idp.example.com'],
  configSchema: z.strictObject({
    clientId: z.string().min(1).max(255),
    clientSecret: z.string().min(1).max(1024).meta({ writeOnly: true }),
  }),
  upstreamConfig: (config) => ({
    issuer: 'https://idp.example.com',
    clientId: config.clientId,
    clientAuthentication: { method: 'client_secret_basic', clientSecret: config.clientSecret },
  }),
});
```

`defineUpstreamOidcPreset` runs the checks the server's loader runs, throws an
`AuthMethodContractError` that lists every problem, and returns the preset frozen, with the
contract version of the SDK release (`AUTH_METHOD_CONTRACT`). A server refuses a preset written
against another version, so pin the SDK to the QAuth release you build for.

## The preset's members

The SDK's type is `UpstreamOidcPresetOptions<TConfig>`; `UpstreamOidcPreset` is the same with its
`contract`.

| Member            | What it is                                                                                                                                                                                                             |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | Its AuthMethod id, the admin API's name for it. Never `oidc`, which the generic client holds.                                                                                                                          |
| `type`            | Its AuthMethod type: the attributes' source, and the route segment of `/upstream/<type>/callback`, the `redirect_uri` to register at the provider. Never one that starts with `oidc_`, the generic client's namespace. |
| `display`         | Its name, and optionally its icon, on the sign-in pages.                                                                                                                                                               |
| `origins`         | The `https` origins the provider answers on, one to eight. The issuer and every endpoint, set by hand or discovered, must be on one of them, so the client secret reaches no other host.                               |
| `configSchema`    | A Zod schema of what an admin sets for a realm. Its client secret is a member marked `.meta({ writeOnly: true })`, which the server stores encrypted and never shows.                                                  |
| `upstreamConfig`  | A function of the parsed config that makes the client's config, `UpstreamOidcProviderConfig`, at every use.                                                                                                            |
| `responseMembers` | Optional. Members of the authorization response the callback reads, beside the protocol's own.                                                                                                                         |
| `identityClaims`  | Optional. Claims the identity gets besides the provider's, from those members and the config.                                                                                                                          |
| `attributes`      | Optional. The attributes the claims map to; `UPSTREAM_STANDARD_ATTRIBUTES` unless set.                                                                                                                                 |

`UpstreamOidcProviderConfig` is the generic client's config: `issuer`, `clientId`,
`clientAuthentication`, and optionally `scopes`, `endpoints` set by hand, `responseMode`
(`query` or `form_post`), `idTokenSigningAlgorithms`, `fetchUserinfo` and `tenantIssuer`. The
server parses it with its own schema at every use; a config whose URLs are off the preset's
origins is refused at the admin's configure, naming no value.

## What a preset may set beyond a realm's provider

A realm's admin configures a generic provider with an issuer and a client. A preset may also set
these, which no admin can:

- **A client secret the signer signs** (`clientAuthentication: { method: 'signed_client_secret' }`):
  for a provider that takes no static secret but a JWT in the `client_secret` form member. The
  signer role signs it for each token request with the realm's `upstream_client_assertion` key for
  the preset's type: `iss` is the issuer the provider's client record names (`assertionIssuer`),
  `sub` the client id, and it lives sixty seconds. No secret is stored and the plugin holds no key.
- **A multi-tenant issuer** (`tenantIssuer: { template, tenantClaim }`): for a provider whose shared
  endpoints serve many tenants. The template holds `{tenantid}` once, in its path
  (`https://idp.example.com/{tenantid}/v2.0`), and a token is accepted only when its `iss` is the
  template with its own `tenantClaim` value in place. That check binds a token to its own tenant;
  it does not restrict sign-in to one tenant, so an issuer template takes every tenant the shared
  endpoint serves. A preset that should take one tenant sets that tenant's issuer, without
  `tenantIssuer`, and a token of any other tenant is refused.
- **Response members** (`responseMembers`): at most four members the provider sends beside the
  protocol's parameters, each with a map. A provider that answers by `form_post` posts the response
  cross-site; the client bounces it to the `GET` callback, and each member rides on in the URL as
  its map makes it, at most 1024 characters, or is dropped. The callback maps the carried value
  again, so a map must give its own output back unchanged. The request log censors each loaded
  preset's members. A member is the browser's to choose, never signed by the provider.
- **Identity claims** (`identityClaims({ claims, response, config })`): claims set over the
  provider's, such as a name from a response member. A preset never sets `sub` or a claim only the
  ID token carries (`UPSTREAM_ID_TOKEN_ONLY_CLAIMS`), and it may remove a claim the provider vouches
  for (`email`, `phone_number` and their `*_verified` flags, `UPSTREAM_VERIFIED_CLAIM_PAIRS`) but
  never set one: a value it makes up is never taken as verified. No other claim it sets makes an
  attribute verified either, since the server's client checked only the provider's claims.
- **Attribute rules** (`attributes`): which claims become the account's attributes, under which
  key, and when one is verified (`verified: (claims) => upstreamClaimIsTrue(claims, 'email_verified')`).
  Without `verified`, an attribute is never verified. A rule's `verified` sees only the provider's
  claims, never one the preset set, and an attribute read from a claim the preset set is never
  verified.

## Check it with the preset kit

`checkUpstreamOidcPreset(preset, scenario)` of `@qauth-labs/plugin-sdk/testing` checks what it can
without the server, in any test runner, and throws an `AuthMethodContractError` that names each
problem:

- the static checks `defineUpstreamOidcPreset` runs;
- every scenario config passes the schema, and `upstreamConfig` makes a provider config for it whose
  URLs are `https` and on the preset's origins, with a tenant template whose `{tenantid}` is in its
  path;
- the client secret is the value of a `writeOnly` member, and no such member's value is anywhere
  else in the provider config;
- each response member's map keeps its output within 1024 characters and gives it back unchanged;
- `identityClaims` sets neither `sub`, a claim only the ID token carries, nor a claim the provider
  vouches for.

```ts




it('is a preset the server can build', () => {
  checkUpstreamOidcPreset(upstreamOidcPreset, {
    configs: [{ clientId: 'kit-client', clientSecret: 'kit-secret-value-0123' }],
  });
});
```

The full sign-in is the plugin's own end-to-end test against the released server image, with the
plugin added on top, as an operator adds it.

## Package, load and enable it

Publish it as any plugin
([Write a plugin in your own repository](/extend/auth-method-contract/#write-a-plugin-in-your-own-repository)):
the compiled JavaScript, `@qauth-labs/plugin-sdk` under `dependencies` and `zod` under
`peerDependencies`. A package exports an `upstreamOidcPreset` or an `authMethod`, never both.

A deployment loads it only when `AUTH_METHOD_PLUGINS` names it and `PLUGIN_API_ENABLED` is on; no
provider plugin is on the server's first-party list. The boot logs each plugin it loads with how
its method was built (`kind: "upstream-oidc-preset"`), and says why it skipped one. Each realm then
has it off until an admin configures and enables it with the
[plugin operations](/extend/auth-method-contract/#installing-and-enabling-a-plugin).

## How its attributes rank

Claim resolution asserts the highest-ranked verified attribute: `wallet`, then the `oidc_*`
providers, then `self_reported`. A method the loader built from a preset ranks with `oidc_*`,
because the server's own client checked the provider's ID token. The sign-in records that on each
attribute it writes for the method (`provenance: { "builtFrom": "upstream-oidc-preset" }`), so a
process that loads no plugin, such as one of the `api` role that serves the token endpoint, ranks
it the same, and a type another package serves later does not re-rank what this one wrote. A
plugin that exports its own `authMethod` keeps an unknown rank, below `self_reported`, whatever its
type, and no plugin's type starts with `oidc_`.

## Examples

QAuth's own presets are written this way, each in its own repository: `qauth-labs/plugin-google`
(#1074), `qauth-labs/plugin-microsoft` (#1075), a multi-tenant provider with an issuer template,
and `qauth-labs/plugin-apple` (#1076), with a signed client secret and a `form_post` response
member. Sign in with Apple also needs the signer to hold the key Apple issues and to read the
client's Team ID and Services ID (#1073).

---

# Adding an admin operation

URL: https://docs.qauth.dev/extend/adding-an-admin-operation/

Every operation of the admin API goes through the same pipeline: the DPoP-bound admin token, the
caller's grants on the realm, the operation's classification, the approval gate for a security
operation, the handler in one transaction, and the audit row
([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/), Decision 7). A
new operation does not add a stage. It adds five things, in this order:

1. [Register the permission](#1-register-the-permission) it needs.
2. [Define the operation](#2-define-the-operation): its id, class, effects and permissions, and
   its route.
3. [Classify](#3-classify) each request, when what it needs depends on the request.
4. [Render](#4-render) it for the approver, when it is a security operation.
5. [Audit](#5-audit) the change its handler makes.

The realm operations are the reference, and every later admin operation follows them:

| Operation                 | Route                                                   | Class    | Permissions                                                        |
| ------------------------- | ------------------------------------------------------- | -------- | ------------------------------------------------------------------ |
| `realms.get`              | `GET /admin/v1-rc.0/realms/{realmId}`                   | read     | `realms.read`                                                      |
| `realms.policies.update`  | `PATCH /admin/v1-rc.0/realms/{realmId}/policies`        | security | `realms.policies.write`, `realms.policies.security`, `realms.read` |
| `realms.policies.preview` | `POST /admin/v1-rc.0/realms/{realmId}/policies/preview` | read     | `realms.read`                                                      |

They are listed with their effects on [Security operations](/reference/security-operations/#operations),
which is generated from the registry. Their code is in `apps/auth-server/src/app/admin/realms/`:
`operations.ts` holds the definitions, `routes.ts` the routes, `preview.ts` the preview's
classification, and `realms.test.ts`, `preview.test.ts`,
`apps/auth-server/src/app/admin-realms.integration.test.ts` and
`apps/auth-server/src/app/admin-realm-policy-preview.integration.test.ts` their tests.

A preview answers what a save would be without making it: it takes the save's body, classifies it
with the save's own definition (`classifyRequest`), and answers the shape of
`apps/auth-server/src/app/admin/change-preview.ts` (`AdminChangePreview` in the OpenAPI document),
which masks every secret field to `set` or `not set`. It is a read: it needs the save's read
permission only, and writes nothing but its audit row.

Operation ids and permission ids are part of the published contract: a client names them, an
approval stores them, and an audit row keeps them. Choose them as you would a route.

## 1. Register the permission

A permission is `<resource>.<action>` with one class: `read`, `write` or `security`. The catalog is
`apps/auth-server/src/app/helpers/admin-permissions.ts`; the
[permissions page](/reference/admin-permissions/#permissions) is generated from it. The built-in
roles follow the catalog by class (`apps/auth-server/src/app/helpers/admin-roles.ts`): `viewer`
gets every read permission, `editor` every read and write permission, `security-admin` all of
them. The token's scopes are checked by class too: a `write` permission needs
`qauth:admin:write`, a `security` one `qauth:admin:security`.

Reuse a permission when the new operation acts on the same resource the same way. The realm
operations needed none of their own: `realms.read`, `realms.policies.write` and
`realms.policies.security` were in the catalog before them. An operation whose change can be
either a write or a security change, field by field, declares both, and each request needs only
the ones its change needs ([Classify](#3-classify)). An operation that answers the resource also
needs its read permission: the scopes are independent, so `realms.policies.update`, which answers
the realm, needs `realms.read` on every request. Filing or withdrawing an approval needs the
security permissions the operation declares; the rest is checked when the call runs with it.

## 2. Define the operation

An area keeps its definitions in `admin/<area>/operations.ts` and adds them to `ADMIN_OPERATIONS`
in `apps/auth-server/src/app/helpers/admin-operations.ts`. A definition says:

- `id`, `class`, `effects` and `permissions`: its declaration, what it needs at most. A security
  operation names the [effects](/reference/security-operations/#effects) that make it one.
- `description`: one sentence, shown on the generated pages and in OpenAPI.
- `loadState` and `stateVersion`, for an operation on a resource with a version: the resource as
  the request finds it, and the version a client names in `If-Match`. The pipeline answers 428
  without `If-Match` and 412 when it names another version, before the handler runs. An operation
  with no `classify` may read state too, to show it to the approver and bind its approval to that
  version: `users.verify` shows the account and its credentials, and every request needs its
  declaration whatever the state.
- `secretMembers`: the JSON Pointers of the body members that carry a secret. The body schema
  holds each to a sealed value, and the handler opens it with `openRequestSealedValue`
  (`apps/auth-server/src/app/admin/secrets/sealed-values.ts`), for its own operation only.
- `classify` and `render`, when they apply (steps 3 and 4).

An id the registry reserves (`apps/auth-server/src/app/helpers/admin-operations-reserved.ts`) must
be registered with at least its reserved class and effects; a request-dependent one also passes
its security cases at boot.

A definition module imports values only from
`apps/auth-server/src/app/helpers/admin-classification.ts`, and types from the registry: the
registry imports the module, so importing the registry or the pipeline back would read them before
they exist. That is also why `loadState` reads the realm from `request.adminPipeline.authority`.

The route names its operation and carries the registry's OpenAPI extensions:

```ts
typed.patch(
  `${REALM_PATH}/policies`,
  {
    config: { operation: operations.updatePolicies.id },
    preHandler: requireMergePatch,
    schema: {
      ...operationSchemaExtensions(operations.updatePolicies), // operationId, x-qauth-class, …
      'x-qauth-stability': 'experimental',
      'x-qauth-errors': [400, 401, 403, 404, 412, 415, 422, 428, 503],
      security: [{ [ADMIN_SECURITY_SCHEME]: [] }],
      // params, headers, body, response …
    },
  },
  handler
);
```

The area's route module goes into `ADMIN_ROUTE_MODULES` in
`apps/auth-server/src/app/admin/listener.ts`. A route that names no operation, or one the registry
does not hold, stops the boot. The API conventions check
(`apps/auth-server/src/app/api-conventions/openapi-conventions.ts`) holds every admin operation of
the OpenAPI document to the registry; each area's unit test runs it over its routes.

## 3. Classify

An operation without `classify` needs its declaration on every request. One whose need depends on
the request, such as a merge patch that may touch a write field or a security field, has a
`classify(request, state)`: a pure, synchronous function of frozen copies of the request and of
`loadState`'s result. Its answer must stay within the declaration. When it throws, or answers
anything else, the request fails closed: it needs the whole declaration.

A merge-patch operation builds `classify` from the field table of `classifyByField`, with
`mergePatchLeafPaths` as the fields the body changes. A member the table does not hold fails the
request closed. `realms.policies.update` builds its table from the realm policy annotations
([Realm policies](/reference/realm-policies/)), and judges each change on the merged document,
never on the patch alone: `null` gives a field its default, which may be looser than the stored
value, so a `null` that loosens is a security change. A secret field is a security change whatever
the patch does with it. A patch that shortens the access-token lifetime is a write; one that
lowers the password score is a security change; a patch of both needs both permissions, both
scopes and one approval. Every patch needs `realms.read` besides.

`loadState` runs once the caller is known to hold at least one of the operation's permissions:
a caller who holds none is refused with 403 before anything is read, so it learns nothing of the
resource. `loadState` may refuse what it cannot judge: `realms.policies.update` answers 422,
naming each field, when the merged document fails the policy schema, such as a
`bruteForce.lockoutSeconds` above a day, so an invalid patch is never filed for an approval.

## 4. Render

A security operation runs only with an approval, and the approver decides from what `render`
shows: a title and a list of fields, each a `label` and a `value`, with the `before` it replaces
for a change. It gets the filed request and, for an operation with `loadState`, the state the
approval was filed against, which the approval is bound to: a call after the state moved does not
run on it. Never show a secret: `realms.policies.update` shows a secret field only as whether it
was set and whether the patch sets or clears it. The display caps the number and the length of
the fields (`apps/auth-server/src/app/admin/approvals/display.ts`), and shows the requester's
reason beside them as quoted text, never as part of the rendering.

## 5. Audit

The handler does its work through `adminTransaction(request)`, the transaction its audit row
commits in, and records what it changed with `recordAdminChange(request, change)`: the resource's
state `before` and `after`, and an annotation `secret` on each member that holds one. The audit
log stores the diff with each secret masked (`***`), and never its value. A call records one
change. A call the pipeline refuses, or a handler that fails, gets its `denied` or `failed` row
with no diff, and its transaction is rolled back.

Pass that transaction to every repository call the handler makes. A call that does not pass it
would take a second connection from the pool the public listener serves from, and commit on its
own, outside the audited transaction. Inside a handler, `request.server.repositories` refuses
such a call (`apps/auth-server/src/app/admin/handler-scope.ts`): it throws, so the call fails with
500, its transaction rolls back, and its row is `failed`. A savepoint of the transaction is
another transaction, and is refused too.

`realms.policies.update` writes through the policy store in that transaction, conditional on the
version it was classified against, with a guard that refuses a stored change that would need more
than the request was authorized for. Its audit row holds the changed fields before and after and
the policy version.

## Tests

Each operation gets a unit test of its definition, classification, renderer, body schema and
representation, with the API conventions check over its routes, and an integration test against
real Postgres and Redis that runs it through every stage with the test approval factor. The realm
operations' suites are the model.

---

# Portal & Dashboard

URL: https://docs.qauth.dev/portal/

This lane is for people using the QAuth developer portal — the TanStack Start application at
`apps/developer-portal` where a developer registers, verifies their email, logs in, and manages
their own OAuth clients.

- [Portal guide](/portal/guide/) — the session model, the required environment variables, and
  every flow the portal implements, each traced to its route and server action.
- [Known gaps](/portal/known-gaps/) — an honest account of the places the portal is thinner
  than a first look suggests: a dashboard card that misreports a shipped feature as unbuilt, and
  a page that exists but isn't linked from anywhere.

---

# Portal guide

URL: https://docs.qauth.dev/portal/guide/

`apps/developer-portal` (Nx project `developer-portal`) is a TanStack Start + React 19
application. It is where a developer registers an account, verifies their email, logs in, and
manages the OAuth clients they use against the auth-server. This page describes what is in the
tree today; there is no prior prose on this app to lean on, so every claim below is traced to a
file.

## The session model

The portal owns its own session — it does not reuse the auth-server's hosted-UI session cookie
(see [the consents page](#the-consents-page) below, where that distinction used to break a page). The session lives in an `HttpOnly`, signed, `__Host-` prefixed cookie,
and the property worth understanding before extending this app is that **tokens never reach the
browser**: every call to the auth-server is made from a TanStack Start server function, running
on the server, and the browser only ever holds the signed cookie.

- **Cookie name**: `__Host-qauth_portal_session`
  (`apps/developer-portal/src/server/session-cookie.ts:5`).
- **Payload**: `{ accessToken, refreshToken, expiresAt }`
  (`apps/developer-portal/src/server/session-cookie.ts:7`, the `PortalSessionPayload` interface).
- **Signing**: HMAC-SHA256 over the base64url-encoded payload, compared with `timingSafeEqual`
  on verification — `createHmac('sha256', secret).update(value).digest('base64url')`
  (`apps/developer-portal/src/server/session-cookie.ts:25`) and the constant-time comparison at
  `apps/developer-portal/src/server/session-cookie.ts:45`. The signature is not encryption: the
  payload is base64url, not encrypted, so it is unreadable-by-accident but not confidential
  against anyone who can read the cookie value directly (nobody but the browser and the portal's
  own server should be able to).
- **Cookie attributes**: `Path=/`, `HttpOnly`, `Secure`, `SameSite=Lax`, and
  `Max-Age=<PORTAL_SESSION_TTL>`, set in `setSessionCookieHeader`
  (`apps/developer-portal/src/server/session-cookie.ts:61`, the `Max-Age` line itself is
  `apps/developer-portal/src/server/session-cookie.ts:69`).
  `Secure` is always emitted regardless of environment — the code comment at
  `apps/developer-portal/src/server/session-cookie.ts:56` notes that the `__Host-` prefix
  requires it per RFC 6265bis §4.1.3.2, and browsers reject the `Set-Cookie` header outright
  without it, even on `localhost`. Developing over plain HTTP therefore requires looping back
  through `localhost` (which browsers treat as a secure context) or a TLS-terminating proxy.
- **TTL**: `PORTAL_SESSION_TTL`, an environment variable defaulting to `900` seconds
  (`apps/developer-portal/src/server/config.ts:3`) — this is the cookie's `Max-Age`, i.e. how
  long the browser keeps the cookie at all.

That TTL is a separate number from the `expiresAt` field inside the payload. `expiresAt` is
computed at login as `Date.now() + result.data.expires_in * 1000`
(`apps/developer-portal/src/server/actions/login.server.ts:16`) — the auth-server's own access
token lifetime, not `PORTAL_SESSION_TTL`. Every server function that needs the current user reads
the cookie and separately checks `Date.now() >= session.expiresAt`
(e.g. `apps/developer-portal/src/server/actions/current-user.server.ts:14`) before trusting the
access token inside it, so a cookie that outlives the token it carries is still treated as
expired.

The payload also carries a `refreshToken`, but nothing in the portal currently reads it back out
to refresh an expired access token. The comment directly above that expiry check says so:

> Refresh-token rotation lives in Phase 2.x; for now an expired session bounces the user to
> `/login`.
> — `apps/developer-portal/src/server/actions/current-user.server.ts:12`

So today, once `expiresAt` passes, the developer is signed out and has to log in again — the
stored `refreshToken` is inert.

**Login** (`apps/developer-portal/src/server/actions/login.server.ts`) calls
`authServerClient.login` (`apps/developer-portal/src/server/actions/login.server.ts:13`), a JSON
`fetch` to the auth-server's `/auth/login`, and on success sets the session cookie via
`setSessionCookieHeader` (`apps/developer-portal/src/server/actions/login.server.ts:20`).
**Logout** (`apps/developer-portal/src/server/actions/logout.server.ts`) reads the current
session, calls the auth-server's `/auth/logout` with the access token
(`apps/developer-portal/src/server/actions/logout.server.ts:11`), and always clears the cookie
(`apps/developer-portal/src/server/actions/logout.server.ts:14`) — even if the upstream call
fails, the developer's browser stops holding a session.

Every route under `_authed` (`apps/developer-portal/src/routes/_authed.tsx`) gates on this same
cookie: `beforeLoad` calls `currentUserFn` and redirects to `/login` when it returns `null`
(`apps/developer-portal/src/routes/_authed.tsx:9`).

## Environment variables

Four environment variables are required or configurable server-side
(`apps/developer-portal/src/server/config.ts`; `PORTAL_TRUST_PROXY` in
`apps/developer-portal/src/server/trust-proxy.ts`):

| Variable                | Required | Default | What it does                                                                                                                                                                                                                               |
| ----------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AUTH_SERVER_URL`       | Yes      | —       | Base URL of the auth-server the portal's server functions call. Read at `apps/developer-portal/src/server/config.ts:1`.                                                                                                                    |
| `PORTAL_SESSION_SECRET` | Yes      | —       | HMAC-SHA256 key used to sign and verify the session cookie. Read at `apps/developer-portal/src/server/config.ts:2`.                                                                                                                        |
| `PORTAL_SESSION_TTL`    | No       | `900`   | Session cookie `Max-Age` in seconds. Parsed at `apps/developer-portal/src/server/config.ts:3`.                                                                                                                                             |
| `PORTAL_TRUST_PROXY`    | No       | —       | Proxy addresses (single IPs, comma-separated) allowed to report the client address. Parsed at `apps/developer-portal/src/server/trust-proxy.ts`; an invalid value stops the server at startup (`apps/developer-portal/src/node-entry.ts`). |

`AUTH_SERVER_URL` and `PORTAL_SESSION_SECRET` are enforced at startup: `config.ts` throws if
either is missing, but only when running server-side (`import.meta.env.SSR`,
`apps/developer-portal/src/server/config.ts:9`) — the comment there explains why: this
module can be pulled into a client bundle chunk via the server actions, where `process.env` is
always empty, so the check is scoped to avoid a false failure in the browser.

## Flows

### Register → verify → login → logout

- **Register** (`/register`, `apps/developer-portal/src/routes/register.tsx`) submits email and
  password through `registerFn` → `registerHandler`
  (`apps/developer-portal/src/server/actions/register.ts:5`), which calls the auth-server's
  `/auth/register`. The auth-server answers every address with the same `202`, whether it was free
  or already had an account, so the page shows the same "check your inbox" screen for both, with
  the address as typed and a resend option, and never says "address already registered". The
  mail says what comes next: a verification link, or a notice that the address already has an
  account. The page does not log the developer in.
- **Verify** (`/verify?token=...`, `apps/developer-portal/src/routes/verify.tsx`) validates the
  token shape client-side (64 hex characters) and opens on a confirmation step that asks for the
  account's password. Submitting calls `verifyFn`
  (`apps/developer-portal/src/server/actions/verify.ts`), which sends the token and the password
  to the auth-server's `POST /auth/verify`. The token proves the mailbox and the password proves
  the registrant, so the owner of an address cannot verify an account someone else registered
  with it by following the link. The page does not verify on load, so a link scanner or a
  prefetch cannot either. A wrong password keeps the form open, and the token is not consumed.
- **Login** (`/login`, `apps/developer-portal/src/routes/login.tsx`) — see the session model
  above. On failure the page always shows the same generic "Invalid email or password" message
  regardless of the underlying error code, an explicit anti-enumeration choice
  (`apps/developer-portal/src/routes/login.tsx:43`). The message also asks a developer who has
  just signed up to confirm the address first: while the realm requires verified accounts
  (`accounts.requireVerifiedAccount`, the default) the auth-server refuses an unverified account with the same `401` as a wrong password. The page
  also has a "Forgot password? Coming soon." line
  (`apps/developer-portal/src/routes/login.tsx:79`) — there is no
  password-reset endpoint anywhere in `apps/auth-server`, so that line is accurate as written,
  not a stale claim.
- **Logout** is a button in the authed layout's header
  (`apps/developer-portal/src/routes/_authed.tsx:35`) that calls `logoutFn` and navigates
  to `/login`.

### OAuth client management

All of `/clients` sits under the `_authed` layout.

- **List** (`/clients`, `apps/developer-portal/src/routes/_authed/clients.index.tsx`) calls
  `listClientsFn` on mount and renders one card per client.
- **Create** (`/clients/new`, `apps/developer-portal/src/routes/_authed/clients.new.tsx`) submits
  a form to `createClientFn`; on success it shows the one-time secret reveal (below) before
  routing to the new client's detail page.
- **Detail** (`/clients/$clientId`,
  `apps/developer-portal/src/routes/_authed/clients.$clientId.tsx`) loads one client via
  `getClientFn` and is also where edit, delete, secret regeneration, and API-key management all
  live.
- **Edit** is the same detail page in an editing state, submitting to `updateClientFn`
  (`apps/developer-portal/src/routes/_authed/clients.$clientId.tsx:72`, the `handleSave`
  function).
- **Delete** is a confirmation modal calling `deleteClientFn`
  (`apps/developer-portal/src/routes/_authed/clients.$clientId.tsx:102`, the `handleDelete`
  function); the modal's own copy says the deletion "cannot be undone."

Every client-management server function (`apps/developer-portal/src/server/actions/clients.server.ts`)
follows the same shape: read the access token out of the signed session cookie
(`apps/developer-portal/src/server/actions/clients.server.ts:20`), return an `UNAUTHENTICATED`
result if it's missing or expired, and
otherwise proxy the call to the auth-server with `Authorization: Bearer <token>`. The access
token is attached server-side on every request; the browser never sees it.

### The one-time secret reveal and regeneration

A confidential client's secret is shown exactly once — at creation
(`apps/developer-portal/src/routes/_authed/clients.new.tsx:83`, the `SecretReveal` render) or
after a regeneration (`apps/developer-portal/src/routes/_authed/clients.$clientId.tsx:327`) —
through the shared
`SecretReveal` component (`apps/developer-portal/src/components/secret-reveal.tsx`). Its own
doc comment states the mechanism plainly:

> Renders inside a non-dismissible modal so the developer cannot lose the secret by clicking the
> backdrop. The secret is passed in as a prop and never written to any store — when the parent
> removes this component the value is gone.
> — `apps/developer-portal/src/components/secret-reveal.tsx:21`

There is no "view secret again" affordance anywhere in the client-detail page: once the reveal
modal closes, the detail view only ever shows "Hidden. Secrets are shown only once, at creation
or regeneration." (`apps/developer-portal/src/routes/_authed/clients.$clientId.tsx:205`). A public
client (`tokenEndpointAuthMethod === 'none'`) has no secret to show at all
(`apps/developer-portal/src/routes/_authed/clients.$clientId.tsx:204`).
**Regenerating** a secret (behind a confirmation modal warning that existing integrations break
immediately) invalidates the old one and re-triggers the same one-time reveal.

The absence of a "view again" button is a UI convenience, not the guarantee. "Never retrievable"
is enforced two levels below it, and neither is client-side:

- **At the type level**, the portal's own client for the developer API's clients distinguishes the
  two shapes.
  `OAuthClient` (`apps/developer-portal/src/server/auth-server-client.ts:82`) — what every list
  and get call returns — has no `clientSecret` field at all; the comment above it says why:
  "deliberately absent here — it only exists on {@link ClientWithSecret}"
  (`apps/developer-portal/src/server/auth-server-client.ts:79`). `ClientWithSecret`
  (`apps/developer-portal/src/server/auth-server-client.ts:164`) is a distinct type, returned
  **only** by the create and regenerate calls
  (`apps/developer-portal/src/server/auth-server-client.ts:159`). There is no portal API call
  that can ask for a client and get a secret back outside those two responses — the type the
  other calls return cannot carry one.
- **On the auth-server**, where the actual guarantee is enforced: a client create (`POST` on the
  developer API's clients, or the deprecated `/api/clients`) generates
  the secret, hashes it with Argon2id, and keeps the plaintext only in a local variable
  (`generateClientSecret`, `apps/auth-server/src/app/helpers/developer-clients.ts:279`). Only
  `clientSecretHash` is passed to the repository's `create` call
  (`apps/auth-server/src/app/helpers/developer-clients.ts:425`); the plaintext is spread into the
  HTTP response once (`apps/auth-server/src/app/routes/developer/clients.ts:243`, and
  `apps/auth-server/src/app/routes/clients/index.ts:216` on the deprecated path) and then goes out
  of scope. Regeneration is the same shape: only the new `hash` is persisted
  (`apps/auth-server/src/app/helpers/developer-clients.ts:648`), and the plaintext is returned once
  (`apps/auth-server/src/app/routes/developer/clients.ts:404`). No code path — in the portal or the
  auth-server — reads a plaintext secret back out of storage, because no plaintext secret is
  ever stored.

So a portal contributor who "improves" `SecretReveal` to add a persistence layer would not
weaken this guarantee — they'd just be caching a value the auth-server never lets them fetch
again. The enforcement that matters lives in the response shapes and the database column, not in
this component.

### API keys

Static developer API keys let a client authenticate without the full OAuth flow, and — per
ADR-008 — they are environment-gated: only a client whose effective environment resolves to
`development` may mint one (see
[Environment-Aware Authorization](/operate/environment-authorization/#static-developer-api-keys)
for the resolver). This shipped as issues #97 (backend) and #98 (portal UI), and the code is in
the tree today: `apps/developer-portal/src/components/api-keys-section.tsx`.

The management UI is **not** a standalone page — it is a section embedded in the client-detail
page, rendered under the client's own fields
(`apps/developer-portal/src/routes/_authed/clients.$clientId.tsx:225`). Its own doc comment
describes the gate:

> Environment gating: the create form renders ONLY when `client.staticApiKeysAllowed` is true (a
> `development` client). For a `staging`/`production` client the form is replaced with guidance
> to use the OAuth `client_credentials` grant. As defense-in-depth, a `403` from the mint endpoint
> is still handled gracefully (it surfaces the same guidance), so the UI stays correct even if the
> gate flag is stale.
> — `apps/developer-portal/src/components/api-keys-section.tsx:30`

A newly created key's plaintext is shown once, in the same non-dismissible-modal pattern as the
client secret (`apps/developer-portal/src/components/api-keys-section.tsx:263`); the list
view afterwards only ever shows the masked `prefix…last4` form. Revoking a key
(`apps/developer-portal/src/components/api-keys-section.tsx:99`, the `handleRevoke` function) is
an idempotent soft-delete — a revoked key is still listed, marked "Revoked," and cannot
authenticate again.

### The consents page

`/consents` (`apps/developer-portal/src/routes/_authed/consents.tsx`) lists the OAuth clients a
developer has granted access to and lets them revoke a grant. Revoking forces a fresh consent
prompt the next time that app hits `/oauth/authorize`.

It reaches the auth-server the same way every other authenticated page does: through TanStack
Start server functions (`apps/developer-portal/src/server/actions/consents.server.ts`), which read
the developer's access token from the signed, HttpOnly `__Host-qauth_portal_session` cookie and
attach it as `Authorization: Bearer <token>`. No token or session cookie reaches the browser, and
the page sits under the `_authed` layout, so an anonymous visitor is redirected to `/login` rather
than shown a network `401`.

The auth-server endpoints behind it are the developer API's consents, `GET` and `DELETE` on
`/developer/v1-rc.0/consents` (#524; `apps/auth-server/src/app/helpers/family-consents.ts`),
behind the developer family's token guard and scoped to the token's `sub`, the same auth model as
the developer API's clients. The deprecated `/api/consents` serves the same data in its old shape. A consent belonging to another user
is reported as `404`, never `403`, so the API cannot be used to discover that someone else's
consent id exists.

#### Why there are two consent surfaces

The auth-server also serves a cookie-authenticated `/consents`
(`apps/auth-server/src/app/routes/consents/index.ts`) for its own hosted UI. The two differ only in
how the caller authenticates; ownership and auditing are shared through
`apps/auth-server/src/app/helpers/consent-management.ts` so they cannot drift apart on the part
that matters.

The cookie surface requires a per-session CSRF token echoed back as `X-CSRF-Token`, because a
cookie is ambient authority a cross-site page can make the browser attach. The developer API
requires none: a Bearer token has to be put on the request by code that already holds it. The
cookie surface is deprecated too: the account API's `/account/v1-rc.0/consents` replaces it once
the account console ships (v0.4).

> **Historical note (fixed in #366).** This page used to be the portal's one exception to the
> "server functions are the only callers of auth-server endpoints" rule — it called `fetch()`
> straight from the browser with `credentials: 'include'`, expecting the auth-server's
> `__Host-qauth_session` cookie. Three independent blockers made that impossible for a
> portal-authenticated developer: that cookie is set only by the auth-server's own `POST /ui/login`
> (`apps/auth-server/src/app/routes/ui/login.ts:449`), which the portal's login flow never visits;
> it is `SameSite=Lax` (`apps/auth-server/src/app/helpers/session-cookie.ts:371`), so it is
> withheld from cross-site `fetch()` subresource requests whatever `credentials: 'include'` says;
> and CORS `origin` resolves to `false` in production unless an operator sets `CORS_ORIGIN`
> (`apps/auth-server/src/app/plugins/cors.ts:48`). The shipped topology is cross-origin to begin with —
> [Docker](/operate/docker/#developer-portal) runs `auth-server` and `developer-portal` as separate
> Compose services on different ports. A fourth blocker was waiting behind those: the page never
> read the CSRF token out of the list response, so its `DELETE` would have been refused even had
> the rest lined up.

## See also

- [Known gaps](/portal/known-gaps/) — the dashboard's stale API-keys card.
- [Environment-Aware Authorization](/operate/environment-authorization/) — the ADR-008 policy
  that gates static API keys.
- [Hosted UI](/integrate/hosted-ui/) — `/ui/login`, `/ui/consent`, and the `__Host-qauth_session`
  cookie the auth-server's own cookie-authenticated `/consents` surface uses.
- [Docker](/operate/docker/#developer-portal) — how the portal is deployed and where
  `AUTH_SERVER_URL` / `VITE_AUTH_SERVER_URL` point in that setup.

---

# Known gaps

URL: https://docs.qauth.dev/portal/known-gaps/

This page documents surfaces in `apps/developer-portal` where the UI is misleading or
incomplete as written today. It exists so the next round of work has an honest baseline rather
than a guess. No dates are implied for any fix below — none has been scheduled.

## The dashboard misreports a shipped feature as unbuilt

`/dashboard` (`apps/developer-portal/src/routes/_authed/dashboard.tsx`) is a 48-line component: a
welcome heading (`apps/developer-portal/src/routes/_authed/dashboard.tsx:15`) and two cards
(`apps/developer-portal/src/routes/_authed/dashboard.tsx:19`). The first card links to client
management. The second reads:

> Coming soon in Phase 2.3.
> — `apps/developer-portal/src/routes/_authed/dashboard.tsx:42`

for **API Keys**. That is not accurate. Static developer API keys shipped — backend in issue #97,
portal UI in issue #98 — and the feature is reachable today: `apps/auth-server/src/app/routes/clients/api-keys.ts`
implements the endpoints, and `apps/developer-portal/src/components/api-keys-section.tsx` is a
full create/list/revoke UI for them, embedded in the client-detail page
(`apps/developer-portal/src/routes/_authed/clients.$clientId.tsx`). See the
[portal guide](/portal/guide/#api-keys) for the working flow.

The dashboard card was never updated after #97/#98 landed. A developer who trusts the dashboard's
own words has no way to discover that API keys already work — the card actively tells them the
opposite of what the rest of the app does.

## ~~`/consents` exists but nothing links to it~~ — fixed

**Resolved in #366.** The consent screen now lives under the authenticated layout
(`apps/developer-portal/src/routes/_authed/consents.tsx`), so it redirects to `/login` without a
session, and the `_authed` header carries a nav link to it
(`apps/developer-portal/src/routes/_authed.tsx`). It also no longer calls the auth-server from the
browser — the separate authentication defect recorded here previously — and it has a test, which
it did not when this gap was written. See the
[portal guide](/portal/guide/#the-consents-page).

Both halves of this gap had the same root cause: no link and no test meant nothing exercised the
page, so its `401` for every portal-authenticated developer went unnoticed.

## Two smaller, verified leftovers

Neither of these is load-bearing, but both are easy to check and both are still scaffold from the
TanStack Start template rather than portal-specific content:

- The document `<title>` is still the framework default:
  `title: 'TanStack Start Starter'` (`apps/developer-portal/src/routes/__root.tsx:18`). Every
  browser tab for this app reads "TanStack Start Starter," not anything naming QAuth.
- The portal's root route, `/`, renders a single unlabelled placeholder:
  `return <Button variant="link">Click me</Button>;`
  (`apps/developer-portal/src/routes/index.tsx:9`). It has no `onClick` handler and does nothing.
  There is no redirect from `/` to `/login` or `/dashboard`, so this is what a browser visiting
  the portal's bare origin actually shows.

## See also

- [Portal guide](/portal/guide/) — what the portal does today, session model included.

---

# Dashboard specification

URL: https://docs.qauth.dev/portal/dashboard-spec/

Every other page in this documentation set describes what QAuth does. This one describes what the
developer dashboard **should** do. It exists so that the implementation phase is a matter of
writing code rather than making design decisions, and it is deliberately written before any of
that code exists.

Read [Portal guide](/portal/guide/) for the portal's session model and shipped flows, and
[Known gaps](/portal/known-gaps/) for the honest account of the dashboard as it stands. This page
does not repeat either; it builds on both.

## How to read this page

The single thing a reader must never have to work out is whether a paragraph describes today or
tomorrow. Two conventions carry that:

- A **Shipped** callout, or a `path:line` anchor in backticks, means the behaviour is in the tree
  at the `lastVerified` date above. Every such anchor was opened and read.
- A **Proposed** heading, or a sentence in the form "the dashboard **must**/**should**", describes
  work that does not exist. No proposed path in this page names a file that exists, and no
  proposed field is present in any shipped schema.

Where this page names a value — a page size, a cache TTL, a colour treatment, a route — that value
is a decision, not a suggestion. Changing one is fine; re-opening it because the page "left it
open" is not. The reasoning is given inline so a later change is made knowingly.

## Scope

Four surfaces, in the order an implementer should build them:

| #   | Surface                                 | Backend work required                                                         |
| --- | --------------------------------------- | ----------------------------------------------------------------------------- |
| A   | Surface what already ships              | None for API keys; **#366** for consents                                      |
| B   | Effective environment policy per client | Response widening (see [Surface B](#surface-b--effective-environment-policy)) |
| C   | Agent visibility                        | Response widening (see [Surface C](#surface-c--agent-visibility))             |
| D   | Activity feed and metrics tiles         | Two new endpoints and one index migration                                     |

### Non-goals, dated 2026-08-10

- **Wallet-federation provider configuration UI.** Wallet trust is operator-set environment
  configuration, not developer self-service: `WALLET_FEDERATION_ENABLED`
  (`libs/server/config/src/lib/schemas/federation.ts:283`), the `VerifierProfile` the deployment
  operates under, and the per-realm issuer allowlist all come from the server environment. The
  sign-in flow itself completes end to end once an operator turns them on
  (`apps/docs-site/src/lib/status.ts:147`, the `WALLET_FEDERATION_ENABLED` row), so a portal
  surface would be editing deployment configuration a developer does not own.
- **Realm administration.** No admin-panel application exists in the workspace. Realm-level
  controls (`max_environment_laxity`, `dynamic_registration_allowed_scopes`) are operator-set by
  design (`apps/auth-server/src/app/helpers/environment-policy.ts:22`), and putting them in a
  self-service developer portal would invert that.
- **An operator-tier audit view.** There is no operator role in the system. The redacted,
  client-scoped developer view specified in [Surface D](#surface-d--activity-feed-and-metrics-tiles)
  is the deliberate answer, not a placeholder for a fuller one.

## Information architecture

**Shipped.** `/dashboard` is a 48-line component under the `_authed` layout: a welcome heading and
two cards, one of which advertises API keys as unshipped
(`apps/developer-portal/src/routes/_authed/dashboard.tsx:42`). The authed layout renders a header
with the developer's email and a log-out button and no navigation at all
(`apps/developer-portal/src/routes/_authed.tsx:30`).

**Proposed.** The dashboard becomes a real landing page and gains three sibling destinations:

| Route        | Purpose                                          | Layout                                     |
| ------------ | ------------------------------------------------ | ------------------------------------------ |
| `/dashboard` | Overview counters, metric tiles, recent activity | `_authed` (unchanged)                      |
| `/clients`   | Client list                                      | `_authed` (unchanged, shipped)             |
| `/api-keys`  | API keys across every client the developer owns  | `_authed` (new)                            |
| `/activity`  | The full activity feed                           | `_authed` (new)                            |
| `/consents`  | Granted consents and revocation                  | `_authed` (**moved**; blocked on **#366**) |

The authed header gains a navigation row linking Dashboard, Clients, API keys, Activity and
Consents. It is one row of links, not a collapsible sidebar: five destinations do not justify a
navigation chrome the app does not otherwise have.

**Decision — `/consents` keeps its URL. DONE (#366).** `_authed` is a pathless layout route
(`apps/developer-portal/src/routes/_authed.tsx`), so moving the page to
`routes/_authed/consents.tsx` put it behind the session gate without changing the URL a developer
may have bookmarked. Do not rename it to `/settings/consents` in a later pass.

**Decision — the feed page is called "Activity", not "Audit".** The API resource genuinely is
`audit_logs` and the endpoint is named for it. The page is not, because "audit" promises a
complete record and this view is deliberately incomplete: it is scoped to one developer's clients,
it withholds end-user data, and it structurally cannot show rows that carry no client attribution
(see [what the feed cannot show](#what-the-feed-structurally-cannot-show)). Naming the page for the
table would be a promise the page does not keep.

### Dashboard layout order

Top to bottom: overview counters → metric tiles → the ten most recent activity rows → destination
cards. Numbers that answer "is anything wrong" come before the evidence, and the evidence before
the navigation. A developer who opens this page because something broke should not have to scroll
past a card grid to find out.

## Universal rendering rules

These apply to every counter, tile, card and feed on the dashboard, and exist because the most
likely way this dashboard misleads someone is by rendering a failure as a zero.

1. **Three states, always.** Loading renders a skeleton of the final shape. Error renders an inline
   "Couldn't load" with a retry control. Loaded renders the value. There is no fourth state.
2. **An error never renders as `0`, `—`, or an empty list.** A tile that shows `0` failed token
   exchanges when the query failed is worse than one that shows nothing, because it is believed.
3. **Empty is not zero.** A developer with no clients gets an empty state that links to
   `/clients/new`, not a row of zeros. A developer with clients but no events in the window gets
   "No events in the last 24 hours", not `0`.
4. **Timestamps render in the viewer's local time zone, with the UTC value in the element's
   `title` attribute.** Activity data gets compared against server logs; an unambiguous UTC
   reading has to be available without leaving the page.
5. **Operator-set values render as authoritative; self-asserted values render as claims.** See
   [Surface C](#surface-c--agent-visibility) for the concrete treatment. It is applied consistently
   across the dashboard, not only on the agent row.

## Surface A — surface what already ships

### A1. Overview counters

**Proposed.** Three counters at the top of `/dashboard`: clients in `development`, `staging` and
`production`, plus a total.

**Shipped foundation.** `GET /api/clients` already returns each client's **effective** environment
— the stricter of the client's own column and its realm's ceiling — resolved through
`resolveEnvironmentPolicy` (`apps/auth-server/src/app/routes/clients/index.ts:427`) and projected
by `toClientResponse` (`apps/auth-server/src/app/routes/clients/index.ts:109`).

**Decision — count in the browser from the existing list response, do not add a counts endpoint.**
The clients list is already fetched for `/clients`; a developer's client count is small; and a
server-side counting endpoint would need its own filtering and caching story for a number that is
`array.filter(...).length`. The honest limit: this is `O(clients)` in one response body, and
`GET /api/clients` has no pagination today (`apps/auth-server/src/app/routes/clients/index.ts:413`
lists every row for the developer). **If `GET /api/clients` ever gains pagination, these counters
must move server-side in the same change** — a paginated list would silently make them count only
the first page.

### A2. API keys promoted to a first-class destination

**Shipped.** Static developer API keys work end to end. The backend registers mint
(`apps/auth-server/src/app/routes/clients/api-keys.ts:103`), list
(`apps/auth-server/src/app/routes/clients/api-keys.ts:180`) and revoke
(`apps/auth-server/src/app/routes/clients/api-keys.ts:206`), and the portal has a full
create/list/revoke UI in
`apps/developer-portal/src/components/api-keys-section.tsx`, rendered inside the client-detail page
(`apps/developer-portal/src/routes/_authed/clients.$clientId.tsx:222`). The delivery record agrees:
`apps/docs-site/src/lib/status.ts:162` carries API keys as `shipped`. The dashboard card that says
otherwise (`apps/developer-portal/src/routes/_authed/dashboard.tsx:42`) is simply stale.

**Proposed.** A `/api-keys` page listing every key the developer holds, grouped by client, and a
dashboard card linking to it.

**Decision — the page fans out server-side over the developer's clients.** There is no cross-client
key-listing endpoint, and this specification does not add one: the fan-out is
`listClientsHandler` followed by one `GET /api/clients/{clientId}/api-keys` per client, all inside a
single TanStack Start server function, so the browser makes one round trip. This reuses the
existing per-client endpoint rather than adding a fourth way to ask about keys.

**Decision — every client gets a section, including clients that cannot mint keys.** Only a client
whose effective environment resolves to `development` may mint — the gate is
`assertStaticApiKeysAllowed`, called before any hashing work
(`apps/auth-server/src/app/routes/clients/api-keys.ts:139`). It is tempting to list only those
clients. Do not: a client whose environment was tightened after a key was issued still **holds**
that key, and hiding the section would strand a live credential with no revocation path in the UI.
The create form still renders only where `staticApiKeysAllowed` is true — that gate is already
implemented and documented in the component's own contract
(`apps/developer-portal/src/components/api-keys-section.tsx:31`) — and clients that cannot mint show
the existing `client_credentials` guidance instead.

**Decision — the embedded section on the client-detail page stays.** `/api-keys` is an additional
route into the same component, not a replacement. Removing the embedded section would break the
flow a developer already knows for the sake of tidiness.

#### The fan-out's failure and scale behaviour

A fan-out is n requests pretending to be one, and every one of them can fail independently. The
universal rendering rules are written for a single surface; here is how they apply to n:

- **Concurrent, bounded at 8 in flight.** Sequential would make page load linear in client count;
  unbounded would let one developer with many clients open a connection burst against the
  auth-server from a single page view.
- **Partial failure renders per section, never as a silent gap.** If k of n sub-requests fail, the
  n − k that succeeded render normally and each of the k renders its own inline "Couldn't load keys
  for this client" with a retry that re-issues **only** that sub-request. The page does not fail
  whole, and — per universal rule 2 — a failed section never renders as "no keys", which would read
  as "nothing to revoke here."
- **A page-level banner states the count** — "2 of 9 clients couldn't be loaded" — because a reader
  scanning for a key they know exists needs to know the list is incomplete without finding the one
  broken section.
- **A `401` from any sub-request is different in kind** and short-circuits: it means the portal
  session expired mid-fan-out, so the page routes to `/login` rather than rendering eight
  successes and one auth error.
- **Section order is the client list's own order**, so `/api-keys` and `/clients` agree; within a
  section, keys are newest-first with revoked keys last.

**The scale ceiling is real, not hypothetical.** `GET /api/clients` is unpaginated — it returns
every row for the developer (`apps/auth-server/src/app/routes/clients/index.ts:413`) — so n is
unbounded by anything except how many clients someone has made.

**Decision — the design inverts at 25 clients.** Above that, `/api-keys` stops fanning out, renders
a client picker plus one client's keys at a time, and the dashboard card links to the picker. 25 is
chosen as roughly three screens of sections and, at 8 concurrent, about three round-trip waves —
past that the page is neither fast nor readable and the fan-out has stopped paying for itself. An
implementer hitting this ceiling in practice should read it as the signal to build the cross-client
list endpoint this specification declined to add, not as a reason to raise the number.

### A3. Consents — linked, but only after #366

**Shipped.** `/consents` exists and is functional in the sense that its code paths are written, but
it cannot authenticate for a developer who signed in through this portal. Issue **#366** records
three independent blockers, each fatal on its own:

1. The page depends on `__Host-qauth_session`, the auth-server's hosted-UI cookie
   (`apps/auth-server/src/app/helpers/session-cookie.ts:170`). The portal sets
   `__Host-qauth_portal_session` instead (`apps/developer-portal/src/server/session-cookie.ts:5`)
   and never visits `/ui/login`, so the cookie the page needs is simply absent.
2. That cookie is issued `SameSite=Lax` (`apps/auth-server/src/app/helpers/session-cookie.ts:371`),
   which withholds it from cross-site `fetch()` subresource requests regardless of
   `credentials: 'include'`.
3. Production CORS is fail-closed: `origin` resolves to `false` unless an operator sets
   `CORS_ORIGIN` (`apps/auth-server/src/app/plugins/cors.ts:48`).

It was the only page in the portal that called the auth-server directly from the browser. See
[the portal guide](/portal/guide/#the-consents-page) for the full account.

**Hard prerequisite — SATISFIED (#366).** Moving the consent calls behind TanStack Start server
functions was a **prerequisite for the dashboard's consents link, not a follow-up**: a dashboard
that links to a page which answers "Please sign in to manage authorized applications" to a
signed-in developer is worse than a dashboard that does not link it. That migration has landed —
the page is `apps/developer-portal/src/routes/_authed/consents.tsx`, backed by
`apps/developer-portal/src/server/actions/consents.server.ts` against `GET`/`DELETE
/api/consents` — and the `_authed` header already carries the link. The dashboard card described
below is now unblocked.

**Decision — no feature flag for the link.** The consents entry appears in the dashboard and the
authed header in the same pull request that lands #366's server-function migration, and not before.
A runtime flag for a two-line navigation change adds a configuration surface with no operational
benefit, and a flag that defaults off is a link nobody ever turns on.

**Proposed, as part of that same change.** The server functions must follow the shipped portal
pattern exactly: read the access token from the signed session cookie via a `readAccessToken`
equivalent (`apps/developer-portal/src/server/actions/clients.server.ts:19`), return the
`UNAUTHENTICATED` result when it is missing or expired
(`apps/developer-portal/src/server/actions/clients.ts:24`), and proxy with
`Authorization: Bearer <token>`.

**Two things #366 must solve that its task list does not name.** Both follow from the same fact —
the consents endpoints are built around a browser session, and a server function does not have one:

1. **Authentication.** They authenticate by **session cookie** and have no Bearer path at all
   (`apps/auth-server/src/app/routes/consents/index.ts:18`); the handlers resolve the caller through
   `resolveBrowserSession` (`apps/auth-server/src/app/routes/consents/index.ts:100`), which reads
   `__Host-qauth_session`. A portal server function holds a Bearer access token instead.
2. **CSRF.** `DELETE /consents/:id` requires the caller to echo an `X-CSRF-Token` header whose value
   is a per-session token minted (or reused) by the `GET` and stored on the browser session
   (`apps/auth-server/src/app/routes/consents/index.ts:68`, `ensureApiCsrfToken`), then compared
   with `csrfTokensEqual` on the delete
   (`apps/auth-server/src/app/routes/consents/index.ts:143`); the control and its timing-safe
   comparison are described in the module doc comment
   (`apps/auth-server/src/app/routes/consents/index.ts:36`). The token is anchored to an
   auth-server session that a Bearer-authenticated server function never establishes, so there is
   nothing to mint it against. **#366 must redesign this control, not merely relay the header.** The
   good news is that the control's own stated purpose — defending a cookie-authed, state-changing
   endpoint against cross-site and same-origin-XSS calls — largely evaporates once the caller is a
   server function presenting a Bearer token from an `HttpOnly` cookie the browser cannot read; but
   "largely" is doing work in that sentence and the decision belongs to #366 with security review,
   not to this page.

This specification records both as dependencies and pre-empts neither.

## Surface B — effective environment policy

**Shipped.** `apps/auth-server/src/app/helpers/environment-policy.ts` is the single authority.
`resolveEnvironmentPolicy` (`apps/auth-server/src/app/helpers/environment-policy.ts:248`) takes the
stricter of the client's declared environment and the realm ceiling — strictness ordering lives in
one map (`apps/auth-server/src/app/helpers/environment-policy.ts:46`) — and returns the frozen
profile from `ENVIRONMENT_PROFILES`
(`apps/auth-server/src/app/helpers/environment-policy.ts:170`). Both inputs fail safe to
`production`. See [Environment-Aware Authorization](/operate/environment-authorization/#the-profiles)
for the profile table itself.

**The rule the UI must obey: render the response, never re-derive the policy.** A UI that
reimplements strictness ordering will drift from what the server enforces, and the drift is
invisible until the moment it matters — a client shown as `development` while the server treats it
as `production`, or worse, the reverse.

### The gap this surface actually has

The brief for this work stated that Surface B needs no backend change because `GET /api/clients`
already returns the resolved policy. That is **half true, and the half that is false is
load-bearing.** The route resolves the full ten-field `EnvironmentPolicy`
(`apps/auth-server/src/app/helpers/environment-policy.ts:106`), but `toClientResponse` projects
exactly two of its fields — `environment` and `staticApiKeysAllowed`
(`apps/auth-server/src/app/routes/clients/index.ts:123`) — and `clientSchema` carries only those two
(`apps/auth-server/src/app/schemas/clients.ts:40` and
`apps/auth-server/src/app/schemas/clients.ts:48`). Token TTL tier, PKCE enforcement,
loopback-redirect tolerance, rate-limit tier, agent step-up and the consent-screen CSP relaxation
(`t3SecurityEnforced`) are all resolved server-side and then dropped on the floor.

So the UI has two options, and only one of them is acceptable:

- Re-derive the other eight fields in the portal from `environment`, by copying the profile table.
  **Rejected.** This is precisely the drift the rule above forbids, and the portal cannot import the
  authority module — `apps/developer-portal` and `apps/auth-server` are separate Nx applications
  with no dependency between them.
- Widen the response so the server keeps saying what it decided. **Chosen.**

**Rejected alternative — move `environment-policy.ts` into a shared library** so both apps import
it. It is the cleaner long-term shape and it is not this change: relocating the single authority
for every policy checkpoint in the system is a refactor with its own blast radius, whereas widening
a response schema is additive and reversible. Record it as a future option, do not do it here.

### Proposed — widen `clientSchema` with the resolved policy

Add a nested `policy` object to `clientSchema`
(`apps/auth-server/src/app/schemas/clients.ts:20`) carrying every field of the resolved
`EnvironmentPolicy`, populated directly from the resolver's return value inside `toClientResponse`.
Concretely: `environment`, `staticApiKeysAllowed`, `localhostRedirectAllowed`, `pkceRequired`,
`accessTokenLifespanTier`, `refreshRotationRequired`, `rateLimitTier`, `openDynamicRegistration`,
`agentStepUpEnforced`, `t3SecurityEnforced`.

**Plus two fields that are not on `EnvironmentPolicy`,** for reasons given below:
`declaredEnvironment` (the raw column, see [the effective-environment note](#the-policy-cards-three-traps))
and `loopbackRedirectPermitted` (a server-computed answer, see the same section).

**Decision — the widening cascades to two response schemas, deliberately.**
`createClientResponseSchema` (`apps/auth-server/src/app/schemas/clients.ts:132`) and
`regenerateSecretResponseSchema` (`apps/auth-server/src/app/schemas/clients.ts:177`) both
`.extend()` `clientSchema`, so both grow the new fields automatically. That is correct rather than
accidental: both are served through `toClientResponse`
(`apps/auth-server/src/app/routes/clients/index.ts:579` and `:817`), so the data is already there
and a client created or rotated through those paths gets the same policy view as one fetched later.
Name them in the pull request anyway — a schema that changes by inheritance is the kind of thing a
reviewer should be told about rather than discover.

**Decision — keep the existing top-level `environment` and `staticApiKeysAllowed`, duplicated.**
The shipped portal reads `client.staticApiKeysAllowed` to gate the API-key create form
(`apps/developer-portal/src/components/api-keys-section.tsx:31`). Removing the top-level fields
would break it for no gain. The duplication is deliberate and should be commented as such at the
schema.

**Decision — `policy` is read-only and must not appear in `createClientRequestSchema` or
`updateClientRequestSchema`.** The update schema's field list is closed
(`apps/auth-server/src/app/schemas/clients.ts:149`) and the existing `environment` field's own
contract already states why it is response-only: a developer must not be able to self-relax their
security posture through the management API
(`apps/auth-server/src/app/schemas/clients.ts:36`). The same reasoning covers every field of
`policy`.

### Proposed — what the UI renders

On the client-detail page, a **Policy** card. On the client list card, a compact environment badge
only. The detail card shows the six consequences an operator actually cares about, each as a
labelled row with the value and a one-line explanation of what it means for this client:

| Row                      | Source                                            | Rendered as                                                                        |
| ------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Access token lifetime    | `policy.accessTokenLifespanTier`                  | "Short" / "Long", with the tier name in the tooltip                                |
| PKCE                     | **Not a policy field — always "Required (S256)"** | See [the three traps](#the-policy-cards-three-traps) below                         |
| Loopback redirect URIs   | `policy.loopbackRedirectPermitted` (new)          | "Permitted" / "Rejected"                                                           |
| Rate limit               | `policy.rateLimitTier`                            | "Strict" / "Lenient"                                                               |
| Agent step-up            | `policy.agentStepUpEnforced`                      | "Enforced" / "Not enforced"                                                        |
| Consent-screen style CSP | `policy.t3SecurityEnforced`                       | "Strict" / "Relaxed (inline styles)" — see [trap 3](#the-policy-cards-three-traps) |

### The Policy card's three traps

Three rows in that table do **not** say what the obviously-named policy field appears to say, and
each would be a false security statement if they did. This section exists because the first draft of
this specification got all three wrong — which is the best evidence available that "render the
response, never re-derive" is necessary but **not sufficient**. Faithfully rendering a field whose
name reads like the answer, when it is only one input to the answer — or an answer about something
much narrower — produces exactly the drift the rule was written to prevent.

**Trap 1 — PKCE is mandatory for every client in every environment, and `pkceRequired` does not say
so.** `authorizeQuerySchema` declares `code_challenge` and
`code_challenge_method: z.literal('S256')` as **required, non-optional** query parameters
(`apps/auth-server/src/app/schemas/oauth.ts:32` and
`apps/auth-server/src/app/schemas/oauth.ts:37`). No client can obtain an authorization code without
an S256 challenge, whatever its environment. The token endpoint then enforces the downgrade floor
unconditionally — a `code_verifier` presented against a code carrying no challenge is
`invalid_grant` in **every** environment including `development` — the code calls it "a HARD FLOOR
enforced in EVERY environment" (`apps/auth-server/src/app/routes/oauth/token.ts:412`), implemented
at `apps/auth-server/src/app/routes/oauth/token.ts:419`. The surrounding comment states plainly
that the no-challenge branch exists only as defence-in-depth "for any future dev-only flow"
(`apps/auth-server/src/app/routes/oauth/token.ts:405`).

`policy.pkceRequired` is therefore not "is PKCE required" — its own contract says it governs only
whether the environment profile _additionally_ hard-requires it, on top of the project-wide floor
(`apps/auth-server/src/app/helpers/environment-policy.ts:123`). Rendering it as the PKCE row would
tell a `development` client's owner that PKCE is optional while `/oauth/authorize` rejects every
request without it.

**Decision — the PKCE row reads "Required (S256)", unconditionally, and is not sourced from any
policy field.** Its tooltip names the enforcement point: the authorize endpoint's own schema. There
is no false-y branch to render.

**Decision — do not render `oauth_clients.require_pkce` either.** It is already in the response
(`apps/auth-server/src/app/schemas/clients.ts:31`) and already typed in the portal
(`apps/developer-portal/src/server/auth-server-client.ts:74`), which makes it the obvious thing for
an implementer to reach for — and it would give the card two conflicting PKCE renderings.

The claim that matters is that **`requirePkce` is never read as an enforcement gate anywhere in
`apps/auth-server`.** Every reference to it is a write, the response projection
(`apps/auth-server/src/app/routes/clients/index.ts:122`), or a comment; no branch anywhere consults
it. A stored, exposed, unenforced flag must not be presented as a security control.

Do **not** reach instead for the weaker-sounding but tempting "and anyway it is always `true`" — it
is not. The developer-facing write paths do set it `true`
(`apps/auth-server/src/app/routes/clients/index.ts:539`, dynamic registration at
`apps/auth-server/src/app/routes/oauth/register.ts:168`, CIMD at
`apps/auth-server/src/app/helpers/cimd.ts:461`, and the column default at
`libs/infra/db/src/lib/schema/core.ts:410`), but a system client an earlier release created holds
`requirePkce: false`, as `getOrCreateSystemClient` wrote it until #631
(`apps/auth-server/src/app/helpers/oauth-client.ts`), reached from first-party login
(`apps/auth-server/src/app/routes/auth/login.ts:171`) and the authorize route
(`apps/auth-server/src/app/routes/oauth/authorize.ts:392`). The column genuinely varies. The
conclusion is unchanged — it is unenforced either way — but the supporting claim has to be the one
that is true.

**Trap 2 — loopback redirects are permitted in all three environments, and
`localhostRedirectAllowed` says otherwise.** The gate is `isRedirectUriAllowedForPolicy`, which
permits an `http://localhost` redirect when **either** the environment opts in **or** PKCE is
enforced: `policy.localhostRedirectAllowed || policy.pkceRequired`
(`apps/auth-server/src/app/helpers/oauth-redirect.ts:74`). Across the three shipped profiles
(`apps/auth-server/src/app/helpers/environment-policy.ts:170`) that disjunction is `true` every
time — `development` via the first term, `staging` and `production` via the second. The reasoning is
in the function's own doc comment: loopback plus S256 is safe on any host, and gating it on PKCE
rather than https-only is what lets native and MCP clients complete the auth-code flow against a
production authorization server (`apps/auth-server/src/app/helpers/oauth-redirect.ts:50`).

So a card rendering `localhostRedirectAllowed` would print "Rejected — https only" for every
staging and production client, while the server accepts their loopback URIs.

**Decision — the server computes and sends the answer, as `policy.loopbackRedirectPermitted`.**
`toClientResponse` evaluates the same disjunction the gate uses and puts the **result** in the
response; the UI renders that boolean and never sees the two inputs as a choice. Both inputs stay in
`policy` as well, because the response is the complete record of what the server decided — but the
rendered row is sourced from the computed field.

This is the general rule, stated once: **where an enforcement decision is a function of several
policy fields, the server sends the decision, not the arguments.** A field named after an input is
not an answer, and a UI that combines inputs is re-deriving policy no matter how simple the
combination looks.

**Trap 3 — `t3SecurityEnforced` does not gate the T3 hardening bundle; it gates one directive on one
page.** The T3 controls proper — security headers, CSRF, secure cookies — are global, have no client
in scope, and never read the flag: helmet is registered globally, the `/ui/login` and `/ui/consent`
CSRF checks always run, and the session cookie's `Secure` attribute comes solely from
`SESSION_COOKIE_SECURE`. The field's own contract says exactly that, and closes with "do not
document this flag as gating the whole bundle"
(`apps/auth-server/src/app/helpers/environment-policy.ts:157`). Its one consumer is the consent
screen — the rare browser surface that unambiguously carries a `client_id` — which marks the reply
for a relaxed style CSP when the flag is false
(`apps/auth-server/src/app/routes/ui/consent.ts:544`), so a developer iterating on that page is not
forced to nonce every style.

A row reading "T3 hardening bundle: Relaxed" would therefore tell a `development` client's owner
that clickjacking, MIME-sniffing and CSRF protection are off for them. They are not, in any
environment. [Browser security](/operate/browser-security/) states the same thing from the other
side, in bold — which is what makes linking that page from such a row worse than not linking it.

**Decision — the row is labelled "Consent-screen style CSP", renders "Strict" / "Relaxed (inline
styles)", and does not link to the browser-security page.** Unlike traps 1 and 2, the source field
is the right one; the trap is entirely in its name. What the row must not do is inherit that name.

**Decision — four `policy` fields are carried in the response and rendered nowhere.**
`pkceRequired` and `localhostRedirectAllowed` for the reasons in the first two traps above — they
are inputs, not answers. `refreshRotationRequired` and `openDynamicRegistration` because neither is
a consequence a developer can act on from the portal: refresh rotation is transparent to a correctly
implemented client, and dynamic registration is a realm-level posture this client's page cannot
influence. Carrying all four and rendering none is deliberate — it keeps the response the complete
record of what the server decided while keeping the card to what a reader can use.

**Decision — render tier names, not seconds.** `accessTokenLifespanTier` is a coarse label by
design; the concrete seconds come from realm and environment configuration through
`resolveAccessTokenLifespanSeconds`
(`apps/auth-server/src/app/helpers/environment-policy.ts:293`), which the client response does not
carry. Displaying a number the portal cannot actually resolve would be an invented capability.
"Short" with the tier name in the tooltip is honest; "3600 s" would not be.

**Decision — the card states that the environment is the _effective_ one, and why it may differ
from what the developer set.** A realm pinned to `production` overrides a client asking for
`development` (`apps/auth-server/src/app/helpers/environment-policy.ts:254`). A developer who set
`development` and sees `production` with no explanation will file a bug. One sentence — "Capped by
your realm's ceiling" — prevents it, shown only when the effective value is stricter than the
client's declared value. That comparison needs the declared value, which the response does not
carry; **so the widened `policy` object also carries `declaredEnvironment`**, the raw
`oauth_clients.environment` column (`libs/infra/db/src/lib/schema/core.ts:523`), read-only.

## Surface C — agent visibility

**Shipped semantics.** Two columns, two very different trust levels:

- `isAgent` (`libs/infra/db/src/lib/schema/core.ts:479`) is **self-asserted, unverified client
  input**. It arrives in the client's own dynamic-registration body or its own CIMD metadata
  document. The schema comment says so in as many words
  (`libs/infra/db/src/lib/schema/core.ts:469`), and the fail-closed accessor `isAgentClient`
  (`apps/auth-server/src/app/helpers/client-resolution.ts:94`) exists so nothing reads the column
  directly.
- `maxAgentMode` (`libs/infra/db/src/lib/schema/core.ts:496`) is **operator-set server state**. It
  is not part of any registration request; a client cannot raise its own cap
  (`libs/infra/db/src/lib/schema/core.ts:487`).

A reserved `agent:*` scope is granted only when **both** hold: the client is classified as an agent
**and** its cap covers the requested mode. `findExceedingAgentScopes`
(`apps/auth-server/src/app/helpers/scope-modes.ts:156`) rejects a reserved scope when either
condition fails, and `isModeWithinCap` returns `false` for a `null` cap
(`apps/auth-server/src/app/helpers/scope-modes.ts:105`). An absent or unrecognised cap grants
**nothing** — `parseAgentMode` returns `null` for anything it does not recognise rather than
defaulting to a mode (`apps/auth-server/src/app/helpers/scope-modes.ts:76`). Cap ordering is
`readonly < admin < exec`, and a cap is a maximum, not an exact match
(`apps/auth-server/src/app/helpers/scope-modes.ts:59`). See
[Agent authorization](/integrate/agent-authorization/) for the full layer.

### The gap this surface actually has

As with Surface B: neither column is in the client response. `toClientResponse`
(`apps/auth-server/src/app/routes/clients/index.ts:109`) does not project them and `clientSchema`
does not declare them (`apps/auth-server/src/app/schemas/clients.ts:20`). **Surface C is not
read-only-in-the-UI-only; it needs the same response widening as Surface B.**

**Proposed.** Add `isAgent: boolean` and `maxAgentMode: 'readonly' | 'admin' | 'exec' | null` to
`clientSchema`, projected read-only in `toClientResponse`, and — as with `policy` — **absent from
the create and update request schemas**. Ship both widenings in one change; they touch the same two
functions and splitting them means reviewing the same diff twice.

### Proposed — rendering the fail-closed state

This is the part that matters more than the widget. An empty field reads as "unrestricted", which
is the exact opposite of what a `null` cap means. The agent row therefore has **three** states and
never a blank:

| Condition                           | Badge                                          | Body copy                                                                                                              |
| ----------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `isAgent` false                     | "Not an agent" (neutral)                       | "`agent:*` scopes are refused for this client."                                                                        |
| `isAgent` true, `maxAgentMode` null | "Agent — no modes granted" (warning)           | "No `agent:*` scope can be granted. The cap is unset, and an unset cap grants nothing."                                |
| `isAgent` true, `maxAgentMode` set  | "Agent — up to `agent:<mode>`" (informational) | The three reserved scopes listed with permitted/refused markers, so the `readonly ⊂ admin ⊂ exec` relation is visible. |

**Decision — the third state enumerates all three reserved scopes, not just the cap.** Showing
"Cap: admin" requires the reader to know the ordering. Showing `agent:readonly` ✓,
`agent:admin` ✓, `agent:exec` ✗ does not. The subset relation is the part people get wrong.

**Decision — self-asserted and operator-set values get visually distinct treatments, applied
site-wide.** Operator-set values (`maxAgentMode`, effective `environment`, the whole `policy`
object) render as solid-filled badges. Self-asserted values (`isAgent`, and the client's
`declaredEnvironment`) render with a dashed outline and no fill, and their tooltip begins "Declared
by the client; not verified." One consistent visual rule for one real distinction, rather than a
footnote nobody reads.

**Decision — no edit controls anywhere on this surface.** Neither field is accepted by
`updateClientRequestSchema` (`apps/auth-server/src/app/schemas/clients.ts:149`), so an edit control
would either be disabled-on-arrival or would need a new write path that ADR-007's trust boundary
exists to prevent. The card carries a single line instead: "Set by an operator. Contact your
operator to change this."

## Surface D — activity feed and metrics tiles

> **Since 0.2.0 (#458) nothing writes `audit_logs`.** The auth server records events in the event
> store, and the upgrade copied the audit rows there. The feed reads the event store, whose reads
> always take a realm and filter by subject and client. The repository methods below read the
> table as it stood; it is read-only until a later release drops it.

**Shipped foundation.** The audit-logs repository has four read methods.
`findByRealmId` (`libs/infra/db/src/lib/repositories/audit-logs.repository.ts:112`),
`findByRealmAndUserId` (`libs/infra/db/src/lib/repositories/audit-logs.repository.ts:155`) and
`findByRealmAndActorClientId`
(`libs/infra/db/src/lib/repositories/audit-logs.repository.ts:218`) are realm-guarded — each adds a
realm predicate over an `innerJoin`. **`findByUserId` is not.** Its conditions are
`[eq(auditLogs.userId, userId)]` alone, with no realm predicate and no join
(`libs/infra/db/src/lib/repositories/audit-logs.repository.ts:81`); the guarded sibling
`findByRealmAndUserId` is the one that adds `eq(users.realmId, realmId)`
(`libs/infra/db/src/lib/repositories/audit-logs.repository.ts:164`).

That distinction matters for what follows. It is tempting to describe these four as a ready-made,
uniformly-safe base and reach for whichever one is closest — and one of them is not tenant-scoped at
all. **None of the four answers the question this surface asks anyway**: the developer-scoped query
is "rows whose owning client belongs to this developer", which is neither a user nor a realm nor an
actor predicate. What is missing is an HTTP surface **and** a new developer-scoped repository
method. Nothing here proposes a new data _layer_, but it does propose a fifth finder, and that
finder must carry its ownership predicate itself rather than inheriting a guarantee from a sibling.

Pagination in the existing options object is **offset-based**: `limit` and `offset`
(`libs/infra/db/src/lib/repositories/audit-logs.repository.ts:18`, the `FindAuditLogsOptions`
interface).

### Proposed — `GET /api/audit`

**Decision — a top-level collection with a `clientId` filter, not a route nested under
`/api/clients/{id}`.** The primary view is cross-client: the dashboard shows the newest events
across everything the developer owns. A nested route cannot answer that without N requests and a
client-side merge, which cannot be paginated correctly at all. Ownership is enforced identically
either way, so nesting buys nothing and costs the main use case.

**Decision — mounted the same way `/api/clients` is**, from a `routes/audit/` directory whose entry
file exports `autoPrefix = '/api/audit'`, mirroring
`apps/auth-server/src/app/routes/clients/index.ts:85`. Route paths stay resource-relative (`/` and
`/metrics`).

#### Authorization

`preHandler: fastify.requireJwt`, exactly as the list-clients route does
(`apps/auth-server/src/app/routes/clients/index.ts:358`), with `security: [{ bearerAuth: [] }]` in
the schema. `request.jwtPayload.sub` is the developer's `users.id`.

Ownership is the same rule the management API already enforces — scope by
`oauth_clients.developer_id` (`libs/infra/db/src/lib/schema/core.ts:456`), the rule
`resolveOwnedClient` applies per-client
(`apps/auth-server/src/app/routes/clients/index.ts:170`). For a collection it becomes a join
predicate rather than a per-row check:

> `audit_logs.oauth_client_id IN (SELECT id FROM oauth_clients WHERE developer_id = :sub)`

**Do not invent a second ownership pattern.** In particular, do not scope by realm: realm scoping
is the operator-tier boundary the repository's existing methods use, and it would return every
developer's rows in a single-realm deployment.

**Decision — a non-UUID `sub` short-circuits to an empty list**, mirroring
`apps/auth-server/src/app/routes/clients/index.ts:383`. A `client_credentials` token's `sub` is an
opaque `client_id`, not a UUID; querying Postgres with it raises `22P02` and surfaces as a 500.

**The empty case is a first-class requirement, not a fallback.** A developer with no clients gets
`200` and an empty array. Never a 403, never a 404, and never — under any code path, including the
one where the ownership subquery returns no rows — another developer's rows. The ownership
predicate must be applied unconditionally; there must be no branch that skips the `WHERE` clause
when the client set is empty.

#### Pagination

**Cursor-based, keyset over `(created_at DESC, id DESC)`.**

**Decision — the cursor is an opaque base64url string** encoding
`{ t: <created_at>, i: <id>, w: { from, to }, f: <filter fingerprint> }`.

- **Why keyset, not the repository's existing offset.** `audit_logs` is append-heavy. Under
  offset paging, rows inserted between two requests shift the window, so page 2 re-shows rows from
  page 1 and skips others. Deep offsets also degrade. A feed whose second page silently repeats
  its first is the kind of wrong nobody reports.
- **Why `(created_at, id)` is a valid total order.** `created_at` is epoch milliseconds
  (`libs/infra/db/src/lib/schema/audit.ts:62`) and can tie. `id` defaults to `uuidv7()`
  (`libs/infra/db/src/lib/schema/audit.ts:23`), which is time-ordered, so the pair breaks ties in a
  direction consistent with insertion order.
- **Why opaque.** The encoding must stay free to change — adding a field to it later must not break
  callers who stored one. Opacity is not a security control here; ownership is enforced server-side
  on every request regardless of what a caller puts in the cursor.

##### The window is resolved once and frozen in the cursor

This is the part a naive reading gets wrong, and getting it wrong breaks "Load more" outright. The
window has a default (`from` defaults to `to - 30 days`, and `to` defaults to **the time the first
request was received**). The fingerprint check rejects a cursor whose filters do not match the
request's. Put those two together carelessly and every Load-more either `400`s — because `to`
re-defaults to a later "now" and the fingerprint no longer matches — or silently slides the window
forward between pages and drops rows at the boundary. Both were latent in the first draft of this
specification.

**Decision — a pagination session is a snapshot, and the resolved window travels in the cursor.**

1. **First request (no cursor).** The server resolves `to` (query value, else request-receipt time)
   and `from` (query value, else `to - 30 days`), validates the span (`400` if wider than 90 days,
   `400` if `from > to`), and runs the query against that resolved window.
2. **`nextCursor` carries the resolved window** in `w`, alongside the position and the fingerprint.
3. **Subsequent request (with a cursor).** The window comes **from the cursor**, never re-defaulted.
   `to` is not re-evaluated against the clock, so the window cannot slide.
4. **If a cursor request also sends `from` or `to` and either disagrees with the cursor's window, it
   is a `400`** (`invalid_cursor`), not a silent override. Changing the window means starting a new
   pagination session; pretending otherwise would hand back a page from a different query.

The consequence, stated so the UI can be honest about it: **events written after a pagination
session begins do not appear in it.** That is the correct behaviour for a paged feed and it is why
"Refresh" (which discards the cursor and starts a fresh session) is a separate, explicit control —
see [the feed UI](#proposed--the-feed-ui).

##### The fingerprint, constructed

**Decision — the fingerprint is computed over the _resolved_ filter set, after defaults are
applied.** Because defaults are resolved before hashing on the first request and thereafter read
from the cursor, "explicit value" and "same value arrived by default" produce the same fingerprint.
There is no defaults-versus-explicit ambiguity left for the check to trip over; a mismatch means a
caller genuinely changed a filter.

Construction, exactly:

1. Build an object from the resolved filters — `clientId`, `event`, `eventType`, `success`, `from`,
   `to`. **Absent filters are omitted, never serialised as `null`**, so "not filtering by event" and
   "filtering by a null event" cannot collide.
2. Canonicalise: keys sorted lexicographically; booleans as `true`/`false`; integers in decimal with
   no separators; UUIDs lowercased; strings verbatim. Serialise as compact JSON, no whitespace.
3. `SHA-256` the UTF-8 bytes, take the **first 8 bytes**, encode base64url.

Eight bytes is deliberate: this is a consistency check against a caller accidentally mixing filter
sets across pages, not an adversarial control. Ownership and redaction are enforced server-side on
every request from the JWT, independently of anything in the cursor, so a forged fingerprint buys an
attacker nothing but their own rows in a confusing order.

**Decision — `limit` does NOT participate in the fingerprint.** Under keyset pagination the cursor
is a _position_, not an offset, so changing page size mid-session is harmless and correct. Making it
a `400` would break a legitimate UI (dashboard preview of 10, then "see all" at 25) for no
correctness gain.

`limit` defaults to `25`, maximum `100`. **A `limit` above the maximum is a `400`, not a silent
clamp** — a caller that asks for 500, receives 100, and sees no `nextCursor` will conclude it has
seen everything.

**Decision — fetch `limit + 1` rows and return `nextCursor` only when the extra row exists.**
Returning a cursor on a full-but-final page produces a "Load more" button that loads nothing.

#### Filters

All optional, all `AND`-combined.

| Parameter    | Type                                                | Notes                                                                               |
| ------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `clientId`   | UUID                                                | `oauth_clients.id`, matching every other per-client path in this API                |
| `event`      | string, exact match                                 | e.g. `oauth.token.exchange.failure`                                                 |
| `eventType`  | `auth\|token\|client\|security\|user\|realm\|agent` | The shipped enum (`libs/infra/db/src/lib/repositories/audit-logs.repository.ts:13`) |
| `success`    | boolean                                             |                                                                                     |
| `from`, `to` | integer, epoch milliseconds                         | Matches the column's own units                                                      |

**Decision — `clientId` is the row UUID, not the public `client_id` string.** Every other
per-client path in this API takes the UUID — `clientIdParamsSchema` is `z.object({ id: z.uuid() })`
on the client routes (`apps/auth-server/src/app/routes/clients/index.ts:134`) and
`z.object({ clientId: z.uuid() })` on the API-key routes
(`apps/auth-server/src/app/routes/clients/api-keys.ts:47`). The two identifiers are easy to confuse;
consistency with the existing surface is the tiebreaker. The response carries both so the UI never
has to guess.

**Decision — time bounds are epoch milliseconds, not ISO-8601.** `created_at` is a `bigint` in
milliseconds (`libs/infra/db/src/lib/schema/audit.ts:62`). Accepting ISO strings would put a parse
and a time-zone assumption between the caller and the column, and a boundary that is silently off
by an offset is the worst kind of filter bug.

**Decision — the default window is 30 days and the maximum span is 90 days**, resolved and frozen as
described under [the window](#the-window-is-resolved-once-and-frozen-in-the-cursor). This
bounds the keyset scan. There is no retention or pruning job for `audit_logs` anywhere in the tree
(searched `libs/infra/db/src` and `apps/auth-server/src` for retention/prune/purge; nothing matches
`audit_logs`), so the table only grows. This is an operational view, not an export.

#### Response shape and redaction

**Decision — the response is camelCase.** The management API's payloads are app-specific rather
than RFC wire formats, and the project's convention for those is camelCase
(`apps/auth-server/src/app/schemas/clients.ts:6`). The column names are snake_case; the wire format
follows the repository's existing management-API surface. Mixing the two would make `/api/audit`
the only inconsistent endpoint in the JSON API.

Returned per row:

| Field             | Source column         | Notes                                                                                                                                                                               |
| ----------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | `id`                  | Row key for the UI, and the cursor's second component                                                                                                                               |
| `event`           | `event`               |                                                                                                                                                                                     |
| `eventType`       | `event_type`          |                                                                                                                                                                                     |
| `success`         | `success`             |                                                                                                                                                                                     |
| `createdAt`       | `created_at`          | Epoch milliseconds                                                                                                                                                                  |
| `client`          | via `oauth_client_id` | A nested `{ id, clientId, name }` — the owning client's UUID, its public `client_id` string, and its name. The feed is cross-client, so a row has to say which client it belongs to |
| `scopeMode`       | `scope_mode`          | `libs/infra/db/src/lib/schema/audit.ts:60`                                                                                                                                          |
| `actorClientId`   | `actor_client_id`     | A public client identifier only, never a secret (`libs/infra/db/src/lib/schema/audit.ts:44`)                                                                                        |
| `delegationChain` | `delegation_chain`    | Ordered public `client_id`s; contains no token, secret or subject material (`libs/infra/db/src/lib/schema/audit.ts:51`)                                                             |

Withheld, always, with no query parameter that can turn any of them on:

- **`ip_address`** (`libs/infra/db/src/lib/schema/audit.ts:36`) and **`user_agent`**
  (`libs/infra/db/src/lib/schema/audit.ts:37`). End-user device and network data. A developer is not
  an operator; the portal is self-service with no operator vetting.
- **`user_id`** (`libs/infra/db/src/lib/schema/audit.ts:29`) — **omitted entirely, not
  pseudonymised.** Omission is the strictly smaller surface, no surface in this specification groups
  or joins by user, and a pseudonym is a stable correlator that would exist purely because it was
  available. If a future feature genuinely needs per-user grouping, adding a pseudonym then is
  additive; removing one that has shipped is a breaking change. Choose the reversible direction.
- **`metadata`** (`libs/infra/db/src/lib/schema/audit.ts:61`) — withheld wholesale. It is free-form
  `jsonb` written by many call sites with no shared schema (for example
  `apps/auth-server/src/app/routes/clients/index.ts:476`), so its contents cannot be
  redaction-reviewed once and trusted afterwards: a future call site could add end-user data to it
  without anyone revisiting this endpoint. **The projection is an allowlist of columns, never a
  denylist** — a column added to `audit_logs` later must not appear here by default.

This follows the data-minimisation precedent of **#259**, which gated ID-token email claims on
scope rather than emitting them because they were available.

##### The same rule applied to `event`, which is where it was initially missed

The argument for withholding `metadata` — an open namespace that a future call site can extend
without anyone revisiting this endpoint — applies verbatim to `event`, and the first draft of this
specification returned `event` unrestricted. It is a `varchar(100)`
(`libs/infra/db/src/lib/schema/audit.ts:33`) with no enum and no allowlist anywhere in the tree.

The leak is not hypothetical, and it is worth being precise about where it is and is not.
`delegation_chain`, `actor_client_id` and `scope_mode` are **not** the vector — those columns carry
public client identifiers and a coarse mode label, and nothing else
(`libs/infra/db/src/lib/schema/audit.ts:44`, `:51`). The vector is **an open event namespace plus a
millisecond timestamp.** Client-attributed rows already describe end-user authentication behaviour:
`oauth.stepup.required` is written with `oauthClientId: client.id` at **six** sites — five in the
authorize route (`apps/auth-server/src/app/routes/oauth/authorize.ts:354`,
`apps/auth-server/src/app/routes/oauth/authorize.ts:484`,
`apps/auth-server/src/app/routes/oauth/authorize.ts:550`,
`apps/auth-server/src/app/routes/oauth/authorize.ts:587`,
`apps/auth-server/src/app/routes/oauth/authorize.ts:616`) and one in the consent UI
(`apps/auth-server/src/app/routes/ui/consent.ts:810`) — and `oauth.consent.revoked` likewise
(`apps/auth-server/src/app/routes/consents/index.ts:181`). A developer holds their own application
logs; joining "a step-up was demanded at 14:02:11.431" against their own request log identifies
which of their users it was, and what that user was doing at the time. `user_id` being absent does
not help when the timestamp is the join key.

**Decision — both halves: an event allowlist, and coarsened timestamps.**

1. **`event` and `eventType` are served from an explicit allowlist**, applied with the same
   structural rule as the column allowlist: **a row whose `event` is not on the list is not
   returned at all** — not returned with the event redacted, which would leak its existence and its
   timestamp. A new event name added to the tree is invisible to this endpoint until someone puts it
   on the list, which is the same fail-closed direction as the column rule. The complete list, and
   the verdict for every other event in the tree, is
   [enumerated below](#every-event-in-the-tree-classified).
2. **`createdAt` is truncated to whole seconds on this surface.** Millisecond precision is what makes
   a log join a reliable identification, and no developer-facing use case here needs it: the feed is
   read by eye and the tiles count over a 24-hour window. Truncation happens in the projection, not
   in storage — the column keeps full precision for operators.

**The cursor keeps full millisecond precision**, because the keyset order depends on it
(`(created_at, id)` is only a total order at the stored resolution). The cursor is opaque and
server-minted, so this does not hand the precision back through the front door; it means only that
the coarsening is a display-and-response concern, never a query-correctness one.

##### Every event in the tree, classified

An allowlist that names some events and leaves the rest to fail closed is not a decision — it is a
decision deferred to whoever next reads the code and cannot tell whether an omission was reasoned or
overlooked. So: **every `event` string written anywhere in `apps/auth-server/src` or `libs` appears
exactly once below, with a verdict and a reason.** The enumeration is mechanical (all `event: '…'`
audit writes, test files excluded) and gives **38 distinct names** at the `lastVerified` date.

Three verdicts, not two — because a third category turned out to exist and matters:

- **Allow** — client-attributed, and it is the developer's own integration activity.
- **Exclude (policy)** — reachable, but it describes what an identified end user did. This is the
  category with a real cost.
- **Unreachable** — written with `oauth_client_id: null`, or attributed to a client whose
  `developer_id` is `null`. The ownership predicate already excludes these; the allowlist never gets
  a say. Recorded so nobody re-argues the policy for an event that cannot appear.

| Event                             | Verdict           | Reason                                                                                                                                                        |
| --------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `oauth.client.created`            | Allow             | The developer's own client lifecycle                                                                                                                          |
| `oauth.client.updated`            | Allow             | ditto                                                                                                                                                         |
| `oauth.client.deleted`            | Allow             | ditto                                                                                                                                                         |
| `oauth.client.secret_regenerated` | Allow             | ditto                                                                                                                                                         |
| `api_key.created`                 | Allow             | ditto                                                                                                                                                         |
| `api_key.revoked`                 | Allow             | ditto                                                                                                                                                         |
| `oauth.token.exchange.success`    | Allow             | The developer's own token traffic; 23 of 25 write sites are client-attributed                                                                                 |
| `oauth.token.exchange.failure`    | Allow             | ditto — the single most useful event for debugging an integration                                                                                             |
| `oauth.authorize.success`         | Allow             | The developer's own authorize traffic                                                                                                                         |
| `oauth.authorize.failure`         | Allow             | ditto; 7 of 8 sites attributed                                                                                                                                |
| `oauth.introspect.success`        | Allow             | The developer's own resource server introspecting a token (`apps/auth-server/src/app/routes/oauth/introspect.ts:221`)                                         |
| `oauth.introspect.failure`        | Allow             | ditto                                                                                                                                                         |
| `oauth.revoke.success`            | Allow             | The developer's own revocation call (`apps/auth-server/src/app/routes/oauth/revoke.ts:108`)                                                                   |
| `oauth.revoke.failure`            | Allow (no effect) | Policy says allow, but every write site is `oauthClientId: null` (`apps/auth-server/src/app/routes/oauth/revoke.ts:81`) — written before client auth succeeds |
| `oauth.stepup.required`           | Exclude (policy)  | Six attributed sites; describes an identified end user being challenged                                                                                       |
| `oauth.stepup.elevation`          | Exclude (policy)  | Attributed; an identified end user re-authenticating for a dangerous scope                                                                                    |
| `oauth.consent.granted`           | Exclude (policy)  | Attributed; an identified end user's consent decision                                                                                                         |
| `oauth.consent.denied`            | Exclude (policy)  | ditto, 3 sites                                                                                                                                                |
| `oauth.consent.revoked`           | Exclude (policy)  | ditto                                                                                                                                                         |
| `user.login.success`              | Exclude (policy)  | End-user behaviour. Also unreachable — attributed to the system client, whose `developerId` is `null`                                                         |
| `user.login.failure`              | Exclude (policy)  | End-user behaviour; `oauthClientId: null`                                                                                                                     |
| `user.logout.success`             | Exclude (policy)  | ditto                                                                                                                                                         |
| `user.logout.failure`             | Exclude (policy)  | ditto                                                                                                                                                         |
| `ui.login.success`                | Exclude (policy)  | Hosted-UI end-user behaviour; `oauthClientId: null`                                                                                                           |
| `ui.login.failure`                | Exclude (policy)  | ditto                                                                                                                                                         |
| `ui.login.csrf_failure`           | Exclude (policy)  | ditto                                                                                                                                                         |
| `oauth.userinfo.success`          | Unreachable       | `oauthClientId: null` (`apps/auth-server/src/app/routes/oauth/userinfo.ts:94`). Policy answer if that ever changes: allow                                     |
| `oauth.userinfo.failure`          | Unreachable       | `oauthClientId: null` (`apps/auth-server/src/app/routes/oauth/userinfo.ts:115`). Policy answer if that ever changes: allow                                    |
| `oauth.client.registered`         | Unreachable       | Attributed, but dynamic registration creates clients with `developerId: null` — see below                                                                     |
| `oid4vp.response.received`        | Unreachable       | `oauthClientId: null` (`apps/auth-server/src/app/routes/oid4vp/response.ts:240`); also wallet federation behind a default-off flag                            |
| `oauth.consent.csrf_failure`      | Unreachable       | `oauthClientId: null` (`apps/auth-server/src/app/routes/ui/consent.ts:638`)                                                                                   |
| `consents.revoke.csrf_failure`    | Unreachable       | `oauthClientId: null` (`apps/auth-server/src/app/routes/consents/index.ts:146`)                                                                               |

**On the three that prompted this enumeration.** `oauth.introspect.success` was a genuine omission —
`oauth.introspect.failure` was already on the list, so excluding its success twin was an
inconsistency, not a decision, and it is now allowed. `oauth.userinfo.success` / `.failure` are the
developer's own resource-server traffic and would be allowed on the same reasoning — but both write
`oauthClientId: null`, so allowlisting them would change nothing today and would misleadingly imply
they appear. They are recorded as unreachable **with their policy answer written down**, so if
userinfo ever becomes client-attributed the question does not have to be re-derived.
`oid4vp.response.received` is settled twice over: unattributed, and wallet-federation transport
behind a flag that is off by default.

**A fourth structural gap, found while enumerating: dynamically registered clients are invisible to
this feed entirely.** Both `POST /oauth/register`
(`apps/auth-server/src/app/routes/oauth/register.ts:177`) and CIMD registration
(`apps/auth-server/src/app/helpers/cimd.ts:468`) create clients with `developerId: null`. The
ownership predicate is `oauth_clients.developer_id = :sub`, so **no** row belonging to a DCR or CIMD
client can ever match it — not just `oauth.client.registered`, but every token exchange and
authorize event those clients generate. A developer whose clients were all registered dynamically
sees an empty feed and no explanation. This is a property of the ownership model, not of the
allowlist, and it cannot be fixed here: `developer_id` is the only ownership signal the schema has.
The feed's empty state must therefore say so rather than reading as "nothing happened" — see the
footnote below. The ownership position itself is now settled in
[ADR-012](/reference/records/adr/012-dynamic-client-ownership/): a DCR registration carrying a
developer access token IS attributed (#374), an anonymous one is not, and a CIMD client is not
ownable at all — so this gap narrows but does not close, and the empty state is still required.

##### The allowlist's cost, stated in one place

So that this never has to be reconstructed from two lists again, here is everything the feed does
not show, complete:

1. **End-user authentication and consent activity for the developer's own clients** — step-up
   challenges, step-up elevations, and consent granted / denied / revoked. These are reachable,
   client-attributed rows that are deliberately withheld. **This is the real cost of the policy
   decision**, and it is larger than "consent and step-up were excluded" suggests in the abstract:
   it means a developer cannot see, for their own application, that a user was challenged for
   step-up or withdrew consent.
2. **All first-party and hosted-UI login/logout activity** (`user.*`, `ui.*`) — excluded on the same
   grounds, and unreachable anyway.
3. **Anything belonging to a dynamically registered or CIMD client** — the whole client, not
   selected events, per the structural gap above.
4. **Anything recorded before a client was identified**, and **anything belonging to a client the
   developer has since deleted**.
5. **Millisecond precision on every timestamp** — the feed shows whole seconds.

Items 1 and 5 are reversible policy choices and should be re-confirmed with the owner before
implementation rather than after. Items 2, 3 and 4 are structural.

#### What the feed structurally cannot show

Four categories of row will never appear, and the UI must say so rather than leave an unexplained
gap. The first is a policy choice; the other three are structural. The complete cost is stated in
[one place above](#the-allowlists-cost-stated-in-one-place); this section covers only the three
structural causes and their code anchors.

1. **Rows whose `event` is not on the allowlist** — see
   [the classification table](#every-event-in-the-tree-classified). A policy choice.
2. **Rows written before a client was resolved.** Many failure paths record `oauthClientId: null` —
   for example `apps/auth-server/src/app/routes/oauth/authorize.ts:189` and
   `apps/auth-server/src/app/routes/oauth/token.ts:195`. They have no client to be scoped to.
3. **Rows belonging to a deleted client.** The FK is `set null` on delete
   (`libs/infra/db/src/lib/schema/audit.ts:30`), so deleting a client detaches its entire audit
   history from the ownership predicate.
4. **Every row belonging to a dynamically registered or CIMD client**, because those clients carry
   `developerId: null` (`apps/auth-server/src/app/routes/oauth/register.ts:177`,
   `apps/auth-server/src/app/helpers/cimd.ts:468`) and the ownership predicate is
   `developer_id = :sub`.

**Decision — gap 4 gets its own empty state, not the generic one.** A developer whose clients were
all registered dynamically would otherwise see the ordinary "No events yet", which reads as "nothing
happened" when the truth is "this surface cannot show your clients at all". When the developer owns
zero clients by `developer_id` **and** the feed is empty, the empty state says so explicitly and
points at `/clients/new`. Distinguishing the two cases costs one extra count and prevents a bug
report that would be impossible to reproduce.

**Decision — an `event` or `eventType` filter naming something outside the allowlist is a `400`, not
an empty result.** An empty result is an existence oracle: it lets a caller distinguish "no such
events for me" from "that event is withheld" only by guessing, and it invites an implementer to
treat the filter as the authority instead of the allowlist. Reject the request and name the
constraint.

**Decision — a permanent footnote under the feed**, not a tooltip and not a documentation-only
note: "This feed shows a defined set of client and token events for the clients you own. Your end
users' sign-in, step-up and consent activity is not shown. Neither is anything recorded before a
client was identified, anything belonging to a client you have since deleted, or anything from a
dynamically registered client. Times are shown to the nearest second."

Say all five things. A feed that quietly omits a category is an audit-shaped surface making a
promise it does not keep, which is the failure mode this whole page is trying to avoid.

#### Proposed — index migration

The ownership predicate plus the keyset order needs a composite index. The shipped indexes are
`idx_audit_logs_oauth_client_id` on the FK alone
(`libs/infra/db/src/lib/schema/audit.ts:66`) and `idx_audit_logs_created_at` on the timestamp alone
(`libs/infra/db/src/lib/schema/audit.ts:69`); neither supports "this client's rows, newest first"
without a sort. **Add exactly one index — `idx_audit_logs_client_created_at` on
`(oauth_client_id, created_at DESC)` — in a migration that lands before the endpoint**; see
[ordering](#implementation-order-and-dependencies).

**Be honest about what that index does and does not do.** The common case is the feed with **no**
`clientId` filter, which is not a single-value lookup: the predicate is
`oauth_client_id = ANY(<the developer's clients>)`. Postgres serves that from this index as one
index scan per array element, and it will generally **not** preserve the global
`created_at DESC` ordering across them — expect a sort, or a merge, above the scans. The index still
earns its place: it turns each per-client access into a range scan already ordered within that
client and already bounded by the window, so the sort input is "this developer's rows in the last 30
days" rather than the table. **That bound is the real protection, and it is why the window is
mandatory and capped rather than optional.**

**Decision — do not add a second index for the tiles.** The tile window is 24 hours against the
feed's 30 days, so the same composite index reaches a set roughly thirty times smaller, and the
event/`success` predicates are applied as a filter above it. One index that serves both surfaces
adequately beats two that each serve one perfectly, on a table with no pruning where every index is
a permanent write cost.

**Retracted: two claims of index support that do not hold.** An earlier draft of this page credited
the two existing partial indexes for the metrics tiles. Neither works, and the reasoning is worth
keeping so it is not re-invented:

- **`idx_audit_logs_failed`** is `(event, created_at) WHERE success = false`
  (`libs/infra/db/src/lib/schema/audit.ts:71`). A partial index is only usable when the query's
  predicate **implies** the index predicate, and Postgres cannot infer `success = false` from
  `event = 'oauth.token.exchange.failure'` — the naming convention is a project convention, not a
  constraint the planner knows about. The fix is in the query, below.
- **`idx_audit_logs_actor_client_id`** is `(actor_client_id, created_at) WHERE actor_client_id IS
  NOT NULL` (`libs/infra/db/src/lib/schema/audit.ts:77`). The "agent actions" count constrains the
  leading column only with `IS NOT NULL`, which is the index's own partial predicate — so there is
  no range to seek to and the scan degenerates to reading the whole partial index. It also carries
  no ownership column, so every row it returns still needs checking. It is the right index for
  "this specific agent's activity, newest first", which is the query
  `findByRealmAndActorClientId` was built for
  (`libs/infra/db/src/lib/repositories/audit-logs.repository.ts:218`) — not for this tile.

### Proposed — `GET /api/audit/metrics`

**Decision — a separate path, not a query flag on the feed.** A `?metrics=true` parameter that
changes the response shape cannot be expressed in one OpenAPI schema, and the two surfaces need
different cache policies. Two paths, two schemas.

**Decision — the tiles aggregate from `audit_logs`, never from the Prometheus registry.** The
registry is a per-process `Registry` instance created at plugin registration
(`apps/auth-server/src/app/plugins/metrics.ts:46`) and served by `GET /internal/metrics` on the
internal listener (`apps/auth-server/src/app/internal/routes/metrics.ts`). It is process-local, it resets on restart, and
behind replicas each process holds a different partial count. It is also global — it has no notion
of which developer owns what — so it could not answer a per-developer question even if it were
durable. `audit_logs` is durable, attributable and indexed. See
[Observability](/operate/observability/) for what the registry is legitimately for.

**Window: a rolling 24 hours** (`created_at >= now_ms - 86_400_000`), stated on the tile group, not
implied.

Four tiles, all scoped by the same ownership predicate and the same 24-hour window, all served from
the one composite index above:

| Tile                    | Predicate                                                    |
| ----------------------- | ------------------------------------------------------------ |
| Tokens issued           | `event = 'oauth.token.exchange.success'`                     |
| Token failures          | `event = 'oauth.token.exchange.failure' AND success = false` |
| Authorizations          | `event = 'oauth.authorize.success'`                          |
| Agent-attributed events | `actor_client_id IS NOT NULL`                                |

**Decision — the "Token failures" predicate carries `AND success = false` explicitly**, even though
it is redundant against today's data. Every `.failure` event in the tree is written with
`success: false` — verified by extracting all 53 `.failure` audit writes across
`apps/auth-server/src` and checking each one's `success` field — so this changes no result. It is
there because the redundancy is the _contract_: it documents at the query site that the naming
convention and the boolean must agree, and it is the form a partial index on `success = false`
could ever match. Without it the predicate silently depends on a convention nothing enforces.

**Decision — one aggregate query with four `count(*) FILTER (WHERE ...)` clauses, not four
queries.** All four share the ownership predicate, the window and the index access path; splitting
them multiplies that work by four for no benefit. This is an assertion about query shape, not a
benchmarked claim about performance — if it proves wrong under load, the tiles are independent
enough to split without changing anything else in this specification.

**Decision — the fourth tile is called "Agent-attributed events", not "Agent actions".** It counts
audit rows that carry an `actor_client_id`, which is a narrower and more literal thing than "actions
an agent took": today five call sites write that column, four in
`apps/auth-server/src/app/routes/oauth/token.ts` — `client_credentials` token issuance, delegated
token exchange, ID-JAG token exchange and the `jwt-bearer` (ID-JAG) grant — plus consent step-up
elevation in `apps/auth-server/src/app/routes/ui/consent.ts`. Whatever an agent then does against a
resource server is invisible to this authorization server. "Agent actions" would promise the latter.

**A note on what this tile counts, because it is easy to get backwards.** All five write sites set
`oauthClientId` and `actorClientId` from the **same** client — the agent is both the row's owning
client and its actor. So under an ownership predicate on `oauth_client_id`, this counts rows where
**the developer's own agent client acted**, which is the intended question. It does not count rows
where someone else's agent acted upon the developer's client; no such row exists, because nothing
writes an `actor_client_id` that differs from the row's `oauth_client_id`. Delegation depth is
recorded in `delegation_chain`, not by splitting the two columns
(`libs/infra/db/src/lib/schema/audit.ts:54`).

**Decision — "Token failures" is labelled "attributed to your clients" in its helper text.** It
undercounts: failures recorded before the client is resolved carry no `oauth_client_id` (see
[above](#what-the-feed-structurally-cannot-show)). A tile that undercounts without saying so is a
tile that gets trusted for something it cannot do.

**Decision — the tiles are not filtered by the feed's event allowlist.** They are aggregate counts
over named events, and every event they count is on the allowlist anyway. Stating it prevents an
implementer from wiring the allowlist in twice and quietly zeroing a tile.

**Decision — cache for 60 seconds in Redis, keyed by `developerId` and window.** Redis, not
in-process memory, for the same reason the Prometheus registry was rejected: a per-process cache
gives different replicas different answers. `fastify.redis` is already available and the
set-with-TTL pattern is established (`apps/auth-server/src/app/helpers/cimd.ts:513`). Sixty seconds
bounds the worst case to one aggregate query per developer per minute while staying visibly fresh
for a surface that is a trend indicator, not a monitor.

#### Rate limits for both endpoints

`POST /api/clients` sets the precedent that an expensive authenticated handler gets its own per-route
budget rather than riding the global default
(`apps/auth-server/src/app/routes/clients/index.ts:457`, capped per-IP because create runs an
argon2id hash). These two reads are the most expensive in this API for a different reason — an
uncached keyset scan and an aggregate, both over a table with no pruning — so they need budgets too,
but keyed differently.

**Decision — both endpoints are rate-limited per authenticated developer, not per IP.** The
argon2id routes cap by IP because the cost is inflicted before the caller is known to be legitimate.
Here the caller is already authenticated by `requireJwt` and the cost scales with _their_ data, so
`request.jwtPayload.sub` is the correct key; an IP key would throttle a whole office behind one NAT
and would not throttle a single developer looping from many addresses.

- **`GET /api/audit`** — 60 requests per minute per developer. Comfortably above a human clicking
  "Load more" and far below a scripted export, which is not what this surface is for.
- **`GET /api/audit/metrics`** — 30 requests per minute per developer. The 60-second cache already
  absorbs repeat traffic, so this only bounds a caller deliberately missing the cache.

Both are ordinary `config.rateLimit` blocks in the route definition, the same mechanism
`POST /api/clients` uses. Neither is rate-limit-exempt: `GET /internal/metrics` has no rate limit
because a scraper polls it, on a listener that admits only known peers
(`apps/auth-server/src/app/internal/routes/metrics.ts`), and that reasoning does not transfer to a
developer-facing endpoint.

**Decision — the tiles render an "as of" relative timestamp.** A number that can be 60 seconds
stale must say so, or it will be read as live and disbelieved when it disagrees with the feed
directly beneath it.

### Proposed — the feed UI

**Decision — a "Load more" button, not infinite scroll.** Infinite scroll over a live-append table
with a keyset cursor produces duplicates across re-renders and gives the reader no stable sense of
position. A button makes each fetch an explicit action and the cursor a single monotonic hand-off.

**Decision — no auto-refresh; a manual "Refresh" resets the cursor and clears the loaded pages.**
Auto-refresh would put the visible list and the held cursor into permanent disagreement.

**Decision — the dashboard preview shows ten rows and links to `/activity`; `/activity` fetches
twenty-five at a time.** The preview exists to make a problem visible, not to be read in full.

**Decision — the portal reaches both endpoints only through TanStack Start server functions.** The
browser must never call the auth-server directly. This is the exact mistake #366 fixed on the
consent screen — where a regression test now asserts the page contains no browser-side `fetch()`
at all — and the whole portal holds the property everywhere else. Do not add a new exception.

## Implementation order and dependencies

Ordered. Each step assumes every step above it has landed.

1. **Correct the API-keys card and ship `/api-keys`.** No backend dependency, and it is the only
   change that retracts an actively false statement
   (`apps/developer-portal/src/routes/_authed/dashboard.tsx:42`). Ship it first.
   - **Docs dependency:** [Known gaps](/portal/known-gaps/) opens with that stale card. Its first
     section becomes wrong the moment this lands and must be updated in the **same** pull request.
2. **Widen `clientSchema` with `policy`, `declaredEnvironment`, `isAgent` and `maxAgentMode`.** One
   change, covering Surfaces B and C — they touch the same two functions.
   - The portal's own `OAuthClient` interface
     (`apps/developer-portal/src/server/auth-server-client.ts:63`) must be widened in the same pull
     request, or the new fields arrive at runtime with no types and get quietly ignored.
   - **`apps/docs-site/public/openapi.json` must be regenerated in the same pull request**
     (`pnpm exec nx run auth-server:openapi-export`, declared at
     `apps/auth-server/project.json:69`). The response schema is part of the spec.
3. **Ship Surfaces B and C in the UI.** Depends on 2.
4. **Land the `idx_audit_logs_client_created_at` migration.** Before the endpoint, not with it — an
   endpoint merged ahead of its index is a sequential scan in production for however long the two
   pull requests are apart.
5. **Ship `GET /api/audit` and `GET /api/audit/metrics`, with the ownership filter and the redaction
   allowlist tested, before any UI consumes them.** A UI built against an unredacted response bakes
   fields into components that then have to be removed, and the removal is the change nobody
   prioritises.
   - **`apps/docs-site/public/openapi.json` and
     [the API reference](/integrate/api-reference/) must change in the same pull request as the
     route**, regenerating the spec with `pnpm exec nx run auth-server:openapi-export`. This is a
     hard CI constraint, not a courtesy: `findRoutesMissingFromOpenApi`
     (`apps/docs-site/src/invariants/endpoint-coverage.test.ts:76`) asserts that every route
     statically extracted from `apps/auth-server/src/app/routes` appears in `openapi.json`, and the
     legs-2-and-3 case (`apps/docs-site/src/invariants/endpoint-coverage.test.ts:115`) asserts exact
     path-set equality between `openapi.json` and the API reference page. Merging the route alone
     red-fails the docs-site suite, and merging the docs alone fails it in the other direction.
6. **Ship the metrics tiles and the activity feed UI.** Depends on 5.
7. **#366 — move the consent calls behind server functions.** Independent of 1–6; can run in
   parallel. Its own internal order: settle how a server function authenticates **and** what
   replaces the session-anchored `X-CSRF-Token` control
   (`apps/auth-server/src/app/routes/consents/index.ts:143`) before writing the server functions —
   both change the auth-server side, and discovering the CSRF problem after the portal side is
   written means writing it twice.
8. **Link consents from the dashboard and the authed header.** Depends on 7, in the same pull
   request as 7. Never before.

### One more dependency, in the opposite direction

The guard that catches documentation claiming a shipped feature is unbuilt scans the site content
tree and the two READMEs (`apps/docs-site/src/invariants/status-claims.ts:282`, the
`findStaleStatusClaims` function). It does **not** scan `apps/developer-portal`. That is precisely
why "Coming soon in Phase 2.3" survived in a React component for two shipped issues while the
documentation stayed correct. Extending the guard's scan set to portal source is a reasonable
follow-up and is **not** a prerequisite for anything above — it is recorded here so the next person
to ask "how did that survive?" has the answer.

## What this specification does not settle

Stated plainly, so nobody mistakes silence for a decision:

- **How a portal server function authenticates to the auth-server's consents endpoints, and what
  replaces their session-anchored CSRF token.** Both are set out under
  [Surface A3](#a3-consents--linked-but-only-after-366); both are #366's to answer, and the CSRF
  half is not on #366's task list today.
- **Whether `environment-policy.ts` should move to a shared library.** Rejected for this change,
  with reasons, but the question is legitimate and will recur.
- **Retention for `audit_logs`.** There is none today. The 90-day query cap bounds the read side;
  it does nothing about the table growing without limit.
- **Realm-level visibility of any kind.** Out of scope by the non-goals above, and it should stay
  out until an operator role exists to own it.

## See also

- [Portal guide](/portal/guide/) — the session model, and every flow the portal implements today.
- [Known gaps](/portal/known-gaps/) — the baseline this specification is written against.
- [Environment-Aware Authorization](/operate/environment-authorization/) — the ADR-008 policy
  Surface B renders.
- [Agent authorization](/integrate/agent-authorization/) — the ADR-007 layer Surface C makes visible.
- [Observability](/operate/observability/) — what the Prometheus registry is for, and why the
  metrics tiles do not use it.
- [API reference](/integrate/api-reference/) — where `/api/audit` must be documented when it ships.

---

# Reference

URL: https://docs.qauth.dev/reference/

This lane is for reference material for QAuth's APIs, configuration, and terminology.

---

# Status

URL: https://docs.qauth.dev/reference/status/

Current release: v0.2.3 (pre-1.0, 2026-11-12).

### Delivery tracks

- T0 Trust floor (shipped): Real-DB (testcontainers) repository tests, logout endpoint test, CI typecheck + coverage gate.
- T1 MCP productization (shipped): `@qauth-labs/resource-guard` (RFC 9728 metadata + token validation + step-up scope challenges), Client ID Metadata Documents (CIMD) support, MCP quickstart + example, RFC 7009 revocation.
- T2 Agent-native authorization (shipped): Agent client type, RFC 8693 on-behalf-of token exchange, scope modes (ReadOnly / Admin / Exec), step-up, per-agent audit.
- T3 OIDC conformance + hardening (shipped): Security headers, CSRF, secure cookies, OIDC ID token/nonce/claims, structured logging + Prometheus metrics, failed-login lockout.
- T5 Environment-aware authorization (shipped): `environment` (development / staging / production) as a fail-safe policy dimension; `resolveEnvironmentPolicy` drives token TTLs, PKCE, localhost redirects, rate-limit tier, agent step-up; environment-gated developer API keys.
- T4 Federation + PQC (long-term platform) (partial): Identifier abstraction, the gate this track waited on, shipped and closed. Wallet federation completes a browser sign-in end to end behind a default-off flag — HAIP profile wiring (#377) and the same-device return leg (#405) both landed 2026-09-11 — with the real-wallet interoperability pass still open; PQC hybrid signing shipped behind a default-off flag. See the feature rows below.

### Feature status

- Identifier abstraction (ADR-002) (shipped): Epic #224 closed. Migrations 0010–0012 shipped, including the destructive 0011 that dropped `users.email`, `users.email_normalized`, and `users.password_hash`. `users` is now a pure identity anchor; credentials live in `user_credentials`. Not a gate for anything else — done.
- PQC / hybrid signing (shipped, flag HYBRID_SIGNING_ENABLED default off): Epic #241 closed. Hybrid ML-DSA-65 + Ed25519 signing, mixed AKP+OKP JWKS, a native aws-lc-rs backend via napi-rs, and an attested reproducible build channel (byte-for-byte determinism verified on Linux only) all shipped.
- Wallet federation / OID4VP (partial, flag WALLET_FEDERATION_ENABLED default off): Merged: `VerifierProfile` (#299), OID4VP 1.0 request generation and `direct_post` intake (#233), the per-realm issuer trust allowlist (#236), ES256 + JWE crypto (#298), SD-JWT VC presentation validation (#234), Token Status List revocation (#297), the wallet sign-in UI (#239) and the end-to-end mock-wallet suite (#240, `apps/auth-server/src/app/wallet-federation.integration.test.ts`). A browser completes a wallet sign-in — account linking, sign-in with a linked wallet, and `acr` — once the flag is on and a `VerifierProfile` is named; since 2026-10-19 wallet sign-in creates no accounts (ADR-009 §1, amended), so a wallet is linked from a signed-in account first; with the flag on and no profile named the deployment refuses to start rather than falling back to a default posture. Validated so far only against a mock wallet, on both profiles. HAIP profile wiring (#377) closed 2026-09-11 with Phase C (encrypted `direct_post.jwt`), so `haip-1.0` boots when provisioned; the same-device return leg (#405, ADR-013) landed the same day — the user picks the device on the sign-in form, a same-device flow is answered with an OID4VP 1.0 §8.2 `redirect_uri` carrying a single-use Response Code and completes only in the browser that started it, and the cross-device QR flow is unchanged. Open: the real-wallet interoperability pass (#376). Key-storage assurance into the assurance policy (#379) closed 2026-08-26.
- Agent-native authorization (shipped): Agent client type, RFC 8693 on-behalf-of token exchange (`act` claim), scope modes (ReadOnly / Admin / Exec), step-up before dangerous operations, per-agent audit.
- Environment-aware authorization (shipped): `environment` selects a fail-safe policy profile across token TTLs, PKCE, localhost redirects, rate-limit tier, and agent step-up.
- RP-initiated logout (shipped): OpenID Connect RP-Initiated Logout 1.0 at `/oauth/end-session` (GET and POST), listed in discovery as `end_session_endpoint`. A valid `id_token_hint` for the signed-in account ends that browser session at once; any other signed-in browser confirms first. The browser goes back only to a `post_logout_redirect_uris` entry the client registered, matched exactly. There is no front-channel logout (ADR-018).
- Back-channel logout (shipped): OpenID Connect Back-Channel Logout 1.0: a client registers `backchannel_logout_uri` (an `https` URI on public addresses), and whenever a session ends, by any path, each client it served gets a signed `logout+jwt` logout token at that URI. The token is queued in the transaction that ends the session and sent by the delivery role through the SSRF-safe egress client, with retries; a failed delivery never holds a sign-out back. Discovery lists `backchannel_logout_supported` and `backchannel_logout_session_supported` (#624).
- Upstream OpenID Connect sign-in (partial): A person signs in, or signs up when the realm allows it (`ALLOW_SIGN_UP`, off by default), through one of the realm's upstream OpenID Connect providers (#639): a button per listed provider on the sign-in page and the `upstream` step of the Interaction API, or `qauth_upstream=<type>` on the authorization request, hidden providers included. The account is found by `(realm, provider type, sub)` and tied to the ID token's issuer, never matched by email; a new one gets the provider's claims as attributes, verified unless the provider's verified switch is off. On the ceremony page an unknown identity first asks whether it starts a new account or joins an existing one, which links it only after a fresh sign-in to that account; a signed-in person links one with `qauth_link=<type>`, and the account API lists and unlinks them (#670). Open: the admin API that manages the providers (#714), which are rows of `realm_upstream_providers` until then; provider icons; and the review-your-details page. An account that holds a passkey is asked for it while passkeys are on (`WEBAUTHN_ENABLED`) and refused otherwise, and while `INTERACTION_UI_ENABLED` is off an unverified account is refused rather than verified inline.
- Passkey sign-in (partial, flag WEBAUTHN_ENABLED default off): Built (#651): the sign-in engine's `webauthn_get` and `webauthn_create` steps, passkey-first order with no `login_hint`, the downgrade rule (a login completes only after the account's strongest bound factor, a disabled passkey included), an assertion refused without the user-verification flag, `amr` `["pop","mfa"]` or `["pwd","pop","mfa"]`, the optional enrolment after a password sign-in with a recovery set at the first one, and the two `/ui` pages that run the ceremonies. Sign-up with a passkey alone (#655): an account with no email address and no password, verified by the ceremony, whose recovery set is shown before the code is issued; no mail is ever sent to it, its notices are in the security log, and a recovery code offered beside the first sign-in step finds it, then binds a new passkey in place of the lost one. `/auth/login` and `/ui/login` already refuse a right password of an account that holds a passkey. Open: the FiPA endpoint (#646); the design-system screens (#652).
- Authenticator app (TOTP) second factor (partial): Built (#653): the sign-in engine's `totp` step after the first factor of an account that holds one (SHA-1, six digits, 30 seconds, one step of tolerance, a time step never accepted twice), `amr` `["pwd","otp","mfa"]` for a password then a code, and the `totp_setup` step that binds a new secret to a verified account after a first valid code and a fresh factor, with no mailed code, and issues a recovery set at the first binding. The secret is sealed under the realm's `data_at_rest` key. Wrong codes count per account on their own failure ladder, a password never clears them, and at 100 in a row the app is turned off only while the hosted pages are on and the account keeps another way in; three notices no realm can switch off. The two `/ui` pages serve the steps. `/auth/login` and `/ui/login` refuse a right password of an account that holds one. Open: the stored MFA policy that asks for the set-up (the admin console), the account API's own enrolment, the FiPA endpoint (#646) and the design-system screens (#654).
- Hosted account pages (partial, flag INTERACTION_UI_ENABLED default off): Built (#844): `/ui/account`, the signed-in person's own account on the hosted pages, in their current server-rendered style: the sign-in methods, a password change under the realm's password policy, passkeys (add through the sign-in's enrolment step, rename, remove), the authenticator app (set up, turn off), a new recovery code set shown once, linked upstream accounts (link by signing in, unlink) and the sessions (sign one out, sign out everywhere, which tells each relying party with a back-channel logout URI). Every form works without JavaScript and carries a CSRF value, every change asks for the fresh authentication the account API asks of it, a removal never leaves the account without a way in, and each change is a user event. On while the hosted pages are (`INTERACTION_UI_ENABLED`); the routes are experimental. The design-system account console replaces them: the overview and the password (#685), the passkeys (#686), the authenticator app and recovery codes (#687), the sessions (#688).
- API keys (shipped): Environment-gated developer API keys (backend + portal UI), governed by the same environment-aware authorization policy rather than a standalone flag.

---

# Design records

URL: https://docs.qauth.dev/reference/records/

export const adr009DriftRecheckHref = `${findRecord('adr/009-wallet-account-resolution').route}#drift-re-check-2026-07-26`;
export const eudiDriftLogHref = `${GITHUB_REPO_BLOB_BASE}/docs/eudi-regulatory-drift-log.md`;
export const specPinLogHref = `${GITHUB_REPO_BLOB_BASE}/docs/spec-pin-log.md`;
export const oidfRunbookHref = `${GITHUB_REPO_BLOB_BASE}/docs/oidf-op-certification-runbook.md`;
export const walletInteropHref = `${GITHUB_REPO_BLOB_BASE}/docs/wallet-interop-manual-validation.md`;

{/* NOTE TO THE NEXT EDITOR — read before changing how a record link below is written. Every link to a record is built from `RECORDS`/`findRecord` as a JSX-computed href (curly-brace expression), never as ordinary static Markdown-link or quoted-HTML-attribute syntax. That is deliberate; do not simplify it to the ordinary literal form. */}

{/* Reason: the per-record pages are routes generated outside the `docs` collection (`src/pages/reference/records/[...slug].astro`), so `link-resolution.ts`'s `routedPages` — built only from a walk of `src/content/docs` — has no entry for them. A link written in the ordinary literal form would be reported broken by that guard even when the route is real, because the guard cannot find the route in its index. */}

{/* This is NOT the same thing as `reference/status.mdx`'s `.map()` calls, which build plain-text table cells, never a link target — that precedent covers "render a list from data," not "build a link the guard can't see." This file introduces the second pattern; it does not reuse a solved one. */}

{/* Two consequences follow, and both matter to whoever edits this file next. First: the guard cannot verify these links are correct — only that they are JSX it does not parse, so it stays silent either way. Correctness instead rests on a structural guarantee — `RECORDS.adr[i].route` and the remark link rewriter's `recordRouteForRepoPath` both go through `routeForRecordId` in `lib/records.ts`, so they cannot independently drift apart. That guarantee is real, but it is not guard coverage: nothing here would fail CI if it were ever wrong. */}

{/* Second, and the trap is two-sided: add a new record link in the ordinary literal form and the link-resolution guard reports a false positive (broken link) even though the route is real; add it as a computed href instead — matching this file — and a genuinely wrong link (typo'd id, stale route) stays invisible to every guard forever, with no test short of a human clicking it. There is no move here that both satisfies the guard and gets guard coverage; pick the computed form deliberately, not because it's quieter. */}

QAuth's architecture decision records (ADRs) and its post-quantum security review live at
`docs/adr/` and `docs/security/` in the repository, not under this site's own content tree. They
are cited by `file:line` from code comments and by path from dozens of closed issues and pull
requests, so they stay exactly where those references expect them — this page reads them in
place and links to the rendered result.

## How to read them

Unlike every other page on this site, these records carry **no frontmatter and never will**.
They are dated historical documents, not living docs pages: an ADR's job is to record what was
decided and why, as of the date at its top, not to stay a present-tense description of the
system forever. When reality has moved on, the convention this project uses is a **dated
blockquote note added to the top of the original file** — never a silent rewrite — so the
original decision and every correction to it both stay on the record. Expect to see several such
notes stacked in the ADRs below; read them in order, they are the changelog.

Because these pages are historical rather than present-tense, they intentionally sit outside this
site's own drift guards (`apps/docs-site/src/invariants/`), which assert that content matches the
tree _today_. An ADR correctly saying a feature was "deferred" in March is not drift; a living
docs page saying the same thing about a feature that has since shipped is. Keeping the records
collection physically outside `src/content/docs` is what makes that distinction hold — see the
Task 10 report for how this was verified.

## Architecture Decision Records

<ul>
  {RECORDS.adr.map((record) => (
    <li key={record.id}>
      <a href={record.route}>{record.title}</a>
    </li>
  ))}
</ul>

### ADR-009 is partially superseded

`docs/adr/README.md` records that CIR (EU) 2026/1730 and 2026/1731 — published 22 July 2026, in
force 11 August 2026 — superseded part of ADR-009's findings. No Decision in ADR-009 has changed;
one item is flagged as needing a human call. Read the dated re-check inside the ADR itself:

<a href={adr009DriftRecheckHref}>ADR-009 § Drift re-check (2026-07-26)</a>. ADR-009 actually carries
two "Drift re-check" sections — this one, and an earlier 2026-07-20 pass it explicitly supersedes —
cross-linked to each other inside the ADR; read the one linked here first, it points to the other.

## Security reviews

<ul>
  {RECORDS.security.map((record) => (
    <li key={record.id}>
      <a href={record.route}>{record.title}</a>
    </li>
  ))}
</ul>

### The PQC review's core premise is superseded

The PQC hybrid-signing security review's original scope statement said hybrid issuance "is not
wired into live routes yet." That stopped being true after #275 wired
`apps/auth-server/src/app/app.ts:571`'s `hybridSigningEnabled: true` into the JWT plugin
whenever `HYBRID_SIGNING_ENABLED` is set — an operator flipping that flag now DOES depend on this
code at runtime. A dated note at the top of the review records this; the review's actual findings
and verdict are unaffected, only that one scope claim is superseded. Read the note in the review
itself, not just here — it says exactly what changed and why the rest still holds.

## What this page does not render

Four more design records live at `docs/` root, outside both `docs/adr/` and `docs/security/`, and
are linked out to rather than rendered on this site:

<ul>
  <li>
    <a href={eudiDriftLogHref}>EUDI Regulatory Drift Log</a> — a living log of EU regulatory changes
    affecting the wallet-federation design (ADR-004, ADR-009), updated as new implementing
    regulations publish. Its whole purpose is to be read as a continuously-appended tracker rather
    than a point-in-time decision, which is a different genre from the ADRs and security review this
    page indexes.
  </li>
  <li>
    <a href={specPinLogHref}>Specification Pin Log</a> — what every moving specification is pinned
    to, on what basis, and when it is next due for re-verification. Sibling of the EUDI log above,
    and the home of the quarterly re-pin pass ADR-007 mandates. Same genre as that log: a ledger
    appended to over time, not a closed-form decision.
  </li>
  <li>
    <a href={oidfRunbookHref}>OIDF OP Certification Runbook</a> — an operational checklist, not a
    decision record.
  </li>
  <li>
    <a href={walletInteropHref}>Wallet Interop Manual Validation</a> — the manual procedure for the
    real-wallet interoperability pass (#376), and the place findings get recorded. Same genre as the
    runbook above: a procedure to run and append to, not a closed-form decision.
  </li>
</ul>

Rendering them here would need widening the `records` collection's `glob()` pattern in
`content.config.ts` beyond `docs/adr/` and `docs/security/`, which Task 10 did not do — these
files are actively-changing logs, not the kind of dated, closed-form record the guard question
this page exists to answer is about. A GitHub link is also simply correct for them today: unlike
the ADRs' and security review's own internal cross-links (rewritten to site routes by this
project's remark plugin), nothing in this docs-site build machinery rewrites links to these files
into working site routes, so a link straight to GitHub is the one that actually resolves.

---

# API conventions

URL: https://docs.qauth.dev/reference/api-conventions/

QAuth has three API families: admin, account and developer
([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/), Decision 7).
Every route of the three follows the rules on this page. The rules are part of the 1.0 stability
contract ([ADR-018 §5](/reference/records/adr/018-1-0-scope-and-stability/)), so they are fixed
before the families' first route. A test enforces them over the generated OpenAPI document
([Enforcement](#enforcement)).

The Interaction API (`/interaction/v1-rc.0`) reuses these rules, with the differences its own
page lists: its problem documents carry no prose, and its steps keep the names of the step grammar
([Interaction API](/reference/interaction-api/)). The OAuth protocol endpoints do not: they keep
the shapes their specifications define ([Errors](#errors)). The error format of [Errors](#errors)
is not limited to the families: every route that is not an OAuth protocol endpoint answers it.

## The three families

| Family    | Caller    | Path prefix          | Audience                          |
| --------- | --------- | -------------------- | --------------------------------- |
| admin     | Operator  | `/admin/v1-rc.0`     | `urn:qauth:aud:admin:v1-rc.0`     |
| account   | End user  | `/account/v1-rc.0`   | `urn:qauth:aud:account:v1-rc.0`   |
| developer | Developer | `/developer/v1-rc.0` | `urn:qauth:aud:developer:v1-rc.0` |

- The major version is in the path. Until QAuth 1.0.0 it is a release candidate, `v1-rc.<M>`, and
  nothing about it is promised ([Release candidates](#release-candidates)). A new major version is
  served under its own prefix, such as `/admin/v2`, beside the old one ([Versioning](#versioning)).
- Each token carries one audience, and a family accepts only its own. The audience identifiers
  carry a version, as ADR-018 §5 requires for every QAuth-defined identifier, and it is the same
  release candidate as the path's.
- The admin API's scopes are `qauth:admin:read`, `qauth:admin:write` and `qauth:admin:security`,
  in QAuth's reserved `qauth:` scope namespace, intersected with the caller's admin roles. The
  [admin permissions](/reference/admin-permissions/) page lists them with every permission and the
  built-in roles.
- The account and developer APIs have one scope per operation class, in the same namespace:
  `qauth:account:read` and `qauth:account:write`, `qauth:developer:read` and
  `qauth:developer:write` (#933). An operation needs its family's scope of its `x-qauth-class`, so
  a developer token with only the read scope lists and reads clients, API keys and consents, and
  gets 403 on create, update, delete, secret regeneration, API keys and consent revocation. The two
  scopes are independent, as the admin scopes are: the write scope does not reach a read. No role
  is intersected with them, since the family's operations act on the token's own user, its account
  or the clients it owns ([Family tokens](#family-tokens)). Only an operator can give a client a
  family audience (`urn:qauth:aud:` is reserved, below), and the token endpoint issues a family's
  scopes only to such a client ([Issuing a family audience](#issuing-a-family-audience)). The
  developer portal's token carries both developer scopes.

### Family tokens

Every family route is guarded by `requireFamilyToken(family, options)` in
`apps/auth-server/src/app/helpers/family-token.ts`. A token passes when:

- its signature verifies and it has not expired or been revoked, as on every bearer-protected
  route;
- its protected header carries `typ: at+jwt` (RFC 9068 §2.1), whatever
  `requireAccessTokenTyp` is set to;
- its `iss` is one the family accepts. The check is a hook, `IssuerResolver`. By default it
  accepts only the token issuer of the request's realm (ADR-019 Decision 1): `JWT_ISSUER` as
  written for the realm whose issuer it is, and the realm's own issuer for any other realm. The
  admin family's hook accepts the issuer of an enabled realm, and only a token that verifies with
  that realm's keys ([Admin authority](#admin-authority));
- it carries `sub`, `exp` and `jti`, with `sub` and `jti` non-empty strings;
- its `aud` holds exactly one value, the family's audience. A token with several audiences is
  refused even when one of them is the family's;
- on the developer and admin families, it carries no `act` claim. A delegated token (RFC 8693)
  never manages a developer's clients, and never stands for an admin's passkey sign-in: automation
  reaches the admin API as a service account. The account family accepts one, and an account route
  that changes a credential, an identifier, the contact address or a linked account, or deletes the
  account, refuses it itself (ADR-019 Decision 7);
- its subject is one the route admits (the required `subjects` option: `user`, `client` or both)
  and is active in the realm of the request (ADR-019 Decision 1). A `client_credentials` token,
  whose `sub` is its own `client_id`, must name a client of that realm that is enabled and not
  suspended; any other token must name a user of that realm who is enabled;
- it carries every scope the route lists. An account or developer route lists its family's scope
  of its class (`familyOperation`, and `accountOperation` on the account API, which also applies
  the contract's rules), so the scope the guard checks and the `x-qauth-class` and
  `x-qauth-permission` the document shows are one value.

A family audience reads the same in every realm. Tokens are signed per realm (#491): a token
verifies only with the keys of the request's realm and, under the default issuer rule, only when
its `iss` is that realm's issuer, so a realm admits its own tokens and refuses every other
realm's. The subject is checked
in the request's realm as well, whatever issuer rule a family uses: a user's token is refused in
every realm but the user's, and a `client_credentials` token in every realm whose client of that
`client_id` is missing, disabled or suspended.

A request that presents no token is refused with 401 `unauthorized` and a challenge that names no
error, `WWW-Authenticate: Bearer realm="OAuth"`. A token that fails, its subject included, is
refused with 401 and `WWW-Authenticate: Bearer error="invalid_token"` (`invalid_access_token`, or
`access_token_expired`). A token that lacks a scope is refused with 403 `forbidden` and
`WWW-Authenticate: Bearer error="insufficient_scope"`, whose `scope` names the scopes the route
needs, as on every route a wider token would let through. All three follow RFC 6750 §3.1, and the
body is a problem document with the code named in parentheses. A request under the `DPoP` scheme
gets a `DPoP` challenge instead (RFC 9449 §7.1). A family route therefore lists 401 in its
`x-qauth-errors`, and 403 when it requires a scope.

What a route does for its subject beyond that, such as reading the user's row again or checking a
role, is its own.

### Admin authority

An admin route decides what the token may do to the realm it names with
`resolveAdminAuthority({ iss, sub, scopes, targetRealmId })` in
`apps/auth-server/src/app/helpers/admin-authority.ts`
([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/), Decision 7). It
reads the admin grants and roles from the database on every request, never from token claims, so
a disabled account, a revoked grant or a disabled role counts from the next request, with the
same token.

1. The realm whose issuer is the token's `iss` must be enabled. Otherwise the token is refused
   with 401.
2. The subject must be an enabled account of that realm. Otherwise the token is refused with 401.
3. A token of the operator realm needs a live grant whose target is the requested realm or every
   realm.
4. Any other token is realm-local: the requested realm must be the issuer's own, with a live grant
   on it. The operator realm is never its target.
5. The permissions of the matching grants' roles, intersected with the token's scopes, are the
   permissions the request may use. The operation's own check answers 403 `forbidden` when the one
   it needs is missing.

A realm outside the caller's grants answers 404 `not_found`, exactly as a realm that does not
exist, so the answer never confirms that a realm exists.

Admin grants and custom admin roles live in `admin_grants` and `admin_roles`. A grant names a
built-in role or a custom role, and one realm or every realm. Only an account of the operator realm
holds a grant on every realm or on another realm than its own; the repository and the database
trigger `admin_grants_realm_rule` both refuse anything else. A custom role is defined in one realm
and granted only to that realm's accounts or for that realm. A grant is written live, at the
database's time (the trigger `admin_grants_insert_live`), revoked, never changed (the trigger
`admin_grants_revoke_only`), and a role is disabled, never deleted while a grant names it. A grant
is looked up by its id, or by its account's id, only within a realm: the realm it covers, or its
account's realm. It is revoked only from its account's realm, so a realm sees an operator-realm
admin's grant on it but cannot revoke it. A realm's operator flag, on which the rule rests, is written only by the realms
repository's `setOperator`, which the default realm's boot step calls.

Until each realm has its own issuer, the realm `JWT_ISSUER` names is the only realm whose tokens an
admin route accepts: `RealmIssuerDirectory` maps an issuer to its realm, and `IssuerKeyResolver`
verifies a token with that realm's keys, and both know only the deployment's issuer and today's
signing key.

### The admin listener

The admin API runs on its own internal listener, never on the public one
([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/), Decisions 7 and
8). A process that holds the `admin` service role serves it on `ADMIN_API_HOST` and
`ADMIN_API_PORT`, `127.0.0.1`, port `3002`, by default, while `ADMIN_API_ENABLED` is on
([Configuration](/operate/configuration/)). It is off by default. Where it runs, `ADMIN_API_BASE_URL`, the URL clients address the admin API at, and
`DPOP_ENABLED=true` are required: every admin call carries a DPoP-bound admin token
([The DPoP check](#the-dpop-check-of-the-admin-listener)). The public listener
answers 404 `not_found` for every admin path, except a CORS preflight (`OPTIONS`), which it
answers as on any other path, naming nothing of the admin API. The admin OpenAPI document is
served on the admin listener only, at `/admin/v1-rc.0/openapi.json`, without a token: it
describes the operations and holds no realm data.

The listener grants nothing for a caller's network position: every other call, from loopback too,
needs an admin token. It never routes by host either. Every admin path names the realm it acts on,
`/admin/v1-rc.0/realms/{realmId}/...`, and the listener refuses to boot a route that does not.

Every admin route runs behind the same stages, in this order
(`apps/auth-server/src/app/admin/pipeline.ts`):

1. The request id, which the server makes for every call, never takes from the caller, echoes in
   the response and carries as `trace_id`.
2. The token guard ([Family tokens](#family-tokens)). The realm whose keys verify the token is
   the one its `iss` names. A call without a valid admin token gets 401 here, before any realm
   is read, and every such refusal reads the same, so the answer says nothing about realms.
3. The DPoP check (#520), inside the token guard, before the per-subject ceiling
   ([below](#the-dpop-check-of-the-admin-listener)).
4. The realm, from the path.
5. The authority from grants and scopes ([Admin authority](#admin-authority)). A realm outside
   the caller's grants answers 404 `not_found`.
6. The classification and the permission check ([Security operations](/reference/security-operations/)).
   A caller without a permission the request needs gets 403 `forbidden`, with an
   `insufficient_scope` challenge when the token's scopes, not the caller's roles, are what is
   missing.
7. The approval gate. A request classified `security` runs only with the approval its
   `QAuth-Approval` header names, filed for exactly this request ([Approvals](#approvals)). Every
   other one answers 403 `approval_required` and never runs.
8. The handler, inside one database transaction. The transaction first consumes the approval
   stage 7 checked; a call that finds it used meanwhile answers 403 `approval_required`. The
   handler answers by returning its body: a handler
   that sends or hijacks the reply itself fails, so no answer leaves before its change commits.
   The body is serialized inside the transaction, so one its response schema refuses fails the
   call and its change rolls back.
9. The audit row, in the admin audit log of the realm the request acts on.
10. The error, as a problem document.

A route's own `onRequest`, `preParsing` and `preValidation` hooks would run before stages 6 and
7, so the listener refuses to boot an admin route that has one, in its options or added by its
module: use a `preHandler` hook or the handler. A `preHandler` refuses by throwing, never by
sending the reply; one that sends or hijacks it fails the call.

The listener also has request ceilings of its own, 100 calls a minute each, whatever
`RATE_LIMIT_MAX` and `RATE_LIMIT_WINDOW` say for the public listener, and answers 429
`too_many_requests` beyond them. `RATE_LIMIT_ENABLED` only chooses where the counts live: in
Redis, or in memory while it is off.

- Per client address, the calls the token guard refuses. Past that count, a call from the address
  that presents no token is refused before the token guard, and one whose token the guard refuses
  answers 429. A call that presents a token under the `DPoP` scheme always reaches the token guard,
  so a valid token is never held back by the refusals of others from the same address; a token
  under the `Bearer` scheme is no admin credential, and is refused before the guard there.
- Per token subject, every call, right after the token guard.
- Per client address, every call to the OpenAPI document, which needs no token, in a count of its
  own.

The address is the TCP peer: the listener trusts no proxy, whatever `TRUST_PROXY` names for the
public listener.

#### The DPoP check of the admin listener

An admin token is bound to a DPoP key ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)): the
listener takes it only as `Authorization: DPoP <token>`, with a `DPoP` header holding a proof made
with the key its `cnf.jkt` names (ADR-019 Decision 7, ADR-014 §3). The proof must be for the
call's method (`htm`) and for `ADMIN_API_BASE_URL` followed by the call's path (`htu`), without
query or fragment, never a URL built from the request's `Host`; its `iat` within 60 seconds of the
server's clock; its `ath` the hash of the token; and its `jti` unused. A used proof is kept in
Redis for 181 seconds, in the store of the public listener's proofs, so a proof passes once
wherever it is shown. With Redis unavailable every proof is refused.

A token under the `Bearer` scheme, a token bound to no key, or a proof under another key is
refused as a token: 401 `invalid_access_token`, `WWW-Authenticate: DPoP error="invalid_token"`.
Any other refused proof, a missing one included, answers 401 `invalid_dpop_proof`,
`WWW-Authenticate: DPoP error="invalid_dpop_proof"`. Every challenge of the listener uses the
`DPoP` scheme and names the proof algorithms in `algs`. The proof is checked before the
per-subject ceiling, so a stolen token shown without its key counts against the caller's address,
never against the admin's own ceiling.

The token endpoint issues the admin audience, or a `qauth:admin:*` scope, only with a DPoP proof
([OAuth flow](/integrate/oauth-flow/)). An admin token lives at most the realm's
`tokens.adminAccessTokenLifespanSeconds` (600 seconds by default), and never more than 900 seconds.
The admin OpenAPI document names its scheme `dpopAuth`. When the server shuts down, the listener takes no new call, lets each call in
flight finish for up to 8 seconds, closes the connections still open, waits up to 1.5 seconds
more for the audit rows of their calls, and closes before the database.

**Audit rows.** Every call that reaches a realm within the caller's grants writes exactly one row
to that realm's chain, reads included. A call that succeeds writes `succeeded` in the
handler's transaction, with the change the handler recorded, its secret fields masked: the row
and the change commit together, or neither does, and the answer is serialized before they do, so
the answer and the row always agree. A call refused after that point, such as one
without the permission or the approval, or whose body does not parse, writes `denied`; one that
fails on the server, its handler or commit included, writes `failed`. Both are written in a new
transaction, with no diff. A `denied` or `failed` row that cannot be written is logged, not
retried, and the call has no row; its answer is the same refusal or failure. A
call refused before it reaches a realm within its grants writes no row: one without a valid
token, one over a request limit, and one that names a realm outside its grants, which is logged
with the caller instead, so a stranger cannot add rows to another realm's chain.

### Approvals

A security operation runs only with a fresh approval bound to that exact request (ADR-019
Decision 7). The approval engine lives in `apps/auth-server/src/app/admin/approvals/`.

1. The client calls the operation and gets 403 `approval_required`.
2. It files an approval: `POST /admin/v1-rc.0/realms/{realmId}/approvals` with the operation's id,
   its path parameters other than `realmId`, its query and its body, and an optional `reason`. The
   answer, 201, is the approval, `pending`, with `approvalUrl`: the approval page, on the auth
   server of the realm the requester's account lives in, built from that realm's row. Its path is
   `/approvals/{realmId}/{approvalId}`, naming the realm the approval acts on, where the page finds
   it: an operator-realm admin's approval for a tenant realm lives in the tenant realm.
3. An approver confirms on that page with a factor, or declines. There is no admin route for it.
   The passkey factor is the only one a deployment will use. Neither it nor the approval page has
   shipped yet, so no code a deployment runs gives an approval; the one factor that exists is for
   tests, and is built only in a test run (`VITEST` set or `NODE_ENV=test`), never under
   `NODE_ENV=production`.
4. The client reads the approval, `GET /admin/v1-rc.0/realms/{realmId}/approvals/{approvalId}`,
   until its `status` is `approved`.
5. It repeats the original call, unchanged, with the header `QAuth-Approval: <approvalId>`. The
   admin pipeline checks the approval and consumes it in the transaction of the operation, so the
   operation runs once with it, under the requester's own authorization at that moment.

**What an approval binds.** The canonical request is the operation id, the method, every path
parameter, the query and the body, each as the operation's route parses it, the realm and the
requester, serialized with the JSON Canonicalization Scheme (RFC 8785). `op_hash` is its SHA-256
with a nonce the server draws when the approval is filed. The gate computes the `op_hash` of the
retried call with the approval's nonce and refuses the call when it differs, so a changed body,
path parameter, query, realm or requester finds no approval; and the challenge an approver's
factor signs is derived from it, so an approval given for one filing approves nothing else.

**What an approval keeps.** The operation's method, path parameters and query, what its approver
is shown (below), `op_hash` and the nonce, never the body, and no hash of the request without the
nonce, which would let anyone with a copy of the table test a guessed body against it. Once the
approval is consumed, cancelled, denied or expired, its nonce is overwritten with random bytes, so
neither its `op_hash` nor the audit log's copy of it can be tested against a guess any more. The
overwrite is a new row version: a dump, replica or WAL archive taken while the approval was open
still holds the old nonce beside `op_hash`, and with both a guessed body can still be tested. For a
secret that residual is closed: a security operation takes a secret only sealed (below), so the
body it binds holds a ciphertext, which no guess reaches, and never a password or a client secret
in the clear. The rest of a body, such as a plain config value, can still be tested against those
copies, and holds nothing secret.

**Secrets in a security operation's request.** A security operation that sets a secret declares
the members of its body that carry one, and each takes a sealed value, `{ "sealed": "v1.…" }`,
never the secret: the admin listener refuses to boot a security operation whose body schema holds
a declared secret member to any other schema. The [Security operations](/reference/security-operations/#operations)
page lists each operation's secret members. The client seals each value first:

1. `POST /admin/v1-rc.0/realms/{realmId}/secrets/seal` (`secrets.seal`) with the operation; the
   member, a JSON Pointer (RFC 6901, `~` written `~0` and `/` written `~1`) into the operation's
   body that the operation declares secret; `params`, the path parameters of the request the value
   is for but `realmId`, as that operation's route parses them; and the value. It needs the write
   permission `secrets.seal`, changes nothing and records no value.
2. The answer holds the value encrypted with the realm's `data_at_rest` key, bound to that
   operation, that member, those path parameters, what the operation's route binds beside them
   (for `plugins.update`, the package and type of the plugin installed under the name), and the
   realm. No response, audit row or log line holds the value.
3. The request carries `{ "sealed": … }` at the member, and is filed, approved and sent as any
   other.

```http
POST /admin/v1-rc.0/realms/{realmId}/secrets/seal
{ "operation": "plugins.update", "member": "/secrets/clientSecret",
  "params": { "plugin": "corp-sso" }, "value": "…" }
→ 200 { "operation": "plugins.update", "member": "/secrets/clientSecret", "sealed": "v1.…" }
```

The operation's handler opens a sealed value only for its own operation, that member, its own
path parameters and the realm: one sealed for another operation, member, resource or realm, or
changed, is refused with 400 `bad_request`. A handler that keeps the secret stores it sealed again under a context of
its own, so the value the approval bound never opens as a stored secret. The operation's renderer
names a secret member and never shows its sealed value; an approval whose renderer shows one is
never filed. The listener cannot tell a secret from a plain string by its schema: the operation
that sets a secret declares it, in its body; a security operation takes no secret in its path or
query.

**What a security operation's route and handler must do.** The admin listener refuses to boot a
security operation's route that cannot be bound this way: it needs a renderer, one method, a Zod
object schema for its path parameters naming every parameter of its URL, and a Zod body schema
under every method that carries a body; and every admin operation has exactly one route. Its
handler reads only the parsed path parameters, query and body, whose schemas are deterministic,
and makes an effect outside the database (a KMS or KEK call, a mail, an outbound request) only
through an outbox written in its transaction or after the commit, since an operation that rolls
back leaves its approval usable. The rules in full are on the
[Security operations](/reference/security-operations/#rules) page.

**Who approves.** A human requester's own fresh step-up is its first approval, and only the
requester gives it. An approval needs that one approval today. The engine already counts a
required second approval only from a different account that holds `approvals.approve` on the
realm; the two-admin rule (#521) will make a second admin mandatory where a realm asks for it, and
add the rest of ADR-019's eligibility rules (the approver held the security scope before the
request, no account or credential change in the 7 days before it, a passkey that is not the
requester's). Service accounts (#522) have no passkey: a human admin will approve in their place.
Until they ship, every admin API caller is a human account.

**Who reads.** Filing (`approvals.create`) and withdrawing (`approvals.cancel`) take the
classification of the operation the approval is for: the caller needs every permission it
declares, and `qauth:admin:security`. Reading (`approvals.get`) needs `approvals.read`, and only
the requester, an account that gave one of its approvals and an account that may still give one
read an approval. Anyone else gets 404 `not_found`, exactly as for an id that does not exist. An
approval's representation holds the operation's path parameters and query, never its body. Its `reason`, `params` and `query` are raw values, not display text; a page shows `display` instead, which is `null` once the approval is no longer open.

**How an approval ends.** It expires 5 minutes after it is filed, a constant. It is `consumed`
once the operation commits on it; an operation that fails or rolls back leaves it `approved`
until then. The requester withdraws it with
`POST /admin/v1-rc.0/realms/{realmId}/approvals/{approvalId}/cancel`, whose `If-Match` names the
version the approval's `ETag` gave (428 without one, 412 for another version, 409 for an approval
that is no longer open). An approver may decline it instead (`denied`). A consumed, expired,
cancelled or denied approval approves nothing. One that expires unused is shown `expired` from
then on; the `approval-expiry` job, every minute on the `admin` role, stores `expired` on it and
overwrites its nonce, which changes its version (so a withdrawal naming the old one answers 412).
No job removes approvals.

**What the approver is shown.** The operation, rendered from the request when the approval is
filed, never from text the requester wrote: every security operation registers a renderer, which
returns typed display data, never HTML, and the admin listener refuses to boot a security
operation without one. The approval stores what it rendered, and that is what every reader is
shown, the approval page included; an operation whose renderer fails on a request files nothing. The
requester's reason is shown apart, as quoted text. Every string is length-capped, and a control,
bidirectional, format or other default-ignorable character in it is shown escaped (`\u{202E}`), as
is a private-use or unassigned code point and every space but U+0020, a
backslash doubled and a combining mark past the third on one character escaped, so the text can
neither hide nor reorder what the page shows, nor pass for an escape. Every reader of an approval
gets its display data, and the approval stores it, so a renderer must never show a secret value of
the request: nothing checks it.

**Audit rows.** Every state change writes the admin audit log of the approval's realm: filing and
withdrawing write the rows of `approvals.create` and `approvals.cancel`; approving and declining
write `approvals.approve` and `approvals.deny`, the first with the credential that approved; the
operation's own `succeeded` row lists the approvals it ran on and carries the approval's
`op_hash` as its request digest. A factor that refuses an approver's answer writes a `denied` row
of `approvals.approve`.

### Issuing a family audience

- A client gets a family audience only when an operator lists it in the client's `audience`. The
  client names it with the RFC 8707 `resource` parameter, at `/oauth/authorize` and at
  `/oauth/token`, and the token's `aud` is that value. A client that does not list it is refused
  with `invalid_target`, on every grant and before any consent screen. A client resolved from a
  Client ID Metadata Document or registered at `/oauth/register` lists none, whatever its row
  holds.
- On a user's grant (authorization code and refresh token) a family audience is issued only when a
  `resource` names it, in the request or bound to the code, so the consent the user gave covers
  it: a client's default audience leaves it out. A `client_credentials` token keeps the client's
  default.
- The admin audience is also issued only to an account whose live admin grants give a
  permission; otherwise the request is refused with `invalid_target`.
- An admin scope (`qauth:admin:read`, `qauth:admin:write`, `qauth:admin:security`) is issued only
  when the client lists the admin audience and the account holds a live admin grant whose role has
  a permission of that scope's class. Otherwise the token is issued without it, and the response's
  `scope` says so (RFC 6749 §3.3); when nothing is left of the scopes asked for, the request is
  refused with `invalid_scope`. Grants are read at every issuance, so the next refresh after a
  revocation no longer carries what the grant gave.
- A scope of the account or developer API (`qauth:account:read`, `qauth:developer:write`, ...) is
  issued only when the client lists that family's audience, and the token names a user. No grant
  is read and no DPoP proof is needed. It is withheld, as above, from a client that does not list
  the audience, from a `client_credentials` token, from an ID-JAG and from a token of the
  jwt-bearer grant. A delegated token of token exchange keeps one its subject token carried when
  the agent's own client lists the family's audience and the scope in its `scopes`, and withholds
  it otherwise: the account API refuses an act-chain token per operation, and the developer API
  refuses every one. The client asks for the scope like any
  other, so it must also hold it in its `scopes`, which only an operator writes: the developer API
  and dynamic registration refuse or drop a `qauth:` scope.
- No other scope of the reserved `qauth:` namespace is ever issued.
- Both are issued only with a DPoP proof (RFC 9449 §5, #520), and the token is bound to its key.
  Without one an admin scope is withheld, as above, and a request for the admin audience, or for
  nothing but admin scopes the grants would give, is refused with `invalid_dpop_proof`, the code
  left unspent; on a process with DPoP off, where no proof could help, with `invalid_target` or
  `invalid_scope`. The refresh token issued beside an admin token is bound to the same key,
  whatever the client, so it refreshes only with a proof of that key. A refresh token bound to no
  key, issued before admin tokens needed a proof, never refreshes into one: the admin audience is
  refused with `invalid_grant`, so the user signs in again, and the admin scopes are withheld and
  dropped from the rotated refresh token, so no later refresh of that family issues them. A
  token for the admin API lives at most 900 seconds, whatever
  `tokens.adminAccessTokenLifespanSeconds` says.
- Neither the admin audience nor an admin scope ever reaches a `client_credentials` token, which
  names no account, an ID-JAG that QAuth mints for another authorization server, or a token of the
  jwt-bearer grant, whose authority comes from another identity provider, or a delegated token of
  token exchange: an admin acts as itself, never through an agent, so a token exchange that names
  the admin audience is refused with `invalid_target` whatever grants the user holds. The token
  `/auth/login` mints leaves the admin audience out, whatever the system client lists.
- `/oauth/authorize` takes the user from the browser session only. Its legacy Bearer path, where
  the developer portal's token stood in for a sign-in with no consent screen, was retired by #524:
  an `Authorization` header there signs no one in.
- A family audience never makes a client authoritative at introspection: QAuth is the only
  resource server for it, so a client introspects a family token only when the token is its own.
- `urn:qauth:aud:` is reserved for the audiences QAuth defines, in any letter case, by the rule the
  reserved `qauth:` scopes follow: self-registration never obtains one. Dynamic registration and a
  Client ID Metadata Document ignore it in an `audience` or `resource` member, and register or
  resolve the client with the rest; neither stores those members. The seed manifest refuses it in
  a `cimd_clients` entry, the one place it would be stored. The rule is `isReservedAudience` in
  `@qauth-labs/shared-validation`.
- The developer portal's token, which `/auth/login` mints for the system client, carries the
  developer audience since #524, and both developer scopes since #933. The system client lists the
  audience from its creation, and one created before is given it the next time a node boots or
  reads it. The deprecated `/api/clients` and `/api/consents`, and `/auth/logout`
  (`assertManagementToken`), accept a system-client token with exactly that audience, and no longer
  one whose audience is the system client's id. Expand, then contract (ADR-018 §5): #509 made every
  node accept the audience before #524 minted it.
- Each deprecated `/api/clients` and `/api/consents` route needs the developer scope of the
  operation it aliases, as that operation does (#933): `qauth:developer:read` to list or read,
  `qauth:developer:write` to create, change, delete, regenerate a secret, mint or revoke an API key,
  or revoke a consent. So does `POST /oauth/register` to attribute the client it registers to the
  developer whose token it carries: `qauth:developer:write`, or 403 `access_denied`. `/auth/logout`,
  which only ends access, needs none.
- For the release of #933 only, the developer API, those routes and that attribution take a
  system-client token that names no scope at all, the portal token a node of the previous release
  mints, as carrying both developer scopes (`isPortalTokenBeforeScopes`). A developer whose portal
  session began before the upgrade, or on a node the rolling upgrade has not reached, keeps working.
  The next release removes it: expand, then contract (ADR-018 §5). The portal's refresh token
  carries no scope, as the system client's row lists none; once that grace is gone a token
  refreshed from it reaches no developer operation, and the portal, which never refreshes, signs
  its developer in again.

### Served routes

| Family    | Routes                                                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| account   | `GET /account/v1-rc.0/consents`, `DELETE /account/v1-rc.0/consents/{consentId}`                                                       |
| developer | `/developer/v1-rc.0/clients` (list, create, read, update, delete, `regenerate-secret`), its `api-keys`, `/developer/v1-rc.0/consents` |

They replace `/api/clients`, `/api/consents` and the cookie-authenticated `/consents`, which stay as
deprecated aliases ([Deprecations](#deprecations)) and share their domain logic, so ownership, the
realm's scope allowlist and the events cannot drift between the two. Each route admits a user's
token only (`subjects: ['user']`), and looks its rows up in the request's realm again after the
guard. A developer's client representation names registered client metadata by its RFC 7591 name
(`client_id`, `client_name`, `redirect_uris`, `grant_types`, `response_types`,
`token_endpoint_auth_method`, `client_secret`); its `scopes` stay a list, which RFC 7591's
space-separated `scope` string is not. The account and developer families share one OpenAPI
document, so their operation ids begin with the family: `developer.clients.list`,
`account.consents.delete`.

The account family's whole contract, with the operations the account console's backend will call,
is published ahead of their handlers on [Account API](/reference/account-api/).

## Names

- JSON members are `camelCase`: `createdAt`, `nextCursor`, `ownerId`.
- A member that carries a registered OAuth or OpenID Connect metadata value keeps its registered
  name: `redirect_uris`, `token_endpoint_auth_method`, `client_id`. The allowed names are listed,
  by IANA registry, in `apps/auth-server/src/app/api-conventions/registered-names.ts`. A name is
  added there only when a representation carries that registered value.
- `trace_id` in a problem document is the one other exception. ADR-019 Decision 7 fixed its name.
- Query and path parameters are `camelCase` too: `limit`, `cursor`, `realmId`.

## Ids and times

- `id`, and every reference to a resource by its id (`realmId`, `ownerId`), is an opaque UUID
  string. A client does not parse it or sort by it.
- A time is an RFC 3339 string in UTC, such as `2026-10-22T09:30:00Z`, never an epoch number. Its
  member name ends in `At`: `createdAt`, `updatedAt`, `expiresAt`.

## Requests and responses

- A request body is `application/json`, except a `PATCH` body ([Updates](#updates)).
- A request with an unknown member is refused with 400 `validation_error`. Request objects are
  closed (`additionalProperties: false`).
- A client ignores response members it does not know and enum values it does not know. Both may be
  added in a minor release.

## Paging

Every list pages by cursor.

| Query parameter | Meaning                                                                                |
| --------------- | -------------------------------------------------------------------------------------- |
| `limit`         | Items per page: an integer from 1 to 200, default 50. A larger value is refused (400). |
| `cursor`        | The `nextCursor` of the previous page. Opaque: a client never builds or changes one.   |

The response is an object with exactly two members:

```json
{
  "items": [{ "id": "0b9f7d4e-5c1a-4f7e-9d2b-3a6c8e1f0a42", "createdAt": "2026-10-22T09:30:00Z" }],
  "nextCursor": "eyJwb3NpdGlvbiI6NDJ9"
}
```

- `nextCursor` is `null` on the last page.
- There is no offset, page number or total. A cursor stays correct while rows are added between two
  calls; an offset does not.
- A cursor that does not parse, or that belongs to another list, is refused with 400
  `invalid_cursor`.
- A `limit` above 200 is refused, not clamped, so a short page is never mistaken for the end of the
  list.
- The cursor-based event API uses the same shape.

The query schema and the response schema are shared: `pageQuerySchema` and `pageSchema(item)` in
`apps/auth-server/src/app/api-conventions/paging.ts`.

## Concurrency

Updates use optimistic concurrency (RFC 9110 §13.1.1).

- A read of one resource returns an `ETag`. It is a strong validator: a client compares it only for
  equality.
- `PATCH` and `PUT` require `If-Match` with that value.
- An update without `If-Match` is refused with 428 `precondition_required` (RFC 6585 §3).
- An update whose `If-Match` is stale is refused with 412 `precondition_failed`. The client reads
  the resource again and retries on the new representation.
- A successful update returns the new representation and its new `ETag`.
- A member that records use rather than configuration, such as a developer client's `lastUsedAt`,
  is left out of the `ETag`: no update writes it, and counting it would make every edit of a client
  in use stale.

## Updates

- `PATCH` takes a JSON Merge Patch (RFC 7396), sent as `application/merge-patch+json`.
- A member set to `null` is removed, or reset to its default. A member left out keeps its value. An
  array is replaced whole.
- The patch itself is a request body: an unknown member is refused with 400 `validation_error`.
  A body sent as another media type is refused with 415 `unsupported_media_type`.
- The merged result is checked against the resource's schema. A result that fails is refused with
  422 `unprocessable_content`, and `errors` names each failing field. A rule of the resource that a
  create checks too answers as the create does, such as a developer client's `invalid_redirect_uri`
  and `invalid_client_metadata` (400), so the same mistake gets the same code on both.

## Errors

Every route that is not an OAuth protocol endpoint answers an error with an RFC 9457 problem details
document, sent as `application/problem+json` (ADR-019 Decision 7, decided 2026-10-11).

```json
{
  "type": "https://docs.qauth.dev/reference/problem-types/#validation-error",
  "title": "Validation error",
  "status": 400,
  "detail": "The request is not valid.",
  "instance": "/developer/v1-rc.0/clients",
  "code": "validation_error",
  "trace_id": "req-7f3a",
  "errors": [{ "pointer": "/limit", "message": "Too big: expected number to be <=200" }]
}
```

| Member     | Meaning                                                                                                                                   |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `type`     | The problem type: a URI under [Problem types](/reference/problem-types/), one per code. Not for branching.                                |
| `title`    | The problem type's title, the same for every occurrence. Not for branching.                                                               |
| `status`   | The HTTP status, repeated.                                                                                                                |
| `detail`   | A sentence for a person, when there is one. Never on a 5xx. Not for branching.                                                            |
| `instance` | The path of the request, without its query.                                                                                               |
| `code`     | A stable, machine-readable name for the error, from [Problem types](/reference/problem-types/).                                           |
| `trace_id` | The id under which QAuth logged the request. An operator finds the failure by it.                                                         |
| `errors`   | Present on a validation failure. One entry per field: `pointer`, an RFC 6901 JSON Pointer into the body or the parameters, and `message`. |

- A client branches on `code` and the status, never on `title` or `detail`, whose wording may
  change.
- A minor release may add codes. A client treats a code it does not know by its HTTP status.
- A 401 or 403 from a bearer-protected route also carries a `WWW-Authenticate` challenge (RFC 6750
  §3; the `DPoP` scheme of RFC 9449 §7.1 when the request used it): `invalid_token` for a token
  that was presented and is not valid (`invalid_access_token`, `access_token_expired`), and no
  error code for a request that presented none (`unauthorized`, RFC 6750 §3.1). A 403 says `insufficient_scope`, with the `scope`, only when a token with that
  scope would be let through; a refusal no scope can lift, such as the developer client limit,
  carries a challenge with no error code, so a client does not go back for a wider token.
- A refused new password (`weak_password`) lists why in `reasons` (`too_short`, `too_long`,
  `blocklisted`, `too_weak`; a minor release may add reasons), and a message for each, then any
  feedback, as `errors` under the pointer `/password`.
- The shared schema is `Problem` (`#/components/schemas/Problem` in the OpenAPI document), and a
  route declares its error responses with `problemResponses(...)` from
  `apps/auth-server/src/app/api-conventions/problem.ts`.

**OAuth protocol endpoints keep the shape their specification defines,** because the clients and
libraries written to that specification parse it. These are the authorization, token, revocation,
introspection, device authorization, dynamic registration and userinfo endpoints, the FiPA
authorization challenge endpoint and the wallet-facing OID4VP endpoints. They answer
`application/json` with `error`, and `error_description` where there is something to say, and no
other member: the token endpoint answers with the `error` of RFC 6749 §5.2, dynamic registration
with that of RFC 7591 §3.2.2, and a bearer-protected endpoint with the `WWW-Authenticate` challenge
of RFC 6750 §3 as well. Their schema in the OpenAPI document is `OAuthError`. Each route says which
format it answers in its `config.errorFormat`: `oauth` on these endpoints, unset (`problem`)
everywhere else.

### Error codes

The codes, with each one's problem type, status and title, are listed on
[Problem types](/reference/problem-types/). They are inside the 1.0 promise: a published code keeps
its meaning within a major version. Each is sent with the status listed for it. An error that has
no code of its own is sent with the code of its status, and a status with no code of its own with
`bad_request` (any 4xx) or `internal_error` (any 5xx), so those two are the only codes sent with
more than one status. Codes are lower-case `snake_case`, like the `error` values of OAuth.

Which code each domain error class of `@qauth-labs/shared-errors` answers, and which OAuth `error`
it answers on a protocol endpoint, is set once, in
`apps/auth-server/src/app/api-conventions/error-classes.ts`, as is the code of each error class a
route or a server library defines itself, such as the Shared Signals Framework transmitter's. A
test fails when a class has no entry, and a test keeps the problem types page equal to
`PROBLEM_CODES` in `apps/auth-server/src/app/api-conventions/problem.ts`.

## OpenAPI

Each family is published as OpenAPI 3.1. Every operation of a family carries:

- an `operationId` of the form `<resource>.<verb>`, unique in the document. The resource may have
  several segments: `realms.get`, `realms.list`, `realms.policies.update`. The verbs are `list`,
  `get`, `create`, `update` (`PATCH`), `replace` (`PUT`) and `delete`; any other verb names an
  action, such as `keys.rotate`;
- a security requirement. No family operation is anonymous;
- the five extensions below;
- error responses that reference the shared `Problem` schema, as `application/problem+json`.

Every other operation of the server lists its error responses too: a route names the statuses it
answers by design in `x-qauth-errors`, and the document adds 421, 429 and 500, which any operation
of a realm may answer (`/health` only 429), each referencing `Problem`, or `OAuthError` on an OAuth
protocol endpoint.

| Extension            | Values                             | Meaning                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-qauth-class`      | `read`, `write`, `security`        | What the operation does. On the admin API it is the strictest class among the operation's permissions, and each permission needs its own class's scope: `qauth:admin:read`, `qauth:admin:write` or `qauth:admin:security`. On the account and developer APIs the operation needs its family's scope of its class, such as `qauth:developer:write`. `security` is used on the admin API only. |
| `x-qauth-permission` | a permission id, or a list of them | The permission the caller needs, such as `realms.read`. A list means the request decides which, for example a policy patch whose fields need `realms.policies.write`, `realms.policies.security` or both.                                                                                                                                                                                    |
| `x-qauth-effects`    | a list of effect tags              | Why an admin operation is a security operation ("defined by effect", ADR-019 Decision 7). Present and not empty exactly on security operations. The tags form a closed list, on [Security operations](/reference/security-operations/).                                                                                                                                                      |
| `x-qauth-two-admin`  | `recommended`                      | Set on every security operation: the admin console recommends a second admin's approval. A realm chooses where it is mandatory; that is realm policy, not part of the document.                                                                                                                                                                                                              |
| `x-qauth-stability`  | `stable`, `experimental`           | Where the operation stands under ADR-018 §5. Required on every operation of the server, not only the families.                                                                                                                                                                                                                                                                               |

On the developer and account APIs the scope an operation needs is its family's scope of its
`x-qauth-class`, `read` or `write` (#933): `clients.read`, `clients.apiKeys.read` and
`consents.read` need `qauth:developer:read`; `clients.write`, `clients.apiKeys.write` and
`consents.write` need `qauth:developer:write`; the account API's `profile.read` needs
`qauth:account:read` and its `password.write` `qauth:account:write`. A token without the scope gets
403 `forbidden` with an `insufficient_scope` challenge that names it.

On the admin API every id in `x-qauth-permission` is a permission of the
[admin catalog](/reference/admin-permissions/), and not a retired one, and `x-qauth-class` is the
strictest class among them (`read` < `write` < `security`). With one permission the operation
needs that class's scope. With a list, the request decides which scopes it needs: a policy patch
that changes only a write field needs `qauth:admin:write`, one that changes a security field needs
`qauth:admin:security`, and one that changes both needs both. The class still names the strictest
case, so a security operation never hides behind a write class and always carries its effects and
the two-admin marker.

Every admin operation is defined once, in the admin operation registry
([Security operations](/reference/security-operations/)), with its class, effects and permissions.
The document's `operationId` must name a registered operation, and its `x-qauth-class`,
`x-qauth-permission` and `x-qauth-effects` must be the registry's; the conventions check fails
otherwise. A route of the admin listener names its operation in its route config (`operation`) and
takes these members from the registry (`operationSchemaExtensions`), and the listener refuses to
boot a route that names no registered operation or whose members differ.

A request-dependent operation classifies each request (`classify`). By effect, a policy change
that lengthens an access-token, refresh-token or session lifetime or the key rotation interval, or
shortens or switches off audit-event retention, is `posture-loosening` and needs the security
class; shortening a lifetime or lengthening retention is a write. A field `classify` has no rule
for fails closed only when `classify` takes a merge patch's changed fields from the body with
`mergePatchLeafPaths(body)` and classifies them with `classifyByField`, which throws on a field its
table does not hold; a request-dependent merge-patch operation uses that pattern, since a
`classify` that reads only the fields it expects never sees the others.

An operation that reads the current state to classify (`loadState`) names the version of what it
read (`stateVersion`), which the route sends quoted as its `ETag`. The listener puts the version on
the classification and answers `428` when the request has no `If-Match` and `412` when it names
another version. The route still declares `If-Match` required in its header schema, so the
OpenAPI document says so; the listener checks for it before validation, so a request without it
gets `428`, not the `400` of a failed schema. The handler's write must be conditional on `classification.stateVersion` (an update that
matches the stored version, `412` when none does), or load, classify and write in one transaction
under `SELECT … FOR UPDATE`: otherwise a change made between the classification and the write runs
under a classification of other state.

A route declares all of it in its schema, and `@fastify/swagger` copies it onto the operation. On
the admin API the operation is defined once in the registry, and the route names it in its config
and spreads the registry's members into its schema:

```ts
// helpers/admin-operations.ts, listed in ADMIN_OPERATIONS
export const REALM_POLICIES_UPDATE = defineOperation({
  id: 'realms.policies.update',
  class: 'security',
  effects: ['credential-path', 'token-content', 'posture-loosening', 'administration'],
  permissions: ['realms.policies.write', 'realms.policies.security'],
  description: "Change a realm's policies.",
  loadState: loadRealmPolicies,
  stateVersion: (policies) => policies.version,
  classify: classifyByField({
    changedFields: (request) => mergePatchLeafPaths(request.body),
    fields: POLICY_FIELDS,
    unchanged: WRITE,
  }),
});

// the route, on the admin listener
fastify.patch(
  '/admin/v1-rc.0/realms/:realmId/policies',
  {
    config: { operation: REALM_POLICIES_UPDATE.id },
    schema: {
      // operationId, x-qauth-class, x-qauth-permission, x-qauth-effects and
      // x-qauth-two-admin, from the registry
      ...operationSchemaExtensions(REALM_POLICIES_UPDATE),
      security: [{ bearerAuth: [] }],
      'x-qauth-stability': 'stable',
      consumes: ['application/merge-patch+json'],
      params: z.object({ realmId: z.uuid() }),
      // Required, so the OpenAPI document says so. A request without it gets
      // 428 from the listener, which checks before validation, not 400.
      headers: z.looseObject({ 'if-match': z.string() }),
      body: realmPoliciesPatchSchema,
      response: { 200: realmSchema, ...problemResponses(400, 401, 403, 404, 412, 422, 428) },
    },
  },
  handler
);
```

## Versioning

Inside a major version, changes are additive only:

- new endpoints;
- new optional request members;
- new response members.

Clients ignore unknown response members and unknown enum values. Requests with unknown members are
refused.

These are breaking changes, and only a new major version makes them:

- removing or renaming a member;
- changing a type;
- tightening validation;
- changing a status code;
- removing an endpoint.

**Deprecation.** A deprecation is announced in a minor release. The operation gets
`deprecated: true` in the OpenAPI document and its responses carry the `Deprecation` header (RFC
9745). A `Sunset` header (RFC 8594) is added once a date exists. Removal comes no sooner than 12
months after the announcement, and only in a new major release (ADR-018 §5).

**Major versions.** `v1` stays served for at least 12 months after `v2` ships, and until the next
major release.

### Release candidates

Before QAuth 1.0.0 nothing is promised, so no path or audience says `v1` yet. Each family is
served under `v1-rc.<M>`, today `v1-rc.0`, and so is the Interaction API. A breaking change before
1.0.0 raises `<M>`, so a prefix never names two contracts. The release that ships 1.0.0 serves
`v1`, and from then on the rules above apply. The same rule covers every QAuth-defined versioned
identifier (ADR-018 §5).

**Experimental operations.** An experimental operation sits behind a switch and carries
`x-qauth-stability: experimental`. It is absent from the published document while the switch is
off, and it may change in a minor release without a deprecation window (ADR-018 §5).

### Deprecations

| Operation                                         | Replacement                                                     | Deprecated in | Sunset |
| ------------------------------------------------- | --------------------------------------------------------------- | ------------- | ------ |
| `GET /api/clients`                                | `GET /developer/v1-rc.0/clients`                                | v0.2 (#524)   | —      |
| `POST /api/clients`                               | `POST /developer/v1-rc.0/clients`                               | v0.2 (#524)   | —      |
| `GET /api/clients/{id}`                           | `GET /developer/v1-rc.0/clients/{clientId}`                     | v0.2 (#524)   | —      |
| `PATCH /api/clients/{id}`                         | `PATCH /developer/v1-rc.0/clients/{clientId}`                   | v0.2 (#524)   | —      |
| `DELETE /api/clients/{id}`                        | `DELETE /developer/v1-rc.0/clients/{clientId}`                  | v0.2 (#524)   | —      |
| `POST /api/clients/{id}/regenerate-secret`        | `POST /developer/v1-rc.0/clients/{clientId}/regenerate-secret`  | v0.2 (#524)   | —      |
| `GET /api/clients/{clientId}/api-keys`            | `GET /developer/v1-rc.0/clients/{clientId}/api-keys`            | v0.2 (#524)   | —      |
| `POST /api/clients/{clientId}/api-keys`           | `POST /developer/v1-rc.0/clients/{clientId}/api-keys`           | v0.2 (#524)   | —      |
| `DELETE /api/clients/{clientId}/api-keys/{keyId}` | `DELETE /developer/v1-rc.0/clients/{clientId}/api-keys/{keyId}` | v0.2 (#524)   | —      |
| `GET /api/consents`                               | `GET /developer/v1-rc.0/consents`                               | v0.2 (#524)   | —      |
| `DELETE /api/consents/{id}`                       | `DELETE /developer/v1-rc.0/consents/{consentId}`                | v0.2 (#524)   | —      |
| `GET /consents`                                   | `GET /account/v1-rc.0/consents`                                 | v0.2 (#524)   | —      |
| `DELETE /consents/{id}`                           | `DELETE /account/v1-rc.0/consents/{consentId}`                  | v0.2 (#524)   | —      |

Each answers as before, in its own shape, and carries `Deprecation: @1793404800` (2026-10-31) and
`Link: <https://docs.qauth.dev/reference/api-conventions/#deprecations>; rel="deprecation"` on every
response, errors included (`api-conventions/deprecation.ts`). No sunset date is set yet: before 1.0
nothing is promised, and the release-candidate cleanup removes these paths once their callers have
moved. The developer portal calls only the replacements; the cookie-authenticated `/consents`
serves the hosted UI until the account console (v0.4) takes its place.

## Enforcement

- `apps/auth-server/src/app/api-conventions/openapi-conventions.ts` checks every operation under a
  family prefix: the `operationId`, the security requirement, the five extensions (an admin
  operation's permissions come from the admin catalog, and its class is the strictest class among
  them), the names, the id and time formats,
  closed request objects, the problem schema on error responses, cursor paging, Merge Patch
  bodies, and `If-Match` with its 412 and 428 answers. Its test runs the check
  over `stable-surface/openapi.json` and `apps/docs-site/public/openapi.json`. CI's stable-surface
  check regenerates both files and fails when they differ from the committed copies, so the check
  reads what the server serves.
- The stable-surface check also fails on an untagged operation, on a switch-gated operation that is
  not `experimental`, and on a break that no approval covers. Its rules are in
  [`stable-surface/README.md`](https://github.com/qauth-labs/qauth/blob/main/stable-surface/README.md).
- The error handler (`apps/auth-server/src/app/plugins/error-handler.ts`) builds the problem
  documents. Its tests, and the assembled-app tests in `error-handler-wiring.test.ts` and
  `error-format.integration.test.ts`, assert both formats on the wire.

---

# Problem types

URL: https://docs.qauth.dev/reference/problem-types/

Every route that is not an OAuth protocol endpoint answers an error with an RFC 9457 problem
details document ([API conventions → Errors](/reference/api-conventions/#errors)). This page lists
the problem types. A document's `type` is this page's address followed by the type's slug:

```text
https://docs.qauth.dev/reference/problem-types/#validation-error
```

Each type has one `code` and one `title`, and each code is sent with the status listed under it,
except two: `bad_request` is also sent with any other 4xx status that has no code of its own (such
as 406), and `internal_error` with any other 5xx (such as 502 or 504). A client branches on `code`
and the status, never on `type`, `title` or `detail`. The codes and the slugs are inside the 1.0
promise ([ADR-018 §5](/reference/records/adr/018-1-0-scope-and-stability/)): each keeps its meaning
within a major version, and a minor release may add types. A client treats a code it does not know
by its HTTP status.

An error the server cannot place more precisely gets the type of its status: `bad-request`,
`unauthorized`, `forbidden`, `not-found` and so on. A 5xx never carries a `detail`; its `trace_id`
finds the failure in the server log.

The list is generated from `PROBLEM_CODES` in
`apps/auth-server/src/app/api-conventions/problem.ts`, and a test fails when the two differ. Which
type each domain error class answers is set once, in
`apps/auth-server/src/app/api-conventions/error-classes.ts`: the classes of
`@qauth-labs/shared-errors`, and those a route or a server library defines itself. The Shared
Signals Framework transmitter's routes answer `bad-request`, `validation-error`, `unauthorized`,
`invalid-access-token`, `access-token-expired`, `forbidden`, `not-found`, `conflict` and
`too-many-requests`. A request with no credentials answers `unauthorized`, whether the route takes
an access token or the session cookie; a token that was presented and refused answers
`invalid-access-token` or `access-token-expired`.

## `bad-request`

**Code** `bad_request` · **Status** 400 · **Title** Bad request

The request is malformed and no more specific code applies. Also sent with any other 4xx status that has no code of its own.

## `validation-error`

**Code** `validation_error` · **Status** 400 · **Title** Validation error

The request does not match the schema of the operation. `errors` names each field.

## `invalid-request`

**Code** `invalid_request` · **Status** 400 · **Title** Invalid request

A parameter of an OAuth or OpenID request is missing, repeated or not valid (RFC 6749 §5.2).

## `invalid-scope`

**Code** `invalid_scope` · **Status** 400 · **Title** Invalid scope

A requested scope is unknown, malformed or not allowed (RFC 6749 §5.2).

## `invalid-grant`

**Code** `invalid_grant` · **Status** 400 · **Title** Invalid grant

An authorization grant or refresh token is not valid, has expired or was issued to another client (RFC 6749 §5.2).

## `invalid-target`

**Code** `invalid_target` · **Status** 400 · **Title** Invalid target

A requested `resource` is not one the grant allows (RFC 8707 §2.2).

## `unauthorized-client`

**Code** `unauthorized_client` · **Status** 400 · **Title** Unauthorized client

The client may not use this grant or this response type (RFC 6749 §5.2).

## `unsupported-grant-type`

**Code** `unsupported_grant_type` · **Status** 400 · **Title** Unsupported grant type

The server does not support the `grant_type` (RFC 6749 §5.2).

## `invalid-client-metadata`

**Code** `invalid_client_metadata` · **Status** 400 · **Title** Invalid client metadata

A client metadata value is not valid or not allowed (RFC 7591 §3.2.2).

## `invalid-redirect-uri`

**Code** `invalid_redirect_uri` · **Status** 400 · **Title** Invalid redirect URI

A redirect URI is not valid or not allowed (RFC 7591 §3.2.2).

## `invalid-cursor`

**Code** `invalid_cursor` · **Status** 400 · **Title** Invalid cursor

The `cursor` does not parse, or it belongs to another list.

## `invalid-verification-token`

**Code** `invalid_verification_token` · **Status** 400 · **Title** Invalid verification token

The email verification token in the request is not valid, or has expired.

## `invalid-csrf-token`

**Code** `invalid_csrf_token` · **Status** 400 · **Title** Invalid CSRF token

A cookie-authenticated request that changes state carries no CSRF token, or not the browser session's.

## `invalid-answer`

**Code** `invalid_answer` · **Status** 400 · **Title** Invalid answer

An Interaction API answer does not match the schema of the step it names, names a step the interaction does not offer, or repeats a field.

## `invalid-current-password`

**Code** `invalid_current_password` · **Status** 400 · **Title** Invalid current password

The current password a password change names is wrong. It counts on the account’s failure ladder, as a failed sign-in does.

## `invalid-code`

**Code** `invalid_code` · **Status** 400 · **Title** Invalid code

A one-time code in the request is wrong, expired or used, such as the first TOTP code of an enrolment or a code mailed to an address. It counts on the account’s failure ladder for that code.

## `unauthorized`

**Code** `unauthorized` · **Status** 401 · **Title** Unauthorized

The request carries no credentials: no access token on a route that takes one, or no valid browser session on a route that takes the session cookie.

## `access-token-expired`

**Code** `access_token_expired` · **Status** 401 · **Title** Access token expired

The access token has expired.

## `invalid-access-token`

**Code** `invalid_access_token` · **Status** 401 · **Title** Invalid access token

The access token is not valid, is not valid for this operation, or names no active user.

## `invalid-credentials`

**Code** `invalid_credentials` · **Status** 401 · **Title** Invalid credentials

The identifier or the credential is wrong. The answer does not say which.

## `invalid-client`

**Code** `invalid_client` · **Status** 401 · **Title** Invalid client

Client authentication failed (RFC 6749 §5.2).

## `invalid-dpop-proof`

**Code** `invalid_dpop_proof` · **Status** 401 · **Title** Invalid DPoP proof

The DPoP proof is missing or not valid for this request (RFC 9449 §7.1).

## `insufficient-user-authentication`

**Code** `insufficient_user_authentication` · **Status** 401 · **Title** Insufficient user authentication

The operation needs fresh authentication and the sign-in behind the token is too old or lacks the account’s strongest bound factor (RFC 9470 §3). `max_age` and the `WWW-Authenticate` challenge say how fresh the next sign-in must be.

## `forbidden`

**Code** `forbidden` · **Status** 403 · **Title** Forbidden

The caller is authenticated but may not perform the operation.

## `approval-required`

**Code** `approval_required` · **Status** 403 · **Title** Approval required

The admin operation is a security operation and runs only with a fresh approval bound to it. The request did not run.

## `delegated-token-refused`

**Code** `delegated_token_refused` · **Status** 403 · **Title** Delegated token refused

The token is an act-chain token (RFC 8693 `act`), and the operation changes a credential, an identifier, the contact address or a linked account, or deletes the account: only the person may do that (ADR-019 Decision 7).

## `disabled-by-realm`

**Code** `disabled_by_realm` · **Status** 403 · **Title** Disabled by realm

The realm’s policy does not let a person do this themselves, such as deleting the account or changing the sign-in address. An admin can.

## `not-found`

**Code** `not_found` · **Status** 404 · **Title** Not found

The resource does not exist, or the caller may not know that it exists.

## `method-not-allowed`

**Code** `method_not_allowed` · **Status** 405 · **Title** Method not allowed

The resource does not support the method.

## `conflict`

**Code** `conflict` · **Status** 409 · **Title** Conflict

The request conflicts with the current state of the resource.

## `already-exists`

**Code** `already_exists` · **Status** 409 · **Title** Already exists

A resource with the same unique value already exists.

## `email-already-verified`

**Code** `email_already_verified` · **Status** 409 · **Title** Email address already verified

The email address is already verified.

## `verification-token-used`

**Code** `verification_token_used` · **Status** 409 · **Title** Verification token used

The email verification token has already been used.

## `last-credential`

**Code** `last_credential` · **Status** 409 · **Title** Last credential

The change would leave the account with no way to sign in, such as removing the only passkey of a passkey-only account.

## `second-factor-required`

**Code** `second_factor_required` · **Status** 409 · **Title** Second factor required

The change would remove the last second factor while the realm’s policy requires one for the account.

## `verification-token-expired`

**Code** `verification_token_expired` · **Status** 410 · **Title** Verification token expired

The email verification token has expired.

## `interaction-expired`

**Code** `interaction_expired` · **Status** 410 · **Title** Interaction expired

The interaction is unknown, expired or finished, the flow cookie does not belong to it, or a finish came after the browser session its sign-in started had ended. The answer does not say which.

## `request-timeout`

**Code** `request_timeout` · **Status** 408 · **Title** Request timeout

The request did not arrive whole within the time the server waits for it.

## `precondition-failed`

**Code** `precondition_failed` · **Status** 412 · **Title** Precondition failed

The `If-Match` value does not match the current `ETag` of the resource.

## `content-too-large`

**Code** `content_too_large` · **Status** 413 · **Title** Content too large

The request body is larger than the server accepts.

## `uri-too-long`

**Code** `uri_too_long` · **Status** 414 · **Title** URI too long

A segment of the request path is longer than the server accepts.

## `unsupported-media-type`

**Code** `unsupported_media_type` · **Status** 415 · **Title** Unsupported media type

The media type of the request body is not one the operation accepts.

## `misdirected-request`

**Code** `misdirected_request` · **Status** 421 · **Title** Misdirected request

The server does not answer for the host the request names, or not for this operation on that host.

## `unprocessable-content`

**Code** `unprocessable_content` · **Status** 422 · **Title** Unprocessable content

The request is well formed, but its content cannot be applied, such as a merge patch whose result fails the schema of the resource.

## `weak-password`

**Code** `weak_password` · **Status** 422 · **Title** Weak password

The new password does not meet the password policy. `reasons` lists why (`too_short`, `too_long`, `blocklisted`, `too_weak`), and `errors` carries a message for each, then any feedback, under `/password`.

## `sandbox-ceiling`

**Code** `sandbox_ceiling` · **Status** 422 · **Title** Sandbox ceiling

The realm is a sandbox realm, whose environment ceiling is staging or production, never development. `errors` names `/posture/maxEnvironmentLaxity`.

## `precondition-required`

**Code** `precondition_required` · **Status** 428 · **Title** Precondition required

The update needs an `If-Match` header.

## `too-many-requests`

**Code** `too_many_requests` · **Status** 429 · **Title** Too many requests

The caller has sent too many requests. `Retry-After`, when present, says when to try again.

## `request-header-fields-too-large`

**Code** `request_header_fields_too_large` · **Status** 431 · **Title** Request header fields too large

The request headers are larger than the server accepts.

## `internal-error`

**Code** `internal_error` · **Status** 500 · **Title** Internal error

The server failed. `trace_id` finds the failure in the server log. Also sent with any other 5xx status that has no code of its own.

## `service-unavailable`

**Code** `service_unavailable` · **Status** 503 · **Title** Service unavailable

The server cannot answer now, for example while a dependency is down or it is too busy. `Retry-After`, when present, says when to try again.

---

# Events

URL: https://docs.qauth.dev/reference/events/

<!-- Generated by `pnpm exec nx run shared-events:schema-export` from libs/shared/events. Do not edit by hand. -->

An event records something that happened in QAuth: a sign-in, a refused token request, a new
client. Events exist so that automation outside QAuth can act on them
([ADR-018 §3](/reference/records/adr/018-1-0-scope-and-stability/)). ADR-018 names four routes
for them: signed webhooks in the Standard Webhooks format, a cursor-based event API, Shared Signals
Framework streams, and OpenTelemetry export. Every route carries the same event, in the envelope
below. The event types and their payload schemas are part of the 1.0 stability contract (ADR-018
§5).

This page is generated from the type registry in `libs/shared/events`, together with the JSON
Schema files it links.

## The envelope

Every event has these members. `type`, `category` and `data` depend on the type; the
others mean the same for every type. A member that does not apply is absent, never `null`.

```json
{
  "id": "0199f2b4-7c3e-7a51-9d2b-3a6c8e1f0a42",
  "type": "urn:qauth:event:user.signed_in:v1-rc.0",
  "time": "2026-10-22T09:30:00.123Z",
  "realm": "0199f2b4-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
  "category": "user",
  "actor": {
    "type": "user",
    "id": "0199f2b4-2b3c-7d4e-9f5a-6b7c8d9e0f1a"
  },
  "subject": {
    "type": "user",
    "id": "0199f2b4-2b3c-7d4e-9f5a-6b7c8d9e0f1a"
  },
  "client": {
    "id": "notes-app"
  },
  "request": {
    "traceId": "req-7f3a",
    "ip": "203.0.113.7",
    "userAgent": "Mozilla/5.0"
  },
  "data": {
    "method": "password"
  }
}
```

| Member                  | Type                                                                | Required | Meaning                                                                                                                                                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | UUID                                                                | yes      | The event id, a UUIDv7. One event keeps one id on every route and every retry, so a receiver drops duplicates by it. It is the `webhook-id` of a webhook and the source of an SSF `jti`.                                                                              |
| `type`                  | string                                                              | yes      | The event type, `urn:qauth:event:<name>:v<N>`, or `:v<N>-rc.<M>` for a release candidate. The registry lists every type.                                                                                                                                              |
| `time`                  | time (RFC 3339, UTC)                                                | yes      | When the event happened, as an RFC 3339 time in UTC. Not when it was delivered.                                                                                                                                                                                       |
| `realm`                 | UUID                                                                | yes      | The id of the realm the event happened in.                                                                                                                                                                                                                            |
| `category`              | one of `user`, `admin`                                              | yes      | `user`: an end user's own activity. `admin`: an administrator's change. Fixed by the type.                                                                                                                                                                            |
| `actor`                 | object                                                              | no       | Who or what caused the event.                                                                                                                                                                                                                                         |
| `actor.type`            | one of `user`, `client`, `system`, `operator_cli`, or a later value | yes      | `user`: a person, signed in. `client`: an OAuth client acting for itself or, with `delegationChain`, as an agent for the subject. `system`: QAuth itself, such as a scheduled job. `operator_cli`: an operator on the server host, through a QAuth command-line tool. |
| `actor.id`              | string                                                              | no       | The actor's identifier: a user id, a client's `client_id`, or the operating-system user for `operator_cli`. Absent for `system`.                                                                                                                                      |
| `actor.delegationChain` | array of string                                                     | no       | The RFC 8693 `act` chain of a delegated request, as `client_id` values: the acting agent first, then each earlier actor. Absent when nothing was delegated.                                                                                                           |
| `subject`               | object                                                              | no       | What the event is about.                                                                                                                                                                                                                                              |
| `subject.type`          | one of `user`, `client`, `api_key`, `ssf_stream`, or a later value  | yes      | What kind of thing the subject is.                                                                                                                                                                                                                                    |
| `subject.id`            | string                                                              | yes      | The subject's identifier: a user id, a client's `client_id`, an API key id or a Shared Signals Framework `stream_id`. It stays valid after the subject is deleted.                                                                                                    |
| `client`                | object                                                              | no       | The OAuth client the request came through.                                                                                                                                                                                                                            |
| `client.id`             | string                                                              | yes      | The client's `client_id`.                                                                                                                                                                                                                                             |
| `request`               | object                                                              | no       | The HTTP request that caused the event.                                                                                                                                                                                                                               |
| `request.traceId`       | string                                                              | no       | The id under which QAuth logged the request: the `trace_id` of a problem document from the same request.                                                                                                                                                              |
| `request.ip`            | IPv4 address or IPv6 address                                        | no       | The end user's IP address, as QAuth derived it from the request. An IPv4-mapped IPv6 address is written in its IPv4 form.                                                                                                                                             |
| `request.userAgent`     | string                                                              | no       | The `User-Agent` header, cut to 1024 characters.                                                                                                                                                                                                                      |
| `data`                  | object                                                              | yes      | The type's own payload. Its schema is the type's.                                                                                                                                                                                                                     |

- The `id` is a UUIDv7, assigned once when the event is recorded. A retry, a redelivery and
  every route repeat it, so a receiver drops duplicates by it. A webhook's `webhook-id` header is
  the event id, and an SSF Security Event Token's `jti` is derived from it.
- The `subject` is a plain id with no database link: it stays valid after the user or the client
  is deleted.
- A webhook body is the envelope. Standard Webhooks recommends a full-stop delimited `type`, a
  `timestamp` and `data`: the short name in the middle of the identifier is the delimited type,
  and `time` is the timestamp.
- The envelope's schema is [envelope.json](/schemas/events/envelope.json).

## Payload rules

These rules hold for every event's `data`. They were written for the audit log
([ADR-011 §8](/reference/records/adr/011-enterprise-managed-authorization/),
[ADR-017 §11](/reference/records/adr/017-first-party-login/)) and apply to events.

1. **Ids, not names or addresses.** `data` names a user, a client or a record by its id. A type
   that needs a name, an email address, a phone number or an IP address declares that field in
   its registry entry. No type registered today does.
2. **Never a secret.** No password, code, OTP, token, key, assertion, signature, cookie, secret,
   or set-up or reset link, in any form. There is no exception. An admin event's diff shows a
   changed resource's own fields; there a secret field holds `***`, never its value.
3. **Hidden identifiers are keyed HMACs.** An identifier that must not be revealed, such as the
   address a failed sign-in typed, is carried as an HMAC under a server-side key, never as the
   value and never as a plain hash.

A scanner enforces the rules. The registry's tests fail when a type's schema declares a field
named like a secret, or like personal data the type has not declared. `parseEvent`, the check a
single event passes before it is stored or sent, applies them again: a field named like a secret,
or a value shaped like a token or a key, refuses the event. The scanner reads names, so a field that holds an
id, a type or a count of such a thing passes when its name ends in `Id`, `Type` or `Count`
(`apiKeyId`, `issuedTokenType`).

## Admin events

An admin event records a change an administrator, a service account or an operator made
([ADR-020 §3](/reference/records/adr/020-ui-surfaces-and-acceptance-criteria/),
[ADR-019 Decision 7](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)). Admin
events are always on: no environment key and no realm setting turns them off. Each is written in
the transaction of the change it records, so the change and its event commit together.

**The diff.** `data.diff` lists what the operation changed, one entry per field:

- `path` names the field, as a JSON Pointer (RFC 6901) into the changed resource, such as
  `/smtp/host`.
- `before` and `after` hold its value. `before` is absent when the field did not exist, and
  `after` when it no longer does; `null` means the field held `null`.
- Only changed fields are listed. A nested object present on both sides is diffed member by
  member. Any other value, an array included, is shown whole.

```json
[
  { "path": "/displayName", "before": "Notes", "after": "Team notes" },
  { "path": "/smtp/password", "before": "***", "after": "***" },
  { "path": "/allowedScopes", "before": ["openid"], "after": ["openid", "profile"] }
]
```

**Masking.** A secret field holds `***` on both sides, whatever its value. A field is secret
when the operation marks it, or when its name holds a secret, marked or not: a password, pass,
PIN, secret, token, key, salt, pepper, cookie, signature, credential, `auth` or connection string,
a key-encryption or data-encryption key (`kek`, `dek`), a set-up, reset or other one-time link,
or a one-time password's link (`totpUri`). A name whose last word only describes the secret is
shown: `accessTokenTtl`, `tokenEndpointAuthMethod`, `signingKeyId`, `jwksUri`, `keyUse`,
`saltRounds`, `authServer`. So is a code or a key that only names something: `countryCode`,
`attrKey`. A changed secret is still listed, so a rotation shows as `***` to `***`. A flag
(`true` or `false`) is never masked.

A value shaped like a secret is masked wherever it sits: a token, a signed or encrypted object, a
PEM block, an `Authorization` header value, a private or symmetric JWK, or a URL that carries a
credential: one with a password (or, over HTTP, a user name), a query or fragment member named like
a secret (`?access_token=`, `?sig=`, `?key=`, `?code=`), an `otpauth://` URI, or a webhook URL
that holds its secret in the path. A public JWK is shown, and a list of keys shows its public keys
with each private one masked. A member name shaped like a secret refuses the event.

The field names in a diff are the resource's own, so the payload scanner reads a diff's values,
not its names, and checks instead that every field named like a secret holds `***`. A diff may
show personal data, such as a contact address an admin changed: admin events are read by the
realm's admins.

**Approvals.** `data.approvals` lists the approvals the operation ran on: both approvals of a
two-admin operation, each with the approver, the passkey credential it was given with, and who
created the approver's account.

**The hash chain.** The event store chains a realm's admin events: each stores the hash of the one
before it, and its own hash is SHA-256 over the chain format's id (`qauth-event-chain/1-rc.0`,
a release candidate until 1.0.0), that hash, the id of the transaction that wrote the event, and
the event's canonical JSON (RFC 8785). A changed event breaks the chain at that event,
and a removed one at the event after it. The chain's hashes are stored beside the event and are
not part of the envelope.

## Versioning

An event type's identifier is `urn:qauth:event:<name>:v<N>`. The `<name>` is its short
name: lower-case `snake_case` segments joined by full stops, the resource first. `<N>` is the
major version of its `data`. Every QAuth-defined identifier carries a version (ADR-018 §5).

**Release candidates.** Until QAuth 1.0.0, every type is a release candidate and its identifier
ends in `-rc.<M>`, as in `urn:qauth:event:user.signed_in:v1-rc.0`. Nothing about a candidate
is promised. A breaking change before 1.0.0 raises `<M>` (`:v1-rc.0` becomes `:v1-rc.1`), so
an identifier never names two different schemas. The release that ships QAuth 1.0.0 drops the
suffix from every type: `:v1` is the version under the stability promise, and the rules below
apply from then on.

Within a major release, the contract changes only by addition:

- a new type, which is a new entry in the registry;
- a new optional member of a type's `data`, or of the envelope;
- a new value of an open set (`x-extensible-enum`, shown on this page as "or a later value").

Anything else is a breaking change: removing or renaming a member, changing its type, making a
member required, adding a required member, or narrowing what a member accepts. A breaking change
makes a new type with the next version, such as `:v2`. QAuth emits both versions for every
event until the deprecation window ends, so a receiver moves at its own pace. The old type is
marked deprecated and names its replacement. It is removed only in a new major release, no sooner
than 12 months after the deprecation (ADR-018 §5).

A receiver ignores members it does not know, and accepts a value of an open set it does not know.
The published schemas leave objects open for that reason. A closed set, such as `category`, does
not grow within a major release.

The stable-surface check compares each schema file with the last release and fails on a breaking
change that no one approved.

## Schemas

Each type has a JSON Schema (draft 2020-12) of its whole event: the envelope, with `type`,
`category` and `data` fixed to the type. They are served under `/schemas/events/`, and each
file's `$id` is its URL. The envelope's own schema accepts an event of any type.

## Event types

| Type                                                                                                    | Category | Severity | Since  |
| ------------------------------------------------------------------------------------------------------- | -------- | -------- | ------ |
| [`urn:qauth:event:user.signed_in:v1-rc.0`](#usersigned_in-v1-rc0)                                       | user     | info     | v0.2.0 |
| [`urn:qauth:event:user.sign_in_failed:v1-rc.0`](#usersign_in_failed-v1-rc0)                             | user     | warning  | v0.2.0 |
| [`urn:qauth:event:user.sign_in_step_passed:v1-rc.0`](#usersign_in_step_passed-v1-rc0)                   | user     | info     | v0.2.0 |
| [`urn:qauth:event:user.password_breach_check_failed:v1-rc.0`](#userpassword_breach_check_failed-v1-rc0) | user     | warning  | v0.2.0 |
| [`urn:qauth:event:user.signed_out:v1-rc.0`](#usersigned_out-v1-rc0)                                     | user     | info     | v0.2.0 |
| [`urn:qauth:event:user.client_session_ended:v1-rc.0`](#userclient_session_ended-v1-rc0)                 | user     | info     | v0.2.0 |
| [`urn:qauth:event:user.sign_out_failed:v1-rc.0`](#usersign_out_failed-v1-rc0)                           | user     | warning  | v0.2.0 |
| [`urn:qauth:event:user.registered:v1-rc.0`](#userregistered-v1-rc0)                                     | user     | info     | v0.2.0 |
| [`urn:qauth:event:user.registration_failed:v1-rc.0`](#userregistration_failed-v1-rc0)                   | user     | warning  | v0.2.0 |
| [`urn:qauth:event:user.password_reset:v1-rc.0`](#userpassword_reset-v1-rc0)                             | user     | info     | v0.2.0 |
| [`urn:qauth:event:user.recovery_code_used:v1-rc.0`](#userrecovery_code_used-v1-rc0)                     | user     | warning  | v0.2.0 |
| [`urn:qauth:event:user.recovery_codes_failed:v1-rc.0`](#userrecovery_codes_failed-v1-rc0)               | user     | critical | v0.2.0 |
| [`urn:qauth:event:user.disabled:v1-rc.0`](#userdisabled-v1-rc0)                                         | admin    | warning  | v0.2.0 |
| [`urn:qauth:event:user.enabled:v1-rc.0`](#userenabled-v1-rc0)                                           | admin    | info     | v0.2.0 |
| [`urn:qauth:event:user.upstream_linked:v1-rc.0`](#userupstream_linked-v1-rc0)                           | user     | info     | v0.2.0 |
| [`urn:qauth:event:user.upstream_unlinked:v1-rc.0`](#userupstream_unlinked-v1-rc0)                       | user     | warning  | v0.2.0 |
| [`urn:qauth:event:user.upstream_link_failed:v1-rc.0`](#userupstream_link_failed-v1-rc0)                 | user     | warning  | v0.2.0 |
| [`urn:qauth:event:user.password_changed:v1-rc.0`](#userpassword_changed-v1-rc0)                         | user     | info     | v0.2.0 |
| [`urn:qauth:event:user.credential_added:v1-rc.0`](#usercredential_added-v1-rc0)                         | user     | info     | v0.2.0 |
| [`urn:qauth:event:user.credential_removed:v1-rc.0`](#usercredential_removed-v1-rc0)                     | user     | warning  | v0.2.0 |
| [`urn:qauth:event:user.passkey_renamed:v1-rc.0`](#userpasskey_renamed-v1-rc0)                           | user     | info     | v0.2.0 |
| [`urn:qauth:event:user.recovery_codes_regenerated:v1-rc.0`](#userrecovery_codes_regenerated-v1-rc0)     | user     | warning  | v0.2.0 |
| [`urn:qauth:event:user.agent_ownership_refused:v1-rc.0`](#useragent_ownership_refused-v1-rc0)           | user     | warning  | v0.2.0 |
| [`urn:qauth:event:user.verified:v1-rc.0`](#userverified-v1-rc0)                                         | admin    | warning  | v0.3.0 |
| [`urn:qauth:event:authorization.completed:v1-rc.0`](#authorizationcompleted-v1-rc0)                     | user     | info     | v0.2.0 |
| [`urn:qauth:event:authorization.failed:v1-rc.0`](#authorizationfailed-v1-rc0)                           | user     | warning  | v0.2.0 |
| [`urn:qauth:event:step_up.required:v1-rc.0`](#step_uprequired-v1-rc0)                                   | user     | info     | v0.2.0 |
| [`urn:qauth:event:step_up.elevated:v1-rc.0`](#step_upelevated-v1-rc0)                                   | user     | info     | v0.2.0 |
| [`urn:qauth:event:consent.granted:v1-rc.0`](#consentgranted-v1-rc0)                                     | user     | info     | v0.2.0 |
| [`urn:qauth:event:consent.administrative:v1-rc.0`](#consentadministrative-v1-rc0)                       | user     | info     | v0.2.0 |
| [`urn:qauth:event:consent.denied:v1-rc.0`](#consentdenied-v1-rc0)                                       | user     | info     | v0.2.0 |
| [`urn:qauth:event:consent.revoked:v1-rc.0`](#consentrevoked-v1-rc0)                                     | user     | info     | v0.2.0 |
| [`urn:qauth:event:token.issued:v1-rc.0`](#tokenissued-v1-rc0)                                           | user     | info     | v0.2.0 |
| [`urn:qauth:event:token.request_failed:v1-rc.0`](#tokenrequest_failed-v1-rc0)                           | user     | warning  | v0.2.0 |
| [`urn:qauth:event:token.family_revoked:v1-rc.0`](#tokenfamily_revoked-v1-rc0)                           | user     | critical | v0.2.0 |
| [`urn:qauth:event:token.revoked:v1-rc.0`](#tokenrevoked-v1-rc0)                                         | user     | info     | v0.2.0 |
| [`urn:qauth:event:token.revocation_failed:v1-rc.0`](#tokenrevocation_failed-v1-rc0)                     | user     | warning  | v0.2.0 |
| [`urn:qauth:event:token.introspected:v1-rc.0`](#tokenintrospected-v1-rc0)                               | user     | info     | v0.2.0 |
| [`urn:qauth:event:token.introspection_failed:v1-rc.0`](#tokenintrospection_failed-v1-rc0)               | user     | warning  | v0.2.0 |
| [`urn:qauth:event:userinfo.served:v1-rc.0`](#userinfoserved-v1-rc0)                                     | user     | info     | v0.2.0 |
| [`urn:qauth:event:userinfo.request_failed:v1-rc.0`](#userinforequest_failed-v1-rc0)                     | user     | warning  | v0.2.0 |
| [`urn:qauth:event:client.created:v1-rc.0`](#clientcreated-v1-rc0)                                       | user     | info     | v0.2.0 |
| [`urn:qauth:event:client.updated:v1-rc.0`](#clientupdated-v1-rc0)                                       | user     | info     | v0.2.0 |
| [`urn:qauth:event:client.deleted:v1-rc.0`](#clientdeleted-v1-rc0)                                       | user     | info     | v0.2.0 |
| [`urn:qauth:event:client.secret_rotated:v1-rc.0`](#clientsecret_rotated-v1-rc0)                         | user     | info     | v0.2.0 |
| [`urn:qauth:event:client.suspended:v1-rc.0`](#clientsuspended-v1-rc0)                                   | admin    | warning  | v0.2.0 |
| [`urn:qauth:event:client.suspension_lifted:v1-rc.0`](#clientsuspension_lifted-v1-rc0)                   | admin    | info     | v0.2.0 |
| [`urn:qauth:event:client.first_party_changed:v1-rc.0`](#clientfirst_party_changed-v1-rc0)               | admin    | warning  | v0.2.0 |
| [`urn:qauth:event:client.verified_domain_changed:v1-rc.0`](#clientverified_domain_changed-v1-rc0)       | admin    | warning  | v0.2.0 |
| [`urn:qauth:event:api_key.created:v1-rc.0`](#api_keycreated-v1-rc0)                                     | user     | info     | v0.2.0 |
| [`urn:qauth:event:api_key.revoked:v1-rc.0`](#api_keyrevoked-v1-rc0)                                     | user     | info     | v0.2.0 |
| [`urn:qauth:event:wallet.linked:v1-rc.0`](#walletlinked-v1-rc0)                                         | user     | info     | v0.2.0 |
| [`urn:qauth:event:wallet.link_failed:v1-rc.0`](#walletlink_failed-v1-rc0)                               | user     | warning  | v0.2.0 |
| [`urn:qauth:event:wallet.presentation_received:v1-rc.0`](#walletpresentation_received-v1-rc0)           | user     | info     | v0.2.0 |
| [`urn:qauth:event:interaction.created:v1-rc.0`](#interactioncreated-v1-rc0)                             | user     | info     | v0.2.0 |
| [`urn:qauth:event:interaction.answered:v1-rc.0`](#interactionanswered-v1-rc0)                           | user     | info     | v0.2.0 |
| [`urn:qauth:event:interaction.cancelled:v1-rc.0`](#interactioncancelled-v1-rc0)                         | user     | info     | v0.2.0 |
| [`urn:qauth:event:interaction.expired:v1-rc.0`](#interactionexpired-v1-rc0)                             | user     | info     | v0.2.0 |
| [`urn:qauth:event:request.csrf_rejected:v1-rc.0`](#requestcsrf_rejected-v1-rc0)                         | user     | warning  | v0.2.0 |
| [`urn:qauth:event:request.account_operation_refused:v1-rc.0`](#requestaccount_operation_refused-v1-rc0) | user     | info     | v0.2.0 |
| [`urn:qauth:event:ssf.stream.verification_requested:v1-rc.0`](#ssfstreamverification_requested-v1-rc0)  | user     | info     | v0.2.0 |
| [`urn:qauth:event:key.emergency_retired:v1-rc.0`](#keyemergency_retired-v1-rc0)                         | admin    | critical | v0.2.0 |
| [`urn:qauth:event:admin.change_applied:v1-rc.0`](#adminchange_applied-v1-rc0)                           | admin    | info     | v0.2.0 |

### user.signed_in v1-rc.0

A person signed in: the credential checked out and QAuth started a browser session or issued tokens.

- Identifier: `urn:qauth:event:user.signed_in:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.signed_in.v1-rc.0.json](/schemas/events/user.signed_in.v1-rc.0.json)

| Member            | Type                                                                 | Required | Meaning                                                                                                                                                                                                                                                                                   |
| ----------------- | -------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `method`          | one of `password`, `wallet`, `upstream`, `passkey`, or a later value | yes      | `password`: an identifier and a password. `wallet`: a credential presented from a wallet (OpenID4VP). `upstream`: an upstream identity provider the person signed in through. `passkey`: a passkey whose authenticator verified the user (WebAuthn). The set may grow in a minor release. |
| `verifierProfile` | string                                                               | no       | The verifier profile the wallet presentation was checked under, such as `haip-1.0`.                                                                                                                                                                                                       |

### user.sign_in_failed v1-rc.0

A sign-in was refused: an unknown identifier, a wrong credential, a locked or disabled account.

- Identifier: `urn:qauth:event:user.sign_in_failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.sign_in_failed.v1-rc.0.json](/schemas/events/user.sign_in_failed.v1-rc.0.json)

| Member            | Type                                                                 | Required | Meaning                                                                                                                                                                                                                                                                                   |
| ----------------- | -------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `method`          | one of `password`, `wallet`, `upstream`, `passkey`, or a later value | yes      | `password`: an identifier and a password. `wallet`: a credential presented from a wallet (OpenID4VP). `upstream`: an upstream identity provider the person signed in through. `passkey`: a passkey whose authenticator verified the user (WebAuthn). The set may grow in a minor release. |
| `reason`          | string                                                               | yes      | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release.                                                                                                                                                                                           |
| `identifierHmac`  | string                                                               | no       | A keyed HMAC (HMAC-SHA-256, base64url) of the identifier the person typed, so repeated attempts at one identifier can be correlated without revealing it. Absent when the attempt named a known user, who is then the subject.                                                            |
| `verifierProfile` | string                                                               | no       | The verifier profile the wallet presentation was checked under, such as `haip-1.0`.                                                                                                                                                                                                       |

### user.sign_in_step_passed v1-rc.0

The sign-in engine accepted an answer to one step of a sign-in: the identifier, a solved bot challenge, or a factor that proved who the person is. A refused answer is user.sign_in_failed; the session or the tokens the sign-in leads to are user.signed_in.

- Identifier: `urn:qauth:event:user.sign_in_step_passed:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.sign_in_step_passed.v1-rc.0.json](/schemas/events/user.sign_in_step_passed.v1-rc.0.json)

| Member           | Type   | Required | Meaning                                                                                                                                                                                                                        |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `step`           | string | yes      | The step whose answer was accepted.                                                                                                                                                                                            |
| `identifierHmac` | string | no       | A keyed HMAC (HMAC-SHA-256, base64url) of the identifier the person typed, so repeated attempts at one identifier can be correlated without revealing it. Absent when the attempt named a known user, who is then the subject. |

### user.password_breach_check_failed v1-rc.0

QAuth could not check a password against the realm's breach list (the local list was not loaded, or the range lookup failed or was refused) and took it as not listed: a failed check never blocks a sign-in, a password update or a registration. The subject is the account whose password it was, when one exists.

- Identifier: `urn:qauth:event:user.password_breach_check_failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.password_breach_check_failed.v1-rc.0.json](/schemas/events/user.password_breach_check_failed.v1-rc.0.json)

| Member   | Type   | Required | Meaning                                                                                                                                                             |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `step`   | string | no       | The sign-in step whose password was checked: the password, or a new password. Absent for a registration through `POST /auth/register`.                              |
| `reason` | string | yes      | Why the check failed: `not_configured`, `list_not_loaded`, `lookup_blocked`, `lookup_failed`, `bad_response` or `unavailable`. The set may grow in a minor release. |

### user.signed_out v1-rc.0

A person signed out, and QAuth ended their browser sessions: the one session the relying party named at the end-session endpoint (OpenID Connect RP-Initiated Logout 1.0), one session the person ended on the hosted account page, or every session of the user at `POST /auth/logout` or at "sign out everywhere" on the hosted account page.

- Identifier: `urn:qauth:event:user.signed_out:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.signed_out.v1-rc.0.json](/schemas/events/user.signed_out.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/caep/event-type/session-revoked` ([SSF events](/reference/ssf-events/))

| Member | Type | Required | Meaning                                                                                                                                                                                                          |
| ------ | ---- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sid`  | UUID | no       | The browser session this sign-out ended, when it ended one: the `sid` its ID tokens carry (#549). Absent when the sign-out ended every session of the user, as `POST /auth/logout` and "sign out everywhere" do. |

### user.client_session_ended v1-rc.0

A browser session ended that had served a client with a registered `backchannel_logout_uri`, and QAuth queued that client a logout token (OpenID Connect Back-Channel Logout 1.0). One event per client and session, written in the transaction that ended the session, whatever ended it: a sign-out, an admin, a reset, a retired key, the browser limit or the session lapsing. `client` is the client to notify.

- Identifier: `urn:qauth:event:user.client_session_ended:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.client_session_ended.v1-rc.0.json](/schemas/events/user.client_session_ended.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member   | Type   | Required | Meaning                                                                                         |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `sid`    | UUID   | yes      | The session that ended: the `sid` its ID tokens and the logout token carry.                     |
| `reason` | string | yes      | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release. |

### user.sign_out_failed v1-rc.0

A sign-out request was refused or could not complete.

- Identifier: `urn:qauth:event:user.sign_out_failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.sign_out_failed.v1-rc.0.json](/schemas/events/user.sign_out_failed.v1-rc.0.json)

| Member   | Type   | Required | Meaning                                                                                         |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `reason` | string | yes      | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release. |

### user.registered v1-rc.0

A person created an account.

- Identifier: `urn:qauth:event:user.registered:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.registered.v1-rc.0.json](/schemas/events/user.registered.v1-rc.0.json)

| Member   | Type                                                                 | Required | Meaning                                                                                                                                                                                                                                                                                   |
| -------- | -------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `method` | one of `password`, `wallet`, `upstream`, `passkey`, or a later value | yes      | `password`: an identifier and a password. `wallet`: a credential presented from a wallet (OpenID4VP). `upstream`: an upstream identity provider the person signed in through. `passkey`: a passkey whose authenticator verified the user (WebAuthn). The set may grow in a minor release. |

### user.registration_failed v1-rc.0

An account could not be created, for example because the address is in use.

- Identifier: `urn:qauth:event:user.registration_failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: none: the event never carries one
- Schema: [user.registration_failed.v1-rc.0.json](/schemas/events/user.registration_failed.v1-rc.0.json)

| Member           | Type   | Required | Meaning                                                                                                                                                                                                                        |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reason`         | string | yes      | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release.                                                                                                                                |
| `identifierHmac` | string | no       | A keyed HMAC (HMAC-SHA-256, base64url) of the identifier the person typed, so repeated attempts at one identifier can be correlated without revealing it. Absent when the attempt named a known user, who is then the subject. |

### user.password_reset v1-rc.0

A person reset their account's password: an emailed code proved the mailbox, every other authenticator the account holds proved it too, and a new password replaced the old one. Every refresh token and browser session the account held ends with it, and so does every sign-in in progress for it.

- Identifier: `urn:qauth:event:user.password_reset:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.password_reset.v1-rc.0.json](/schemas/events/user.password_reset.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/caep/event-type/credential-change` ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### user.recovery_code_used v1-rc.0

A person used one of their recovery codes in place of a second factor on the hosted pages: after the password to sign in, or after the code mailed to their address to reset the password. A code works once; it adds no `amr` value to the sign-in, and the person is told by email.

- Identifier: `urn:qauth:event:user.recovery_code_used:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.recovery_code_used.v1-rc.0.json](/schemas/events/user.recovery_code_used.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member      | Type    | Required | Meaning                                                      |
| ----------- | ------- | -------- | ------------------------------------------------------------ |
| `remaining` | integer | yes      | How many of the set are left unused after this one: 0 to 10. |

### user.recovery_codes_failed v1-rc.0

Wrong recovery codes reached 100 in a row for an account, each after a first proof: the right password at sign-in, or the code mailed to the account’s address in a password reset. Someone who holds one of those is guessing its codes. Every further try waits up to 15 minutes; the person is told by email and the operator alerted. Recorded at most once a day per account.

- Identifier: `urn:qauth:event:user.recovery_codes_failed:v1-rc.0`
- Category: `user` · Severity: `critical` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.recovery_codes_failed.v1-rc.0.json](/schemas/events/user.recovery_codes_failed.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### user.disabled v1-rc.0

An operator disabled an account: it can no longer sign in or obtain tokens, and every browser session and token issued to it before now stays refused, also after it is enabled again.

- Identifier: `urn:qauth:event:user.disabled:v1-rc.0`
- Category: `admin` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.disabled.v1-rc.0.json](/schemas/events/user.disabled.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/risc/event-type/account-disabled` ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### user.enabled v1-rc.0

An operator enabled a disabled account again. The person signs in again: what was issued before the account was disabled stays refused.

- Identifier: `urn:qauth:event:user.enabled:v1-rc.0`
- Category: `admin` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.enabled.v1-rc.0.json](/schemas/events/user.enabled.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/risc/event-type/account-enabled` ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### user.upstream_linked v1-rc.0

A person linked an upstream identity to their account: the provider proved the identity, and the person then signed in to the account, with its own factors or through another upstream provider whose identity the account already holds, under its MFA policy, in the same browser and the same interaction. The account can sign in through the provider from now on. The person is told by email at the address of the account’s password; an account with no password, such as one made through a provider, has this record alone.

- Identifier: `urn:qauth:event:user.upstream_linked:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.upstream_linked.v1-rc.0.json](/schemas/events/user.upstream_linked.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member         | Type   | Required | Meaning                                                           |
| -------------- | ------ | -------- | ----------------------------------------------------------------- |
| `provider`     | string | yes      | The upstream identity provider, by its type, such as `oidc_corp`. |
| `credentialId` | UUID   | yes      | The id of the account credential the identity was linked as.      |

### user.upstream_unlinked v1-rc.0

A person removed an upstream identity from their account through the account API, after a fresh sign-in. The account no longer signs in through that provider; the attributes the provider gave stay. The person is told by email.

- Identifier: `urn:qauth:event:user.upstream_unlinked:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.upstream_unlinked.v1-rc.0.json](/schemas/events/user.upstream_unlinked.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member         | Type   | Required | Meaning                                                           |
| -------------- | ------ | -------- | ----------------------------------------------------------------- |
| `provider`     | string | yes      | The upstream identity provider, by its type, such as `oidc_corp`. |
| `credentialId` | UUID   | yes      | The id of the account credential that was removed.                |

### user.upstream_link_failed v1-rc.0

An upstream identity could not be linked. `reason`: `already_linked`, another account holds the identity; `provider_linked`, the account already holds an identity of that provider; `account_unavailable`, the account signed in to is gone or disabled. Nothing was linked. The subject is the account the person signed in to, or the one that holds the identity when nobody has signed in yet.

- Identifier: `urn:qauth:event:user.upstream_link_failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.upstream_link_failed.v1-rc.0.json](/schemas/events/user.upstream_link_failed.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member     | Type   | Required | Meaning                                                                                         |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `provider` | string | yes      | The upstream identity provider, by its type, such as `oidc_corp`.                               |
| `reason`   | string | yes      | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release. |

### user.password_changed v1-rc.0

A person changed their account's password with the current one, after a fresh sign-in with the account's strongest factor, on the hosted account page. The new password met the realm's password policy. Every other browser session and every refresh token of the account ended; the session the change was made in stays. The person is told by email.

- Identifier: `urn:qauth:event:user.password_changed:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.password_changed.v1-rc.0.json](/schemas/events/user.password_changed.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/caep/event-type/credential-change` ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### user.credential_added v1-rc.0

A passkey or an authenticator app (TOTP) was bound to a person’s account, in a step of the hosted pages the person answered: after a sign-in that offered or asked for it, in a recovery that replaced a lost passkey, or from the hosted account page after a fresh sign-in. A passkey an account was registered with is recorded by the registration (`user.registered`).

- Identifier: `urn:qauth:event:user.credential_added:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.credential_added.v1-rc.0.json](/schemas/events/user.credential_added.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member         | Type                                       | Required | Meaning                                                                                                  |
| -------------- | ------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `type`         | one of `passkey`, `totp`, or a later value | yes      | `passkey`: a WebAuthn passkey. `totp`: an authenticator app (TOTP). The set may grow in a minor release. |
| `credentialId` | UUID                                       | yes      | The id of the account credential that was bound.                                                         |

### user.credential_removed v1-rc.0

A person removed a passkey or their authenticator app (TOTP) from their account on the hosted account page, after a fresh sign-in with the account’s strongest factor or with a recovery code in place of a lost one. The account no longer signs in with it.

- Identifier: `urn:qauth:event:user.credential_removed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.credential_removed.v1-rc.0.json](/schemas/events/user.credential_removed.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member         | Type                                       | Required | Meaning                                                                                                  |
| -------------- | ------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `type`         | one of `passkey`, `totp`, or a later value | yes      | `passkey`: a WebAuthn passkey. `totp`: an authenticator app (TOTP). The set may grow in a minor release. |
| `credentialId` | UUID                                       | yes      | The id of the account credential that was removed.                                                       |

### user.passkey_renamed v1-rc.0

A person changed the name they gave one of their passkeys, on the hosted account page. A name is no credential: the passkey signs in as before.

- Identifier: `urn:qauth:event:user.passkey_renamed:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.passkey_renamed.v1-rc.0.json](/schemas/events/user.passkey_renamed.v1-rc.0.json)

| Member         | Type | Required | Meaning                                     |
| -------------- | ---- | -------- | ------------------------------------------- |
| `credentialId` | UUID | yes      | The id of the passkey’s account credential. |

### user.recovery_codes_regenerated v1-rc.0

A person issued a new set of recovery codes on the hosted account page, after a fresh sign-in with the account’s strongest factor: every code of the old set stopped working, and the new codes were shown once. The person is told by email.

- Identifier: `urn:qauth:event:user.recovery_codes_regenerated:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.recovery_codes_regenerated.v1-rc.0.json](/schemas/events/user.recovery_codes_regenerated.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### user.agent_ownership_refused v1-rc.0

QAuth refused to make an account the owner of an agent, because the account is not verified: its primary identity, the credential that created it, is not proved (ADR-015 Decision 8). A password account proves it with the code mailed to its address, a passkey account with a registration that checked user verification, a wallet account with the presentation QAuth verified, and an upstream account with the sign-in that created it while the provider’s verified switch is on. A credential added later never counts, and the setting that makes password sign-in ask for a confirmed address does not change the rule.

- Identifier: `urn:qauth:event:user.agent_ownership_refused:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [user.agent_ownership_refused.v1-rc.0.json](/schemas/events/user.agent_ownership_refused.v1-rc.0.json)

| Member            | Type                                                                                  | Required | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`          | one of `client_registration`, or a later value                                        | yes      | `client_registration`: an RFC 7591 dynamic registration of an agent client (`is_agent: true`) with the account’s developer access token, which would have made the account the client’s owner. The set may grow in a minor release.                                                                                                                                                                                                                               |
| `reason`          | one of `no_primary_identity`, `account_not_verified`, or a later value                | yes      | `no_primary_identity`: the account has no primary credential (it was removed). `account_not_verified`: its primary identity is not proved by its kind’s rule (a password whose mailbox code was never entered, a passkey registered without user verification, an upstream identity whose provider’s verified switch is off or that the realm no longer offers, or a type with no proof); `primaryIdentity` says which kind. The set may grow in a minor release. |
| `primaryIdentity` | one of `password`, `passkey`, `wallet`, `upstream`, `other`, `none`, or a later value | yes      | The kind of the account’s primary identity: `password`, `passkey`, `wallet`, `upstream`, `other`, or `none` when it has none. The set may grow in a minor release.                                                                                                                                                                                                                                                                                                |

### user.verified v1-rc.0

An operator verified an account: from now on it counts as verified for the realm’s verified-account sign-in gate and for owning an agent, whatever its primary identity proves, and an unclaimed account is claimed, so a later mailbox proof by someone else no longer ends it. It attests the account, not an address: the account’s `email_verified` is unchanged, and no token says more about its address than before.

- Identifier: `urn:qauth:event:user.verified:v1-rc.0`
- Category: `admin` · Severity: `warning` · Since: v0.3.0
- Subject: `user`, when known
- Schema: [user.verified.v1-rc.0.json](/schemas/events/user.verified.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member   | Type                                                | Required | Meaning                                                                                                                                                                                                                                                                                                                                                                            |
| -------- | --------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `method` | one of `operator`, `operator_cli`, or a later value | yes      | `operator`: the admin security operation `users.verify`, run with its approval; the actor is the admin account that filed it. `operator_cli`: the `verify-account` command of the migration runner, run on the server host where no admin API is set up; the actor is `operator_cli`, with the operating-system user when the host names one. The set may grow in a minor release. |

### authorization.completed v1-rc.0

The authorization endpoint sent the client back with an authorization response that grants access.

- Identifier: `urn:qauth:event:authorization.completed:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [authorization.completed.v1-rc.0.json](/schemas/events/authorization.completed.v1-rc.0.json)

`data` has no members: the envelope carries the event.

### authorization.failed v1-rc.0

The authorization endpoint refused a request: an unknown client, a redirect URI that is not registered, a scope the client may not have, or a denial.

- Identifier: `urn:qauth:event:authorization.failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [authorization.failed.v1-rc.0.json](/schemas/events/authorization.failed.v1-rc.0.json)

| Member   | Type   | Required | Meaning                                                                                         |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `error`  | string | yes      | The OAuth or OpenID Connect `error` code the request was refused with, such as `invalid_grant`. |
| `reason` | string | no       | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release. |

### step_up.required v1-rc.0

A request needs a fresh sign-in or new consent before it can go on, for example for a dangerous scope (ADR-007 §2).

- Identifier: `urn:qauth:event:step_up.required:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [step_up.required.v1-rc.0.json](/schemas/events/step_up.required.v1-rc.0.json)

| Member            | Type            | Required | Meaning                                                                                         |
| ----------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `reason`          | string          | yes      | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release. |
| `error`           | string          | no       | The OAuth or OpenID Connect `error` code the request was refused with, such as `invalid_grant`. |
| `elevatedScopes`  | array of string | no       | The scopes the request adds to what the user already granted.                                   |
| `dangerousScopes` | array of string | no       | The requested scopes classed as dangerous.                                                      |
| `prompt`          | string          | no       | The OpenID Connect `prompt` value of the request.                                               |
| `maxAge`          | integer         | no       | The `max_age` of the request, in seconds.                                                       |

### step_up.elevated v1-rc.0

After a fresh sign-in, a user granted a client dangerous scopes (ADR-007 §2).

- Identifier: `urn:qauth:event:step_up.elevated:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [step_up.elevated.v1-rc.0.json](/schemas/events/step_up.elevated.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member            | Type                                                 | Required | Meaning                                                                                   |
| ----------------- | ---------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `scopes`          | array of string                                      | yes      | Every scope granted.                                                                      |
| `dangerousScopes` | array of string                                      | yes      | The granted scopes classed as dangerous.                                                  |
| `scopeMode`       | one of `readonly`, `admin`, `exec`, or a later value | no       | The agent scope mode (ADR-007 §2) the request was granted: `readonly`, `admin` or `exec`. |
| `authenticatedAt` | time (RFC 3339, UTC)                                 | no       | When the fresh sign-in happened, as an RFC 3339 time in UTC.                              |

### consent.granted v1-rc.0

A user granted a client the scopes it asked for.

- Identifier: `urn:qauth:event:consent.granted:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [consent.granted.v1-rc.0.json](/schemas/events/consent.granted.v1-rc.0.json)

| Member            | Type            | Required | Meaning                                                             |
| ----------------- | --------------- | -------- | ------------------------------------------------------------------- |
| `scopes`          | array of string | yes      | The scopes granted.                                                 |
| `remembered`      | boolean         | yes      | Whether the user chose to remember the decision for later requests. |
| `dangerousScopes` | array of string | no       | The granted scopes classed as dangerous.                            |

### consent.administrative v1-rc.0

The consent screen was skipped for an operator-flagged first-party client (ADR-017 Decision 9): the client's first-party profile stood for the user's consent to the requested scopes in its allowlist, none of them dangerous. QAuth stores no consent for the user; an authorization code was issued.

- Identifier: `urn:qauth:event:consent.administrative:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [consent.administrative.v1-rc.0.json](/schemas/events/consent.administrative.v1-rc.0.json)

| Member      | Type                                                      | Required | Meaning                                                                                                                                                                         |
| ----------- | --------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `basis`     | one of `web_redirect`, `native_backend`, or a later value | yes      | The first-party profile an operator set on the client (ADR-017 Decision 2), which the waiver rests on: `web_redirect` or `native_backend`. The set may grow in a minor release. |
| `scopes`    | array of string                                           | yes      | The scopes the waiver covered: the requested scopes in the client’s allowlist. A dangerous scope is never among them; it shows the consent screen.                              |
| `resources` | array of string                                           | no       | The RFC 8707 resource indicators of the request, which the code is bound to. Absent when the request named none.                                                                |
| `path`      | one of `/oauth/authorize`, or a later value               | yes      | The endpoint that skipped the screen: `/oauth/authorize`. The set may grow in a minor release.                                                                                  |

### consent.denied v1-rc.0

Consent was not given: the user declined, or the request did not match what the consent screen showed.

- Identifier: `urn:qauth:event:consent.denied:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [consent.denied.v1-rc.0.json](/schemas/events/consent.denied.v1-rc.0.json)

| Member   | Type   | Required | Meaning                                                                                         |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `error`  | string | no       | The OAuth or OpenID Connect `error` code the request was refused with, such as `invalid_grant`. |
| `reason` | string | no       | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release. |

### consent.revoked v1-rc.0

A user withdrew a client's consent. QAuth revoked the refresh tokens the consent covered.

- Identifier: `urn:qauth:event:consent.revoked:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [consent.revoked.v1-rc.0.json](/schemas/events/consent.revoked.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/caep/event-type/token-claims-change` ([SSF events](/reference/ssf-events/))

| Member                | Type    | Required | Meaning                                       |
| --------------------- | ------- | -------- | --------------------------------------------- |
| `consentId`           | UUID    | yes      | The id of the consent that was withdrawn.     |
| `revokedRefreshCount` | integer | no       | How many refresh tokens were revoked with it. |

### token.issued v1-rc.0

The token endpoint issued tokens: for an authorization code, a refresh, client credentials, a token exchange or a JWT bearer assertion.

- Identifier: `urn:qauth:event:token.issued:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [token.issued.v1-rc.0.json](/schemas/events/token.issued.v1-rc.0.json)

| Member            | Type                                                 | Required | Meaning                                                                                                       |
| ----------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `grantType`       | string                                               | yes      | The `grant_type` of the token request, such as `authorization_code`.                                          |
| `scopes`          | array of string                                      | no       | The scopes of the issued access token.                                                                        |
| `audience`        | array of string                                      | no       | The audience of the issued token.                                                                             |
| `resources`       | array of string                                      | no       | The RFC 8707 resource indicators the token is bound to.                                                       |
| `expiresIn`       | integer                                              | no       | The lifetime of the issued access token, in seconds.                                                          |
| `issuedTokenType` | string                                               | no       | The RFC 8693 `issued_token_type` of a token exchange.                                                         |
| `refreshFamilyId` | UUID                                                 | no       | The refresh family the issued refresh token belongs to. Every rotation keeps it.                              |
| `delegationDepth` | integer                                              | no       | How many actors the RFC 8693 `act` chain of the issued token holds.                                           |
| `idJagId`         | string                                               | no       | The `jti` of the identity assertion authorization grant minted or consumed (ADR-011). Never the grant itself. |
| `idJagIssuer`     | string                                               | no       | The issuer of a consumed identity assertion authorization grant (ADR-011).                                    |
| `scopeMode`       | one of `readonly`, `admin`, `exec`, or a later value | no       | The agent scope mode (ADR-007 §2) the request was granted: `readonly`, `admin` or `exec`.                     |

### token.request_failed v1-rc.0

The token endpoint refused a request: failed client authentication, an invalid or replayed grant, a scope or resource outside what was granted.

- Identifier: `urn:qauth:event:token.request_failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [token.request_failed.v1-rc.0.json](/schemas/events/token.request_failed.v1-rc.0.json)

| Member                | Type    | Required | Meaning                                                                                                                                                   |
| --------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `grantType`           | string  | no       | The `grant_type` of the token request, such as `authorization_code`.                                                                                      |
| `error`               | string  | yes      | The OAuth or OpenID Connect `error` code the request was refused with, such as `invalid_grant`.                                                           |
| `reason`              | string  | no       | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release.                                                           |
| `refreshFamilyId`     | UUID    | no       | The refresh family a replayed grant (reason `code_replay` or `refresh_replay`) had issued, which the refusal revoked. Absent when the grant issued none.  |
| `revokedRefreshCount` | integer | no       | How many refresh tokens of that family the refusal revoked; 0 when they were revoked already. Present for the reasons `code_replay` and `refresh_replay`. |

### token.family_revoked v1-rc.0

A replayed grant made QAuth revoke the refresh family it had issued: an authorization code redeemed a second time, or a refresh token presented after it was rotated or revoked. Emitted only when the replay revoked refresh tokens, beside the `token.request_failed` that refused it.

- Identifier: `urn:qauth:event:token.family_revoked:v1-rc.0`
- Category: `user` · Severity: `critical` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [token.family_revoked.v1-rc.0.json](/schemas/events/token.family_revoked.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/caep/event-type/session-revoked` ([SSF events](/reference/ssf-events/))

| Member                | Type                                                     | Required | Meaning                                                                                                                                                                        |
| --------------------- | -------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reason`              | one of `code_replay`, `refresh_replay`, or a later value | yes      | `code_replay`: an authorization code redeemed a second time. `refresh_replay`: a refresh token presented after it was rotated or revoked. The set may grow in a minor release. |
| `refreshFamilyId`     | UUID                                                     | yes      | The refresh family that was revoked.                                                                                                                                           |
| `revokedRefreshCount` | integer                                                  | yes      | How many refresh tokens of the family were revoked, at least 1.                                                                                                                |

### token.revoked v1-rc.0

A client revoked a token at the RFC 7009 revocation endpoint.

- Identifier: `urn:qauth:event:token.revoked:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [token.revoked.v1-rc.0.json](/schemas/events/token.revoked.v1-rc.0.json)
- Security type · SSF: `urn:qauth:secevent:token-revoked:v1-rc.0` ([SSF events](/reference/ssf-events/))

| Member     | Type   | Required | Meaning                                                         |
| ---------- | ------ | -------- | --------------------------------------------------------------- |
| `typeHint` | string | no       | The `token_type_hint` the client sent, such as `refresh_token`. |

### token.revocation_failed v1-rc.0

The revocation endpoint refused a request, for example on failed client authentication.

- Identifier: `urn:qauth:event:token.revocation_failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: none: the event never carries one
- Schema: [token.revocation_failed.v1-rc.0.json](/schemas/events/token.revocation_failed.v1-rc.0.json)

| Member   | Type   | Required | Meaning                                                                                         |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `error`  | string | yes      | The OAuth or OpenID Connect `error` code the request was refused with, such as `invalid_grant`. |
| `reason` | string | no       | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release. |

### token.introspected v1-rc.0

A resource server introspected an active token (RFC 7662).

- Identifier: `urn:qauth:event:token.introspected:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [token.introspected.v1-rc.0.json](/schemas/events/token.introspected.v1-rc.0.json)

| Member          | Type   | Required | Meaning                                               |
| --------------- | ------ | -------- | ----------------------------------------------------- |
| `tokenClientId` | string | no       | The `client_id` the introspected token was issued to. |

### token.introspection_failed v1-rc.0

An introspection request failed: client authentication, or a token that is invalid, expired, revoked or not one the caller may inspect.

- Identifier: `urn:qauth:event:token.introspection_failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [token.introspection_failed.v1-rc.0.json](/schemas/events/token.introspection_failed.v1-rc.0.json)

| Member   | Type   | Required | Meaning                                                                                         |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `error`  | string | yes      | The OAuth or OpenID Connect `error` code the request was refused with, such as `invalid_grant`. |
| `reason` | string | no       | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release. |

### userinfo.served v1-rc.0

The userinfo endpoint returned claims for an access token.

- Identifier: `urn:qauth:event:userinfo.served:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [userinfo.served.v1-rc.0.json](/schemas/events/userinfo.served.v1-rc.0.json)

`data` has no members: the envelope carries the event.

### userinfo.request_failed v1-rc.0

The userinfo endpoint refused a request.

- Identifier: `urn:qauth:event:userinfo.request_failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [userinfo.request_failed.v1-rc.0.json](/schemas/events/userinfo.request_failed.v1-rc.0.json)

| Member   | Type   | Required | Meaning                                                                                         |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `error`  | string | yes      | The OAuth or OpenID Connect `error` code the request was refused with, such as `invalid_grant`. |
| `reason` | string | no       | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release. |

### client.created v1-rc.0

An OAuth client was created: by RFC 7591 dynamic registration, by a developer through the developer API, or by an admin through the admin API.

- Identifier: `urn:qauth:event:client.created:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `client`, when known
- Schema: [client.created.v1-rc.0.json](/schemas/events/client.created.v1-rc.0.json)

| Member         | Type                                                             | Required | Meaning                                                                                                                                                                            |
| -------------- | ---------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `registration` | one of `dynamic`, `developer_api`, `admin_api`, or a later value | yes      | `dynamic`: RFC 7591 dynamic client registration. `developer_api`: a developer created it. `admin_api`: an admin created it, for no developer. The set may grow in a minor release. |
| `isPublic`     | boolean                                                          | yes      | Whether the client is public, with no client authentication.                                                                                                                       |
| `isAgent`      | boolean                                                          | no       | Whether the client registered as an agent (ADR-007 §2).                                                                                                                            |
| `grantTypes`   | array of string                                                  | yes      | The grant types the client may use.                                                                                                                                                |
| `scopes`       | array of string                                                  | no       | The scopes the client may request.                                                                                                                                                 |
| `authMethod`   | string                                                           | no       | How the client authenticates at the token endpoint, such as `private_key_jwt`.                                                                                                     |

### client.updated v1-rc.0

A developer or an admin changed a client's settings.

- Identifier: `urn:qauth:event:client.updated:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `client`, when known
- Schema: [client.updated.v1-rc.0.json](/schemas/events/client.updated.v1-rc.0.json)

| Member   | Type            | Required | Meaning                                                     |
| -------- | --------------- | -------- | ----------------------------------------------------------- |
| `fields` | array of string | yes      | The names of the settings that changed. Never their values. |

### client.deleted v1-rc.0

A developer or an admin deleted a client.

- Identifier: `urn:qauth:event:client.deleted:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `client`, when known
- Schema: [client.deleted.v1-rc.0.json](/schemas/events/client.deleted.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### client.secret_rotated v1-rc.0

A developer replaced a client's secret. The old secret stopped working.

- Identifier: `urn:qauth:event:client.secret_rotated:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `client`, when known
- Schema: [client.secret_rotated.v1-rc.0.json](/schemas/events/client.secret_rotated.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/caep/event-type/credential-change` ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### client.suspended v1-rc.0

An operator or an admin suspended a client: it can no longer obtain tokens until the suspension is lifted.

- Identifier: `urn:qauth:event:client.suspended:v1-rc.0`
- Category: `admin` · Severity: `warning` · Since: v0.2.0
- Subject: `client`, when known
- Schema: [client.suspended.v1-rc.0.json](/schemas/events/client.suspended.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### client.suspension_lifted v1-rc.0

An operator or an admin lifted a client's suspension.

- Identifier: `urn:qauth:event:client.suspension_lifted:v1-rc.0`
- Category: `admin` · Severity: `info` · Since: v0.2.0
- Subject: `client`, when known
- Schema: [client.suspension_lifted.v1-rc.0.json](/schemas/events/client.suspension_lifted.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### client.first_party_changed v1-rc.0

An operator set, changed or removed a client's first-party profile (ADR-017 Decision 2), its policy or its written reason. Removing the profile revoked every refresh token family of the client in the same transaction.

- Identifier: `urn:qauth:event:client.first_party_changed:v1-rc.0`
- Category: `admin` · Severity: `warning` · Since: v0.2.0
- Subject: `client`, when known
- Schema: [client.first_party_changed.v1-rc.0.json](/schemas/events/client.first_party_changed.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member              | Type                                                             | Required | Meaning                                                                                                                                                                                                     |
| ------------------- | ---------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`              | one of `web_redirect`, `native_backend`, or a later value or any | yes      | `web_redirect` or `native_backend`: the profile before the change, or `null` when the client was not first party. The set may grow in a minor release.                                                      |
| `to`                | one of `web_redirect`, `native_backend`, or a later value or any | yes      | The profile after the change, or `null` when it was removed. The set may grow in a minor release.                                                                                                           |
| `flows`             | array of one of `login`, `register`, `reset`, or a later value   | no       | A `native_backend` client's flows after the change: `login`, `register`, `reset`. Absent for any other profile.                                                                                             |
| `pkceRequired`      | boolean                                                          | no       | Whether a `native_backend` client's policy requires PKCE at the authorization challenge endpoint after the change. `false` is a deviation the operator chose for this client. Absent for any other profile. |
| `writtenReason`     | string                                                           | no       | The reason the operator wrote for the profile, as stored with the client. Absent when the profile was removed.                                                                                              |
| `revokedTokenCount` | integer                                                          | yes      | How many refresh tokens the removal revoked: every token of every family of the client that was not already revoked, expired ones included. `0` when the profile was set or changed.                        |

### client.verified_domain_changed v1-rc.0

An operator set, replaced or removed an operator-provisioned client's verified domain (ADR-019 Decision 6), the domain the consent screen and every other screen that names the client show first.

- Identifier: `urn:qauth:event:client.verified_domain_changed:v1-rc.0`
- Category: `admin` · Severity: `warning` · Since: v0.2.0
- Subject: `client`, when known
- Schema: [client.verified_domain_changed.v1-rc.0.json](/schemas/events/client.verified_domain_changed.v1-rc.0.json)
- Security type · SSF: none ([SSF events](/reference/ssf-events/))

| Member | Type          | Required | Meaning                                                                                                                    |
| ------ | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `from` | string or any | yes      | The verified domain before the change, in its stored form (lower case, `xn--` labels), or `null` when the client had none. |
| `to`   | string or any | yes      | The verified domain after the change, in its stored form, or `null` when it was removed.                                   |

### api_key.created v1-rc.0

A developer created an API key for a client.

- Identifier: `urn:qauth:event:api_key.created:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `api_key`, when known
- Schema: [api_key.created.v1-rc.0.json](/schemas/events/api_key.created.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/caep/event-type/credential-change` ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### api_key.revoked v1-rc.0

A developer revoked an API key. It stopped working.

- Identifier: `urn:qauth:event:api_key.revoked:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `api_key`, when known
- Schema: [api_key.revoked.v1-rc.0.json](/schemas/events/api_key.revoked.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/caep/event-type/credential-change` ([SSF events](/reference/ssf-events/))

`data` has no members: the envelope carries the event.

### wallet.linked v1-rc.0

A signed-in user linked a wallet credential to their account.

- Identifier: `urn:qauth:event:wallet.linked:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [wallet.linked.v1-rc.0.json](/schemas/events/wallet.linked.v1-rc.0.json)
- Security type · SSF: `https://schemas.openid.net/secevent/caep/event-type/credential-change` ([SSF events](/reference/ssf-events/))

| Member            | Type    | Required | Meaning                                                                             |
| ----------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `credentialId`    | string  | yes      | The id of the account credential the wallet was linked as.                          |
| `subjectSource`   | string  | yes      | How the subject was resolved from the presentation (ADR-009).                       |
| `rebound`         | boolean | yes      | Whether the link replaced an earlier binding of the same credential.                |
| `verifierProfile` | string  | yes      | The verifier profile the wallet presentation was checked under, such as `haip-1.0`. |

### wallet.link_failed v1-rc.0

A wallet could not be linked, for example because it is linked to another account.

- Identifier: `urn:qauth:event:wallet.link_failed:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [wallet.link_failed.v1-rc.0.json](/schemas/events/wallet.link_failed.v1-rc.0.json)

| Member            | Type   | Required | Meaning                                                                                         |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `reason`          | string | yes      | Why, as a `snake_case` code such as `invalid_credentials`. The set may grow in a minor release. |
| `verifierProfile` | string | no       | The verifier profile the wallet presentation was checked under, such as `haip-1.0`.             |

### wallet.presentation_received v1-rc.0

The OpenID4VP response endpoint accepted a wallet presentation. This is not a sign-in: the flow that asked for it decides.

- Identifier: `urn:qauth:event:wallet.presentation_received:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: none: the event never carries one
- Schema: [wallet.presentation_received.v1-rc.0.json](/schemas/events/wallet.presentation_received.v1-rc.0.json)

| Member              | Type    | Required | Meaning                                                                             |
| ------------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `verifierProfile`   | string  | yes      | The verifier profile the wallet presentation was checked under, such as `haip-1.0`. |
| `presentationCount` | integer | yes      | How many presentations the response held.                                           |

### interaction.created v1-rc.0

A browser ceremony began: the server created an interaction and bound it to the browser that started it with a flow cookie.

- Identifier: `urn:qauth:event:interaction.created:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [interaction.created.v1-rc.0.json](/schemas/events/interaction.created.v1-rc.0.json)

| Member        | Type                                                                         | Required | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------- | ---------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `interaction` | UUID                                                                         | yes      | The interaction: a random reference the server gave it, which links the events of one interaction. Never the interaction id the browser holds.                                                                                                                                                                                                                                                                                                   |
| `purpose`     | one of `authorization`, `logout`, `mailed_pass`, `account`, or a later value | yes      | `authorization`: an authorization request at the authorization endpoint. `logout`: an RP-initiated logout at the end-session endpoint, which asks the person to confirm (#675). `mailed_pass`: the reset or registration start a mailed pass link carries (#637). `account`: a sign-in, a fresh sign-in before a change, an enrolment or an upstream link on the hosted account page (#844), for no client. The set may grow in a minor release. |
| `step`        | string                                                                       | yes      | The first step the ceremony asks for.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `replaces`    | UUID                                                                         | no       | For an interaction that a user switch started: the interaction it replaces, which ended with it. Nothing proved in that one carries over.                                                                                                                                                                                                                                                                                                        |

### interaction.answered v1-rc.0

The engine processed an answer to the current step of an interaction. Of two answers to one step, only the one processed is recorded.

- Identifier: `urn:qauth:event:interaction.answered:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [interaction.answered.v1-rc.0.json](/schemas/events/interaction.answered.v1-rc.0.json)

| Member        | Type                                                              | Required | Meaning                                                                                                                                                                                                                                                                                                         |
| ------------- | ----------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `interaction` | UUID                                                              | yes      | The interaction: a random reference the server gave it, which links the events of one interaction. Never the interaction id the browser holds.                                                                                                                                                                  |
| `step`        | string                                                            | yes      | The step the answer was for.                                                                                                                                                                                                                                                                                    |
| `outcome`     | one of `next_step`, `authenticated`, `finished`, or a later value | yes      | `next_step`: another step comes next, or the same one again after a refused answer. `authenticated`: the answer proved who the user is; the browser session and the flow cookie were replaced. `finished`: the interaction ended, and the request it was for is completed. The set may grow in a minor release. |

### interaction.cancelled v1-rc.0

An interaction ended before it finished, at the request of the browser that started it.

- Identifier: `urn:qauth:event:interaction.cancelled:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [interaction.cancelled.v1-rc.0.json](/schemas/events/interaction.cancelled.v1-rc.0.json)

| Member         | Type                                           | Required | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------- | ---------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `interaction`  | UUID                                           | yes      | The interaction: a random reference the server gave it, which links the events of one interaction. Never the interaction id the browser holds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `step`         | string                                         | yes      | The step the interaction was at.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `reason`       | one of `user`, `user_switch`, or a later value | yes      | `user`: the person cancelled. `user_switch`: the person chose another account, and a new interaction for the same request replaced this one. The set may grow in a minor release.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `sessionEnded` | boolean                                        | no       | For a "Not you?" user switch that signed the browser out of the account the screen showed: `true`. The sessions of that account the interaction held were ended (the one a sign-in during the interaction started, and the one the browser was already signed in with when the interaction started when it was that account’s, #964), and so was the session the browser’s cookie named when it was a later one of the same account, so no later sign-in or client on the browser continues them. The event’s subject is that account. Absent otherwise: on a cancel, on "Use another account" at the account chooser, and on a switch while the screen showed no account with a session the interaction held. |

### interaction.expired v1-rc.0

An interaction expired before it finished or was cancelled: it reached its absolute expiry, or its first step went unanswered for too long. It can no longer be read or answered.

- Identifier: `urn:qauth:event:interaction.expired:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [interaction.expired.v1-rc.0.json](/schemas/events/interaction.expired.v1-rc.0.json)

| Member        | Type   | Required | Meaning                                                                                                                                        |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `interaction` | UUID   | yes      | The interaction: a random reference the server gave it, which links the events of one interaction. Never the interaction id the browser holds. |
| `step`        | string | no       | The step the interaction was at, when the server still had its record. Absent otherwise.                                                       |

### request.csrf_rejected v1-rc.0

A form post was refused because its CSRF check failed: the token was missing or did not match.

- Identifier: `urn:qauth:event:request.csrf_rejected:v1-rc.0`
- Category: `user` · Severity: `warning` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [request.csrf_rejected.v1-rc.0.json](/schemas/events/request.csrf_rejected.v1-rc.0.json)

| Member | Type                                                                                                                           | Required | Meaning                                                        |
| ------ | ------------------------------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------- |
| `form` | one of `sign_in`, `wallet_sign_in`, `wallet_link`, `consent`, `consent_revocation`, `interaction`, `account`, or a later value | yes      | The form that was posted. The set may grow in a minor release. |

### request.account_operation_refused v1-rc.0

An account API call was refused before its operation ran: the token was an act-chain token the operation does not take, the sign-in behind it was too old or lacked the account’s strongest bound factor (ADR-017 Decision 8), or what the guard decides on could not be read.

- Identifier: `urn:qauth:event:request.account_operation_refused:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `user`, when known
- Schema: [request.account_operation_refused.v1-rc.0.json](/schemas/events/request.account_operation_refused.v1-rc.0.json)

| Member           | Type                                                                                                              | Required | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operation`      | string                                                                                                            | yes      | The refused operation: its `operationId` in the account API contract, such as `account.password.change`.                                                                                                                                                                                                                                                                                                                           |
| `reason`         | one of `delegated_token`, `authentication_too_old`, `strongest_factor_missing`, `lookup_failed`, or a later value | yes      | `delegated_token`: an act-chain token at an operation that takes none. `authentication_too_old`: the sign-in is more than five minutes old, or the token gives no time for it or one more than a minute ahead of the server’s clock. `strongest_factor_missing`: the sign-in lacks the account’s strongest bound factor. `lookup_failed`: the bound factors or the session could not be read. The set may grow in a minor release. |
| `requiredFactor` | one of `pop`, `otp`, `pwd`, or a later value                                                                      | no       | With `strongest_factor_missing` only: the RFC 8176 `amr` value the sign-in needed, the account’s strongest bound factor. The set may grow in a minor release.                                                                                                                                                                                                                                                                      |
| `maxAge`         | integer                                                                                                           | no       | With `authentication_too_old` and `strongest_factor_missing` only: the `max_age` of the step-up challenge the call was answered with, in seconds.                                                                                                                                                                                                                                                                                  |

### ssf.stream.verification_requested v1-rc.0

A receiver asked for a verification event on one of its Shared Signals Framework streams (SSF 1.0 §8.1.4). QAuth sends the verification Security Event Token to that stream only.

- Identifier: `urn:qauth:event:ssf.stream.verification_requested:v1-rc.0`
- Category: `user` · Severity: `info` · Since: v0.2.0
- Subject: `ssf_stream`, when known
- Schema: [ssf.stream.verification_requested.v1-rc.0.json](/schemas/events/ssf.stream.verification_requested.v1-rc.0.json)

| Member  | Type   | Required | Meaning                                                                                                 |
| ------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `state` | string | no       | The opaque value the receiver sent, returned to it in the verification event. Absent when it sent none. |

### key.emergency_retired v1-rc.0

An operator retired a published key of the realm that may be compromised (ADR-019 Decision 9): it left the JWKS at once, no verifier in the auth server accepts it, and a new key took its place. A key QAuth does not publish, such as the data-at-rest key, is not recorded as this type.

- Identifier: `urn:qauth:event:key.emergency_retired:v1-rc.0`
- Category: `admin` · Severity: `critical` · Since: v0.2.0
- Subject: none: the event never carries one
- Schema: [key.emergency_retired.v1-rc.0.json](/schemas/events/key.emergency_retired.v1-rc.0.json)
- Security type · SSF: `urn:qauth:secevent:key-emergency-retired:v1-rc.0` ([SSF events](/reference/ssf-events/))

| Member    | Type                                                                                                                                                                                | Required | Meaning                                                                                                                                                |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `keyId`   | string                                                                                                                                                                              | yes      | The `kid` of the retired key. Never the key itself.                                                                                                    |
| `purpose` | one of `token_signing`, `event_signing`, `federation_entity`, `trust_anchor`, `oid4vp_request_signing`, `oid4vp_response_encryption`, `upstream_client_assertion`, or a later value | yes      | What the key was for, one of the purposes whose keys QAuth publishes, such as `token_signing` or `event_signing`. The set may grow in a minor release. |

### admin.change_applied v1-rc.0

An administrator, a service account or an operator changed something in the realm through an admin operation. Emitted for every such change, in its transaction; no setting turns it off. The admin events of a realm form one hash chain.

- Identifier: `urn:qauth:event:admin.change_applied:v1-rc.0`
- Category: `admin` · Severity: `info` · Since: v0.2.0
- Subject: none: the event never carries one
- Schema: [admin.change_applied.v1-rc.0.json](/schemas/events/admin.change_applied.v1-rc.0.json)
- Diff: `data.diff` lists what changed, with every secret value masked ([Admin events](#admin-events))

| Member        | Type            | Required | Meaning                                                                                                                                                                                                                |
| ------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operation`   | string          | yes      | The operation's id in the permission catalog, such as `realms.policies.write` (ADR-019 Decision 7).                                                                                                                    |
| `target`      | object          | yes      | What the operation changed.                                                                                                                                                                                            |
| `target.type` | string          | yes      | What kind of thing the operation changed, as a `snake_case` code such as `realm`, `client` or `webhook_subscription`. The set grows with the admin API.                                                                |
| `target.id`   | string          | yes      | The changed thing's identifier, such as a realm id or a `client_id`. It stays valid after the thing is deleted.                                                                                                        |
| `diff`        | array of object | yes      | What the operation changed in the target, field by field. Only changed fields are listed. A nested object is diffed member by member; any other value, an array included, is shown whole. Every secret value is `***`. |
| `approvals`   | array of object | yes      | The approvals the operation ran on, both of a two-admin operation. Empty when it needed none.                                                                                                                          |

## Earlier event names

Before the event contract, QAuth wrote free-form event names to its audit log and its log
lines. Each becomes a registered type. Several earlier names become one type, and the name implied
some `data`. Since 0.2.0 the auth server records events and writes no audit row; the upgrade
copies every audit row into the event store with this map. A copied event gets the `data` its name
implies and the members of the old row that have the declared form. A required member an old row
cannot supply gets a fixed value: `unknown` for a code, `false` for a flag, an empty list, `0`
for a count or the nil UUID for an id. Log lines keep their names.

| Earlier name                      | Written to | Type                                                   | Implied `data`                |
| --------------------------------- | ---------- | ------------------------------------------------------ | ----------------------------- |
| `user.login.success`              | audit log  | `urn:qauth:event:user.signed_in:v1-rc.0`               | `method: password`            |
| `user.login.failure`              | audit log  | `urn:qauth:event:user.sign_in_failed:v1-rc.0`          | `method: password`            |
| `ui.login.success`                | audit log  | `urn:qauth:event:user.signed_in:v1-rc.0`               | `method: password`            |
| `ui.login.failure`                | audit log  | `urn:qauth:event:user.sign_in_failed:v1-rc.0`          | `method: password`            |
| `ui.login.csrf_failure`           | audit log  | `urn:qauth:event:request.csrf_rejected:v1-rc.0`        | `form: sign_in`               |
| `ui.wallet_login.success`         | audit log  | `urn:qauth:event:user.signed_in:v1-rc.0`               | `method: wallet`              |
| `ui.wallet_login.failure`         | audit log  | `urn:qauth:event:user.sign_in_failed:v1-rc.0`          | `method: wallet`              |
| `ui.wallet_login.csrf_failure`    | audit log  | `urn:qauth:event:request.csrf_rejected:v1-rc.0`        | `form: wallet_sign_in`        |
| `user.logout.success`             | audit log  | `urn:qauth:event:user.signed_out:v1-rc.0`              | —                             |
| `user.logout.failure`             | audit log  | `urn:qauth:event:user.sign_out_failed:v1-rc.0`         | —                             |
| `user.register.success`           | log line   | `urn:qauth:event:user.registered:v1-rc.0`              | `method: password`            |
| `user.register.failure`           | log line   | `urn:qauth:event:user.registration_failed:v1-rc.0`     | —                             |
| `oauth.authorize.success`         | audit log  | `urn:qauth:event:authorization.completed:v1-rc.0`      | —                             |
| `oauth.authorize.failure`         | audit log  | `urn:qauth:event:authorization.failed:v1-rc.0`         | —                             |
| `oauth.stepup.required`           | audit log  | `urn:qauth:event:step_up.required:v1-rc.0`             | —                             |
| `oauth.stepup.elevation`          | audit log  | `urn:qauth:event:step_up.elevated:v1-rc.0`             | —                             |
| `oauth.consent.granted`           | audit log  | `urn:qauth:event:consent.granted:v1-rc.0`              | —                             |
| `oauth.consent.denied`            | audit log  | `urn:qauth:event:consent.denied:v1-rc.0`               | —                             |
| `oauth.consent.revoked`           | audit log  | `urn:qauth:event:consent.revoked:v1-rc.0`              | —                             |
| `oauth.consent.csrf_failure`      | audit log  | `urn:qauth:event:request.csrf_rejected:v1-rc.0`        | `form: consent`               |
| `consents.revoke.csrf_failure`    | audit log  | `urn:qauth:event:request.csrf_rejected:v1-rc.0`        | `form: consent_revocation`    |
| `oauth.token.exchange.success`    | audit log  | `urn:qauth:event:token.issued:v1-rc.0`                 | —                             |
| `oauth.token.exchange.failure`    | audit log  | `urn:qauth:event:token.request_failed:v1-rc.0`         | —                             |
| `oauth.revoke.success`            | audit log  | `urn:qauth:event:token.revoked:v1-rc.0`                | —                             |
| `oauth.revoke.failure`            | audit log  | `urn:qauth:event:token.revocation_failed:v1-rc.0`      | —                             |
| `oauth.introspect.success`        | audit log  | `urn:qauth:event:token.introspected:v1-rc.0`           | —                             |
| `oauth.introspect.failure`        | audit log  | `urn:qauth:event:token.introspection_failed:v1-rc.0`   | —                             |
| `oauth.userinfo.success`          | audit log  | `urn:qauth:event:userinfo.served:v1-rc.0`              | —                             |
| `oauth.userinfo.failure`          | audit log  | `urn:qauth:event:userinfo.request_failed:v1-rc.0`      | —                             |
| `oauth.client.registered`         | audit log  | `urn:qauth:event:client.created:v1-rc.0`               | `registration: dynamic`       |
| `oauth.client.created`            | audit log  | `urn:qauth:event:client.created:v1-rc.0`               | `registration: developer_api` |
| `oauth.client.updated`            | audit log  | `urn:qauth:event:client.updated:v1-rc.0`               | —                             |
| `oauth.client.deleted`            | audit log  | `urn:qauth:event:client.deleted:v1-rc.0`               | —                             |
| `oauth.client.secret_regenerated` | audit log  | `urn:qauth:event:client.secret_rotated:v1-rc.0`        | —                             |
| `oauth.client.suspended`          | audit log  | `urn:qauth:event:client.suspended:v1-rc.0`             | —                             |
| `oauth.client.suspension_lifted`  | audit log  | `urn:qauth:event:client.suspension_lifted:v1-rc.0`     | —                             |
| `api_key.created`                 | audit log  | `urn:qauth:event:api_key.created:v1-rc.0`              | —                             |
| `api_key.revoked`                 | audit log  | `urn:qauth:event:api_key.revoked:v1-rc.0`              | —                             |
| `auth.wallet_link.success`        | audit log  | `urn:qauth:event:wallet.linked:v1-rc.0`                | —                             |
| `auth.wallet_link.failure`        | audit log  | `urn:qauth:event:wallet.link_failed:v1-rc.0`           | —                             |
| `auth.wallet_link.csrf_failure`   | audit log  | `urn:qauth:event:request.csrf_rejected:v1-rc.0`        | `form: wallet_link`           |
| `oid4vp.response.received`        | audit log  | `urn:qauth:event:wallet.presentation_received:v1-rc.0` | —                             |

---

# Account API

URL: https://docs.qauth.dev/reference/account-api/

<!-- Generated by `pnpm exec nx run shared-account-contract:contract-export` from libs/shared/account-contract. Do not edit by hand. -->

The account API is how a signed-in person manages their own account ([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/), Decision 7): the profile, the sign-in methods, the sessions, the security log, the addresses, the connected apps, the notices and deleting the account. The account console calls it from its backend, with the person’s access token ([ADR-020](/reference/records/adr/020-ui-surfaces-and-acceptance-criteria/) §3).

The contract is one OpenAPI 3.1 document, [openapi.json](/account/v1-rc.0/openapi.json). The typed client in `libs/shared/account-client` is generated from it, and both are generated from `libs/shared/account-contract`. The stable-surface check compares the document with the last release ([ADR-018](/reference/records/adr/018-1-0-scope-and-stability/) §5). Every operation also follows the [API conventions](/reference/api-conventions/).

## Status

- This document is the contract, published before the implementation. The auth server serves two of its operations today, `account.consents.list` and `account.consents.delete`; the others arrive with the account console’s backend. The two served operations still answer errors with the auth server’s general problem document, which may carry `detail` and `errors[].message`; the implementation of this contract narrows them to its problem document. It also narrows what they send beyond that: `client_name` is the name the client registered, which no display rule has checked; the path accepts an id in capital letters; and the deletion’s answer and the errors carry no `Cache-Control: no-store`.
- `GET /consents` and `DELETE /consents/{id}`, which the hosted UI calls with the session cookie and an `X-CSRF-Token` header, are deprecated aliases of `account.consents.list` and `account.consents.delete`. They are removed when the account console replaces the hosted UI’s consents page.
- `GET /api/consents` and `DELETE /api/consents/{id}`, deprecated for `/developer/v1-rc.0/consents`, list and revoke a person’s consents with a developer-audience token. A person’s consents move from the developer portal to the account console (ADR-020 §3), so `account.consents.*` is what the console calls. Retiring the developer family’s consent operations is a change of that family’s own contract.

## Tokens

- The callers are backends, such as the account console’s, that hold a person’s access token whose only audience is `urn:qauth:aud:account:v1-rc.0`, sent as a Bearer token or, while the server’s DPoP support is on, a DPoP-bound one. No cookie authenticates a call, and the server sends no CORS headers. Each operation names the audience in `x-qauth-audience`.
- The token’s subject is an enabled user of the request’s realm, and every operation acts on that user’s own account only. A resource of another account answers `not_found`, as one that does not exist.
- Each operation names the permission it needs in `x-qauth-permission` and its class in `x-qauth-class`. The token needs the account scope of that class: `qauth:account:read` for a `read` operation, `qauth:account:write` for a `write` one. The two are independent, so a caller that reads and writes asks for both. A token without it gets 403 `forbidden` with `WWW-Authenticate: Bearer realm="OAuth", error="insufficient_scope", scope="<the scope>"`, or, for a request in the `DPoP` scheme, `WWW-Authenticate: DPoP error="insufficient_scope", scope="<the scope>", algs="<the proof algorithms>"`, before any other rule of the operation. QAuth issues these scopes only to a client whose audience an operator set to `urn:qauth:aud:account:v1-rc.0`.

## Fresh authentication

- An operation whose `x-qauth-fresh-authentication` is `strongest-factor` needs a sign-in at most 300 seconds old (the token’s `auth_time`) whose `amr` holds the account’s strongest bound factor: `pop` when a passkey is bound, else `otp` when an authenticator app is, else `pwd`.
- `strongest-factor-or-recovery-code` also accepts a sign-in of the same age that used a recovery code in place of a lost second factor. Only the two halves of a rebind after a lost factor take it (ADR-017 Decision 8): removing a passkey or the authenticator app, and binding a new authenticator app.
- Otherwise the operation answers 401 `insufficient_user_authentication` (RFC 9470 §3) with the challenge `WWW-Authenticate: Bearer error="insufficient_user_authentication", max_age="300"` when the sign-in is too old, or `max_age="0"` when it is recent but lacks the strongest factor. The problem document carries the same `max_age`. The caller sends the person to the authorization endpoint with that `max_age`, and repeats the call with the new token. That sign-in ends with the account’s strongest bound factor, since a sign-in completes only once the transaction has proved it (ADR-017, the downgrade rule).

For example, a password change with a sign-in of ten minutes ago:

```http
HTTP/1.1 401 Unauthorized
Cache-Control: no-store
Content-Type: application/problem+json
WWW-Authenticate: Bearer error="insufficient_user_authentication", max_age="300"

{"type":"https://docs.qauth.dev/reference/problem-types/#insufficient-user-authentication","title":"Insufficient user authentication","status":401,"code":"insufficient_user_authentication","trace_id":"0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60","max_age":300}
```

## Act-chain tokens

- An act-chain token (RFC 8693 `act`: an admin or an agent acting for the person) never counts as the person’s fresh authentication.
- An operation whose `x-qauth-act-chain` is `refused` answers an act-chain token with 403 `delegated_token_refused`, before any fresh-authentication check, so a delegated caller never gets a challenge it cannot meet. Every operation that changes a credential, an identifier, the contact address or a linked account refuses one, and so do deleting the account and reporting a sign-in as not the person’s.

## Rules

- Typed data from the auth server’s own records, never HTML. Every string a response carries is an enum, a constant or a bounded value with a pattern. A display value has no markup bracket, no control, format, private-use or unassigned character, no line separator, and no space at either end, and `x-qauth-display` says where it comes from.
- A request takes no unbounded text: a value the person types, such as a profile value or a passkey’s name, is a bounded display value too. A password is the one exception: it takes any character, appears only in a request (`writeOnly`) and is never shown.
- Every error is an RFC 9457 problem document (`application/problem+json`) with a stable `code` and a `trace_id`, and no prose: no `detail`, no `instance`, and field errors as reason codes. Each error response lists the codes it may carry in `x-qauth-problem-codes`, a closed list per operation.
- A list pages by cursor: `limit` (1 to 200, default 50) and `cursor`, the opaque `nextCursor` of the previous page, which is `null` on the last page.
- An update is a JSON Merge Patch (RFC 7396, `application/merge-patch+json`) sent with `If-Match`, the `ETag` of the resource’s last read. A stale value answers 412 `precondition_failed`, a missing one 428 `precondition_required`.
- Every answer carries `Cache-Control: no-store`.
- The security log keeps an entry for 90 days by default, a realm setting. Its `kind` is a closed list, built from QAuth’s events through an allow list.

## Operations

Every operation sits under `/account/v1-rc.0` and takes a token whose only audience is `urn:qauth:aud:account:v1-rc.0`. The document gives each one its parameters, its body, one example request and response, and its error responses, each with the codes it may carry. "Its own codes" are the ones beyond what every operation of its shape answers: `bad_request`, the token guard's 401s, `forbidden`, `misdirected_request`, `too_many_requests`, `internal_error` and `service_unavailable`; `validation_error` with parameters or a body; `invalid_cursor` on a list; `content_too_large` and `unsupported_media_type` with a body; the precondition codes and `unprocessable_content` on an update; `insufficient_user_authentication` with fresh authentication; and `delegated_token_refused` where an act-chain token is refused.

### Profile

The person’s profile fields and groups.

| Operation                                     | Request          | Fresh authentication | Act-chain token | Success | Its own codes |
| --------------------------------------------- | ---------------- | -------------------- | --------------- | ------- | ------------- |
| Read the profile (`account.profile.get`)      | `GET /profile`   | —                    | Accepted        | 200     | —             |
| Update the profile (`account.profile.update`) | `PATCH /profile` | —                    | Accepted        | 200     | —             |

### Sign-in methods

Password, passkeys, the authenticator app (TOTP) and recovery codes.

| Operation                                                                  | Request                           | Fresh authentication              | Act-chain token | Success | Its own codes                                            |
| -------------------------------------------------------------------------- | --------------------------------- | --------------------------------- | --------------- | ------- | -------------------------------------------------------- |
| Read the sign-in methods (`account.signInMethods.get`)                     | `GET /sign-in-methods`            | —                                 | Accepted        | 200     | —                                                        |
| Change the password (`account.password.change`)                            | `POST /password/change`           | Strongest factor                  | Refused         | 204     | `invalid_current_password`, `not_found`, `weak_password` |
| List the passkeys (`account.passkeys.list`)                                | `GET /passkeys`                   | —                                 | Accepted        | 200     | —                                                        |
| Read a passkey (`account.passkeys.get`)                                    | `GET /passkeys/{passkeyId}`       | —                                 | Accepted        | 200     | `not_found`                                              |
| Rename a passkey (`account.passkeys.update`)                               | `PATCH /passkeys/{passkeyId}`     | —                                 | Refused         | 200     | `not_found`                                              |
| Remove a passkey (`account.passkeys.delete`)                               | `DELETE /passkeys/{passkeyId}`    | Strongest factor or recovery code | Refused         | 204     | `not_found`, `last_credential`, `second_factor_required` |
| Start an authenticator-app enrolment (`account.totp.enrollment.create`)    | `POST /totp/enrollment`           | Strongest factor or recovery code | Refused         | 201     | `conflict`                                               |
| Confirm an authenticator-app enrolment (`account.totp.enrollment.confirm`) | `POST /totp/enrollment/confirm`   | Strongest factor or recovery code | Refused         | 200     | `invalid_code`, `not_found`                              |
| Remove the authenticator app (`account.totp.delete`)                       | `DELETE /totp`                    | Strongest factor or recovery code | Refused         | 204     | `not_found`, `second_factor_required`                    |
| Read the recovery codes’ status (`account.recoveryCodes.get`)              | `GET /recovery-codes`             | —                                 | Accepted        | 200     | —                                                        |
| Regenerate the recovery codes (`account.recoveryCodes.regenerate`)         | `POST /recovery-codes/regenerate` | Strongest factor                  | Refused         | 200     | `conflict`                                               |

### Sessions

Where the person is signed in, and "sign out everywhere".

| Operation                                       | Request                        | Fresh authentication | Act-chain token | Success | Its own codes |
| ----------------------------------------------- | ------------------------------ | -------------------- | --------------- | ------- | ------------- |
| List the sessions (`account.sessions.list`)     | `GET /sessions`                | —                    | Accepted        | 200     | —             |
| End a session (`account.sessions.delete`)       | `DELETE /sessions/{sessionId}` | —                    | Accepted        | 204     | `not_found`   |
| Sign out everywhere (`account.sessions.endAll`) | `POST /sessions/end-all`       | —                    | Accepted        | 204     | —             |

### Security log

The last 90 days of sign-ins, new devices and security changes, and "this wasn’t me".

| Operation                                              | Request                               | Fresh authentication | Act-chain token | Success | Its own codes           |
| ------------------------------------------------------ | ------------------------------------- | -------------------- | --------------- | ------- | ----------------------- |
| List the security log (`account.securityLog.list`)     | `GET /security-log`                   | —                    | Accepted        | 200     | —                       |
| Report "this wasn’t me" (`account.securityLog.report`) | `POST /security-log/{entryId}/report` | —                    | Refused         | 204     | `not_found`, `conflict` |

### Addresses

The address the account signs in with, and its contact address.

| Operation                                                   | Request                        | Fresh authentication | Act-chain token | Success | Its own codes                                    |
| ----------------------------------------------------------- | ------------------------------ | -------------------- | --------------- | ------- | ------------------------------------------------ |
| Read the addresses (`account.addresses.get`)                | `GET /addresses`               | —                    | Accepted        | 200     | —                                                |
| Start an address change (`account.addressChange.create`)    | `POST /address-change`         | Strongest factor     | Refused         | 202     | `disabled_by_realm`                              |
| Confirm an address change (`account.addressChange.confirm`) | `POST /address-change/confirm` | Strongest factor     | Refused         | 200     | `invalid_code`, `not_found`, `disabled_by_realm` |

### Linked accounts

The upstream accounts the person can sign in through, and their removal.

| Operation                                                         | Request                                     | Fresh authentication | Act-chain token | Success | Its own codes                  |
| ----------------------------------------------------------------- | ------------------------------------------- | -------------------- | --------------- | ------- | ------------------------------ |
| List the linked upstream accounts (`account.linkedAccounts.list`) | `GET /linked-accounts`                      | —                    | Accepted        | 200     | —                              |
| Unlink an upstream account (`account.linkedAccounts.delete`)      | `DELETE /linked-accounts/{linkedAccountId}` | Strongest factor     | Refused         | 204     | `not_found`, `last_credential` |

### Connected apps

The apps the person consented to, and their revocation.

| Operation                                         | Request                        | Fresh authentication | Act-chain token | Success | Its own codes |
| ------------------------------------------------- | ------------------------------ | -------------------- | --------------- | ------- | ------------- |
| List the connected apps (`account.consents.list`) | `GET /consents`                | —                    | Accepted        | 200     | —             |
| Disconnect an app (`account.consents.delete`)     | `DELETE /consents/{consentId}` | —                    | Accepted        | 204     | `not_found`   |

### Account

Deleting the account.

| Operation                                      | Request          | Fresh authentication | Act-chain token | Success | Its own codes       |
| ---------------------------------------------- | ---------------- | -------------------- | --------------- | ------- | ------------------- |
| Preview the deletion (`account.deletion.get`)  | `GET /deletion`  | —                    | Accepted        | 200     | —                   |
| Delete the account (`account.deletion.create`) | `POST /deletion` | Strongest factor     | Refused         | 204     | `disabled_by_realm` |

### Notifications

The security notices the account receives.

| Operation                                                                 | Request                         | Fresh authentication | Act-chain token | Success | Its own codes |
| ------------------------------------------------------------------------- | ------------------------------- | -------------------- | --------------- | ------- | ------------- |
| Read the notification preferences (`account.notificationPreferences.get`) | `GET /notification-preferences` | —                    | Accepted        | 200     | —             |

## Security log

An entry's `kind` is one of a closed list. Each kind is built from QAuth's events ([Events](/reference/events/)) through an allow list; the security log is read from the event store, never kept on its own. A source with an issue is an event type that the feature of that issue registers when it ships, in the same change that marks it registered in the contract. A test keeps the list matched to the event registry both ways: every user event is either a source here or left out with a reason.

| Kind                         | What it tells the person                                                                                                                                                                        | Built from                                                                                                                                                                         | "This wasn't me" |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `signed_in`                  | The person signed in.                                                                                                                                                                           | `user.signed_in`                                                                                                                                                                   | Yes              |
| `new_device`                 | The person signed in from a device QAuth had not seen for the account (the device recognition of #689).                                                                                         | `user.new_device_seen` (with #689)                                                                                                                                                 | Yes              |
| `second_factor_failed`       | A sign-in gave the right password and then a wrong second factor. Only these failed sign-ins are shown: a log of every failed sign-in would tell an attacker which guesses reached the account. | `user.sign_in_failed`, only a refused second-factor step after an accepted password, whose `method` is the second factor’s (TOTP from F2c); never a refused identifier or password | No               |
| `session_ended`              | A session ended: a sign-out, one session ended from the console, or "sign out everywhere".                                                                                                      | `user.signed_out`                                                                                                                                                                  | No               |
| `password_changed`           | The account’s password was changed.                                                                                                                                                             | `user.password_reset`, `user.password_changed`                                                                                                                                     | No               |
| `credential_added`           | A passkey or an authenticator app (TOTP) was added to the account.                                                                                                                              | `user.credential_added`                                                                                                                                                            | No               |
| `credential_removed`         | A passkey or an authenticator app (TOTP) was removed from the account.                                                                                                                          | `user.credential_removed`                                                                                                                                                          | No               |
| `credential_disabled`        | The password or the authenticator app was disabled after too many wrong attempts (ADR-017 Decision 7).                                                                                          | `user.credential_disabled` (with #693)                                                                                                                                             | No               |
| `recovery_code_used`         | A recovery code was used in place of a second factor.                                                                                                                                           | `user.recovery_code_used`                                                                                                                                                          | No               |
| `recovery_codes_regenerated` | A new set of recovery codes replaced the old one.                                                                                                                                               | `user.recovery_codes_regenerated`                                                                                                                                                  | No               |
| `recovery_codes_failed`      | Recovery codes were tried and refused 100 times (ADR-017 Decision 7).                                                                                                                           | `user.recovery_codes_failed`                                                                                                                                                       | No               |
| `send_ceiling_reached`       | Codes were requested for the account’s address past the per-address send ceiling, and a notice with a reset pass went to it (ADR-017 Decision 7).                                               | `user.send_ceiling_reached` (with #637)                                                                                                                                            | No               |
| `identifier_changed`         | The address the account signs in with, or its contact address, changed.                                                                                                                         | `user.identifier_changed` (with #690)                                                                                                                                              | No               |
| `account_linked`             | A wallet or an upstream account was linked to the account.                                                                                                                                      | `wallet.linked`, `user.upstream_linked`                                                                                                                                            | No               |
| `account_unlinked`           | A wallet or an upstream account was unlinked from the account.                                                                                                                                  | `user.upstream_unlinked`                                                                                                                                                           | No               |
| `consent_granted`            | The person let an app access the account.                                                                                                                                                       | `consent.granted`                                                                                                                                                                  | No               |
| `consent_revoked`            | An app’s access to the account was withdrawn.                                                                                                                                                   | `consent.revoked`                                                                                                                                                                  | No               |

A failed sign-in appears only as `second_factor_failed`, after a correct password: a log of every failed sign-in would tell an attacker which guesses reached the account. No entry carries the raw IP address; the location is approximate.

## Notices

The security notices the account receives. A minor release may add one, such as the new-agent-grant notice of ADR-020 §3. Notices go to the contact address; an account without one sees them only in its security log. The mandatory ones always go out; a realm may switch off the others.

| Notice                       | When                                                                                                       | Mandatory |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------- | --------- |
| `new_device`                 | A sign-in from a device QAuth had not seen for the account.                                                | No        |
| `password_changed`           | The password was changed.                                                                                  | Yes       |
| `credential_disabled`        | The password or the authenticator app was disabled after too many wrong attempts. It carries a reset pass. | Yes       |
| `credential_added`           | A passkey or an authenticator app was added.                                                               | Yes       |
| `credential_removed`         | A passkey or an authenticator app was removed.                                                             | Yes       |
| `recovery_code_used`         | A recovery code was used.                                                                                  | Yes       |
| `recovery_codes_regenerated` | The recovery codes were regenerated.                                                                       | Yes       |
| `recovery_codes_failed`      | Recovery codes were tried and refused 100 times.                                                           | No        |
| `send_ceiling_reached`       | Codes were requested past the per-address send ceiling. It carries a reset pass.                           | Yes       |
| `second_factor_failed`       | A wrong second factor followed a correct password.                                                         | Yes       |
| `identifier_changed`         | The sign-in address or the contact address changed; sent to the old address.                               | Yes       |
| `account_linked`             | An upstream account was linked, so the account can sign in through it.                                     | Yes       |
| `account_unlinked`           | An upstream account was unlinked.                                                                          | Yes       |
| `account_deleted`            | The account was deleted.                                                                                   | Yes       |

## Errors

An error is an RFC 9457 problem details document (`application/problem+json`) with a stable `code` and a `trace_id`, as on the other API families ([API conventions](/reference/api-conventions/#errors)). Its `type` and `title` are the code's entry on [Problem types](/reference/problem-types/). It carries no `detail` and no `instance`: a console shows its own text for the code, with the trace id, and treats a code it does not know by its HTTP status. A field error names a reason, one of `required`, `unknown`, `read_only`, `too_short`, `too_long`, `invalid_format`, `not_allowed`; a refused new password, one or more of `too_short`, `too_long`, `blocklisted`, `too_weak`, `breached`.

| Code                               | Status | Meaning                                                                                                                                                                                                                                  |
| ---------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bad_request`                      | 400    | The request is malformed and no more specific code applies.                                                                                                                                                                              |
| `validation_error`                 | 400    | The request does not match the schema of the operation. `errors` names each field and why.                                                                                                                                               |
| `invalid_cursor`                   | 400    | The `cursor` does not parse, or it belongs to another list.                                                                                                                                                                              |
| `invalid_current_password`         | 400    | The current password a password change names is wrong. It counts on the account’s failure ladder, as a failed sign-in does.                                                                                                              |
| `invalid_code`                     | 400    | A one-time code in the request is wrong, expired or used: the first TOTP code of an enrolment, or a code mailed to an address. It counts on the account’s failure ladder for that code.                                                  |
| `unauthorized`                     | 401    | The request carries no access token. `WWW-Authenticate` names the scheme and no error.                                                                                                                                                   |
| `access_token_expired`             | 401    | The access token has expired.                                                                                                                                                                                                            |
| `invalid_access_token`             | 401    | The access token is not valid, is not valid for this operation, or names no active user.                                                                                                                                                 |
| `invalid_dpop_proof`               | 401    | A call under the `DPoP` scheme came with no proof, or with one that is not valid for this request (RFC 9449 §7.1).                                                                                                                       |
| `insufficient_user_authentication` | 401    | The operation needs fresh authentication and the sign-in behind the token is too old or lacks the account’s strongest bound factor (RFC 9470 §3). `max_age` and the `WWW-Authenticate` challenge say how fresh the next sign-in must be. |
| `forbidden`                        | 403    | The token lacks a scope the operation needs.                                                                                                                                                                                             |
| `delegated_token_refused`          | 403    | The token is an act-chain token (RFC 8693 `act`), and the operation changes a credential, an identifier, the contact address or a linked account, or deletes the account: only the person may do that (ADR-019 Decision 7).              |
| `disabled_by_realm`                | 403    | The realm’s policy does not let a person do this themselves, such as deleting the account or changing the sign-in address. An admin can.                                                                                                 |
| `not_found`                        | 404    | The resource does not exist, or belongs to another account: the answer is the same.                                                                                                                                                      |
| `conflict`                         | 409    | The request conflicts with the current state of the account.                                                                                                                                                                             |
| `last_credential`                  | 409    | The change would leave the account with no way to sign in, such as deleting the only passkey of a passkey-only account.                                                                                                                  |
| `second_factor_required`           | 409    | The change would remove the last second factor while the realm’s policy requires one for this account.                                                                                                                                   |
| `precondition_failed`              | 412    | The `If-Match` value does not match the current `ETag` of the resource.                                                                                                                                                                  |
| `content_too_large`                | 413    | The request body is larger than the server accepts.                                                                                                                                                                                      |
| `unsupported_media_type`           | 415    | The media type of the request body is not one the operation accepts.                                                                                                                                                                     |
| `misdirected_request`              | 421    | The server does not answer for the host the request names.                                                                                                                                                                               |
| `unprocessable_content`            | 422    | The request is well formed, but its result fails a rule of the resource, such as a profile field the realm’s profile schema does not accept. `errors` names each field and why.                                                          |
| `weak_password`                    | 422    | The new password does not meet the realm’s password policy. `reasons` lists why.                                                                                                                                                         |
| `precondition_required`            | 428    | The update needs an `If-Match` header.                                                                                                                                                                                                   |
| `too_many_requests`                | 429    | Too many requests. `Retry-After` says when to try again.                                                                                                                                                                                 |
| `internal_error`                   | 500    | The server failed. `trace_id` finds the failure in the server log.                                                                                                                                                                       |
| `service_unavailable`              | 503    | The server cannot answer now, for example while a store it needs is down. It fails closed.                                                                                                                                               |

The account API adds `invalid_current_password`, `invalid_code`, `insufficient_user_authentication`, `delegated_token_refused`, `disabled_by_realm`, `last_credential`, `second_factor_required` to the problem registry.

## Versioning

- The path and the audience carry the major version. Until QAuth 1.0.0 it is a release candidate, `/account/v1-rc.<M>` and `urn:qauth:aud:account:v1-rc.<M>` (today `/account/v1-rc.0`), and nothing about it is promised: a breaking change raises `<M>` for both. The release that ships 1.0.0 serves `/account/v1`.
- Within a major version, changes are additive only: new operations, new optional request members, new response members, and new values of an extensible set (problem codes, field error reasons, password rejection reasons, profile field types, security notices).
- A client ignores response members it does not know, and treats a problem code it does not know by its HTTP status. A request with a member the operation does not declare is refused.
- The published schemas close response objects (`additionalProperties: false`) to describe this version exactly. A later version may add members, so a client must not validate responses strictly against an older schema, and ignores the members it does not know.
- Removing or renaming a member, changing a type, tightening validation, changing a status code, removing an operation, changing what an operation asks of the token (`x-qauth-fresh-authentication`, `x-qauth-act-chain`) and adding to a closed set, such as the security log’s kinds, need a new major version.
- A successor major version is served beside the previous one for at least 12 months, and the previous one stays until the next major release of QAuth.

---

# Experimental features

URL: https://docs.qauth.dev/reference/experimental-features/

<!-- Generated from libs/shared/stability by its tests. Do not edit by hand: change the registry and run `pnpm nx test docs-checks -- -u`. -->

An experimental item ships, but it is outside the stability promise of QAuth 1.0
([ADR-018 §4 and §5](/reference/records/adr/018-1-0-scope-and-stability/)). This page lists every
experimental item, generated from the registry in `libs/shared/stability`. An item joins the
registry in the pull request that adds its switch; an item that a decision record names before it
is built is listed with **Built: no**.

## What experimental means

- The item sits behind a switch, and the switch is off by default.
- Discovery does not mention the item unless the switch is on. The members an item adds are
  absent while it is off, never `null` or `false`, and its routes answer `404`.
- The server logs a warning at boot for each item that is on.
- The page that documents the item shows an "Experimental" banner.
- The item may change in a minor release, without a deprecation window. Read the release notes
  before you upgrade a deployment that turns one on.

The boot warning is one `warn` line per item, with the item's id and a link to its section
below; the link ends in the section's anchor, such as `#oid4vp-10-base` for `oid4vp-1.0-base`:

```text
Experimental feature <id> is on. It may change in a minor release, without a deprecation window. See https://docs.qauth.dev/reference/experimental-features/#<section>
```

The configuration page marks the keys and values that switch an item on as experimental
([Configuration](/operate/configuration/)). For such a key, the warning of its item replaces the
warning of the key, so a deployment sees one line, and only once the item is on.

## Becoming stable

An item becomes stable in a minor release once four conditions hold (ADR-018 §5). Each
condition needs evidence: an RFC number, an issue, a link, or a path in the repository that exists,
such as a test file or a section of an audit report.

1. The spec it implements is an RFC or a Final specification.
2. It has seen external use in a beta.
3. The external audit covered it.
4. Conformance tests exist for it.

`node scripts/experimental-status.mjs` prints the four conditions of every item and names the
items that may become stable. With `--check-stable` it fails when an item marked stable lacks
evidence for a condition.

## Items

| Item                                                  | Built | Switch                                                                           | Spec  |
| ----------------------------------------------------- | ----- | -------------------------------------------------------------------------------- | ----- |
| [`fipa-challenge-endpoint`](#fipa-challenge-endpoint) | no    | `FIRST_PARTY_LOGIN_ENABLED=true`                                                 | draft |
| [`node-first-party`](#node-first-party)               | no    | `@qauth-labs/node/first-party`                                                   | draft |
| [`oid4vp-1.0-base`](#oid4vp-10-base)                  | yes   | `OID4VP_VERIFIER_PROFILE=oid4vp-1.0-base`, with `WALLET_FEDERATION_ENABLED=true` | final |
| [`attestation-client-auth`](#attestation-client-auth) | no    | none named yet                                                                   | draft |
| [`pass-through-leg`](#pass-through-leg)               | no    | `PASS_THROUGH_LEG_ENABLED=true`, with `AUTHORITY_TREE_ENABLED=true`              | draft |
| [`plugin-api`](#plugin-api)                           | yes   | `PLUGIN_API_ENABLED=true`                                                        | draft |

### fipa-challenge-endpoint

**The FiPA authorization challenge endpoint.** Headless sign-in for first-party native apps at `POST /oauth/authorize-challenge`. It stays experimental until FiPA is an RFC; the engine behind it is stable, because the hosted pages use it. PKCE is on by default there, and a per-client setting can switch it off: the single exception to mandatory PKCE.

- Decided in [ADR-017](/reference/records/adr/017-first-party-login/).
- Runs in: the auth server.
- Switch: `FIRST_PARTY_LOGIN_ENABLED=true`. A decision record names it; nothing reads it until the item is built.
- Discovery members: `authorization_challenge_endpoint`, only while the item is on.
- Spec: [OAuth 2.0 for First-Party Applications](https://datatracker.ietf.org/doc/draft-ietf-oauth-first-party-apps/), status `draft`.
- Built: no. Stable: no.
- Documented in: no page yet.

| Condition                                                     | Holds | Evidence and notes                                    |
| ------------------------------------------------------------- | ----- | ----------------------------------------------------- |
| 1. The spec it implements is an RFC or a Final specification. | no    | FiPA is an Internet-Draft.                            |
| 2. It has seen external use in a beta.                        | no    | No beta has run outside the project.                  |
| 3. The external audit covered it.                             | no    | The external audit of ADR-018 §8 has not taken place. |
| 4. Conformance tests exist for it.                            | no    | —                                                     |

### node-first-party

**The `/first-party` subpath of `@qauth-labs/node`.** The Node.js SDK entry point that talks to the FiPA authorization challenge endpoint. It stays experimental with the endpoint, until FiPA is an RFC.

- Decided in [ADR-017](/reference/records/adr/017-first-party-login/).
- Runs in: an SDK.
- Switch: `@qauth-labs/node/first-party`. A decision record names it; nothing reads it until the item is built.
- Spec: [OAuth 2.0 for First-Party Applications](https://datatracker.ietf.org/doc/draft-ietf-oauth-first-party-apps/), status `draft`.
- Built: no. Stable: no.
- Documented in: no page yet.

| Condition                                                     | Holds | Evidence and notes                                    |
| ------------------------------------------------------------- | ----- | ----------------------------------------------------- |
| 1. The spec it implements is an RFC or a Final specification. | no    | FiPA is an Internet-Draft.                            |
| 2. It has seen external use in a beta.                        | no    | No beta has run outside the project.                  |
| 3. The external audit covered it.                             | no    | The external audit of ADR-018 §8 has not taken place. |
| 4. Conformance tests exist for it.                            | no    | —                                                     |

### oid4vp-1.0-base

**The `oid4vp-1.0-base` verifier profile.** The OpenID for Verifiable Presentations 1.0 profile for wallet sign-in. It stays supported, but it allows looser options than HAIP 1.0, such as unsigned requests, so it stays outside the stability promise; `haip-1.0` is the stable profile.

- Decided in [ADR-018](/reference/records/adr/018-1-0-scope-and-stability/).
- Runs in: the auth server.
- Switch: `OID4VP_VERIFIER_PROFILE=oid4vp-1.0-base`, with `WALLET_FEDERATION_ENABLED=true`.
- Discovery members: none.
- Spec: [OpenID for Verifiable Presentations 1.0](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html), status `final`.
- Built: yes. Stable: no.
- Documented in: [`/integrate/wallet-login/`](/integrate/wallet-login/).

| Condition                                                     | Holds | Evidence and notes                                                                                                                             |
| ------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. The spec it implements is an RFC or a Final specification. | yes   | <https://openid.net/specs/openid-4-verifiable-presentations-1_0.html> OpenID4VP 1.0 is an OpenID Foundation Final Specification.               |
| 2. It has seen external use in a beta.                        | no    | No beta has run outside the project; the profile is validated against a mock wallet.                                                           |
| 3. The external audit covered it.                             | no    | The external audit of ADR-018 §8 has not taken place.                                                                                          |
| 4. Conformance tests exist for it.                            | no    | The conformance matrix maps part of OpenID4VP 1.0 (`docs/conformance/requirements/oid4vp-1_0.json`); it does not cover the profile as a whole. |

### attestation-client-auth

**Attestation-based client authentication.** Native apps authenticate to the token endpoint with a client attestation, phase F4 of ADR-017. It stays experimental unless the attestation draft is an RFC before 1.0 is cut.

- Decided in [ADR-017](/reference/records/adr/017-first-party-login/).
- Runs in: the auth server.
- Switch: none named yet.
- Discovery members: `client_attestation_signing_alg_values_supported`, `client_attestation_pop_signing_alg_values_supported`, only while the item is on.
- Spec: [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/), status `draft`.
- Built: no. Stable: no.
- Documented in: no page yet.

| Condition                                                     | Holds | Evidence and notes                                    |
| ------------------------------------------------------------- | ----- | ----------------------------------------------------- |
| 1. The spec it implements is an RFC or a Final specification. | no    | The attestation draft is an Internet-Draft.           |
| 2. It has seen external use in a beta.                        | no    | No beta has run outside the project.                  |
| 3. The external audit covered it.                             | no    | The external audit of ADR-018 §8 has not taken place. |
| 4. Conformance tests exist for it.                            | no    | —                                                     |

### pass-through-leg

**The pass-through leg of the Authority Tree.** Work on a platform that cannot issue a narrowed credential stays inside the tree: the broker vends the owner's own token. It is temporary and weaker by design, with no narrowing. The rest of the Authority Tree is stable.

- Decided in [ADR-016](/reference/records/adr/016-agent-platform-bindings/).
- Runs in: the auth server.
- Switch: `PASS_THROUGH_LEG_ENABLED=true`, with `AUTHORITY_TREE_ENABLED=true`. A decision record names it; nothing reads it until the item is built.
- Discovery members: none.
- Spec: [The pass-through leg, ADR-016 §4](https://docs.qauth.dev/reference/records/adr/016-agent-platform-bindings/), status `draft`.
- Built: no. Stable: no.
- Documented in: no page yet.

| Condition                                                     | Holds | Evidence and notes                                    |
| ------------------------------------------------------------- | ----- | ----------------------------------------------------- |
| 1. The spec it implements is an RFC or a Final specification. | no    | QAuth defines the leg itself, in ADR-016 §4.          |
| 2. It has seen external use in a beta.                        | no    | No beta has run outside the project.                  |
| 3. The external audit covered it.                             | no    | The external audit of ADR-018 §8 has not taken place. |
| 4. Conformance tests exist for it.                            | no    | —                                                     |

### plugin-api

**The plugin API.** The AuthMethod contract as plugins see it, published as the npm package `@qauth-labs/plugin-sdk` with its contract test kit, so a plugin can live in its own repository. It is public and documented, so others can write plugins, but it may change in a minor release. It becomes stable in 1.x, after QAuth's own plugins have matured on it; those first-party plugins are part of 1.0.

- Decided in [ADR-018](/reference/records/adr/018-1-0-scope-and-stability/).
- Runs in: the auth server.
- Switch: `PLUGIN_API_ENABLED=true`.
- Discovery members: none.
- Spec: [The AuthMethod contract, ADR-018](https://docs.qauth.dev/reference/records/adr/018-1-0-scope-and-stability/), status `draft`.
- Built: yes. Stable: no.
- Documented in: [`/extend/auth-method-contract/`](/extend/auth-method-contract/).

| Condition                                                     | Holds | Evidence and notes                                                                                                |
| ------------------------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------- |
| 1. The spec it implements is an RFC or a Final specification. | no    | QAuth defines the contract itself; ADR-018 §4 makes it stable in 1.x.                                             |
| 2. It has seen external use in a beta.                        | no    | No beta has run outside the project.                                                                              |
| 3. The external audit covered it.                             | no    | The external audit of ADR-018 §8 has not taken place.                                                             |
| 4. Conformance tests exist for it.                            | no    | The contract test kit (#599) checks a method against the contract; no conformance test covers the plugin API yet. |

---

# Interaction API

URL: https://docs.qauth.dev/reference/interaction-api/

<!-- Generated by `pnpm exec nx run shared-interaction-contract:contract-export` from libs/shared/interaction-contract. Do not edit by hand. -->

The Interaction API is how a sign-in page reaches the QAuth engine ([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/), Decision 6). The reference ceremony app, and any UI that replaces it, reads the current step of an interaction, answers it and follows the result, until the interaction ends in a redirect. It shares its step grammar with the FiPA authorization challenge endpoint, the transport for first-party native apps ([ADR-017](/reference/records/adr/017-first-party-login/), Decision 3): a step is the same object on both, and only the envelope differs.

Status: this is the contract, published before the implementation. The auth server serves the document today; the operations it describes arrive with the Interaction API implementation.

The contract is one OpenAPI 3.1 document, [openapi.json](/interaction/v1-rc.0/openapi.json), and one JSON Schema per step, under `/interaction/v1-rc.0/steps/`. The auth server serves the same document at `/interaction/v1-rc.0/openapi.json`. The typed client in `libs/shared/interaction-client` is generated from it. Both are generated from `libs/shared/interaction-contract`, and the stable-surface check compares them with the last release ([ADR-018](/reference/records/adr/018-1-0-scope-and-stability/) §5).

## Rules

- Browser-facing and same-origin. A page calls the API on the realm origin it was served from. A flow cookie (`__Host-qauth_flow`) and a CSRF value protect it, and the server sends no CORS headers.
- Typed data from the auth server’s own records, never HTML. Every string a response carries is an enum, a constant or a bounded value with a pattern. A display value has no markup bracket, no control, format, private-use or unassigned character, no line separator, and no space at either end.
- No URL carries `return_to`, a redirect or a client parameter. A page reads one opaque interaction id from its own URL, and the client, the redirect target and everything else it shows come from the API.
- The interaction id alone reads the current step, with no personal data. Personal data, such as the account chooser’s list, needs the flow cookie and a same-origin request. Answering a step or cancelling the interaction needs the flow cookie, the step’s CSRF value and a same-origin request.
- Every operation answers with `Cache-Control: no-store`.

## Versioning

- The path carries the major version. Until QAuth 1.0.0 it is a release candidate, `/interaction/v1-rc.<M>` (today `/interaction/v1-rc.0`), and nothing about it is promised: a breaking change raises `<M>`. The release that ships 1.0.0 serves `/interaction/v1`.
- Within a major version, changes are additive only: new operations, new steps, new optional request members, new response members, and new values of an extensible set (step names, problem codes, fonts).
- A client ignores response members it does not know, and a page shows its error page for a step it does not know. A request with a member the operation does not declare is refused.
- The published schemas close response objects (`additionalProperties: false`) to describe this version exactly. A later version may add members, so a client must not validate responses strictly against an older schema, and ignores the members it does not know.
- Removing or renaming a member, changing a type, tightening validation, changing a status code, removing an operation or a step, and adding to a closed set, such as a step’s errors, need a new major version.
- A successor major version is served beside the previous one for at least 12 months, and the previous one stays until the next major release of QAuth.
- A step is named `urn:qauth:ia:<name>:v1-rc.<M>` until 1.0.0 and `urn:qauth:ia:<name>:v1` from then on, with the same release candidate as the path. QAuth never renames a step; if a registry of standard step names appears, its names are added beside QAuth’s.

## Operations

Every operation sits under `/interaction/v1-rc.0`. The flow cookie is `__Host-qauth_flow`. An operation's success and error responses are listed in the document, each error with the codes it may carry.

| Operation                                  | Request                                             | Flow cookie | CSRF value | Success  | Errors                                      |
| ------------------------------------------ | --------------------------------------------------- | ----------- | ---------- | -------- | ------------------------------------------- |
| Read the current step                      | `GET /interaction/v1-rc.0/{interactionId}`          | No          | No         | 200      | 410, 421, 429, 500, 503                     |
| Read the personal data of the current step | `GET /interaction/v1-rc.0/{interactionId}/personal` | Yes         | No         | 200      | 403, 410, 421, 429, 500, 503                |
| Answer the current step                    | `POST /interaction/v1-rc.0/{interactionId}/answer`  | Yes         | Yes        | 200, 303 | 400, 403, 410, 413, 415, 421, 429, 500, 503 |
| Cancel the interaction                     | `POST /interaction/v1-rc.0/{interactionId}/cancel`  | Yes         | Yes        | 200, 303 | 400, 403, 410, 413, 415, 421, 429, 500, 503 |

An answer is `application/json` or a plain HTML form post (`application/x-www-form-urlencoded`) with the same members, so the password, email-code and TOTP steps work without JavaScript. A JSON answer gets one of two results:

- **Next step** (`"result": "step"`): the interaction as a step read now returns it. A refused answer, such as a wrong password, gets the same step back with its `error` set and a new CSRF value. An answer after which the sign-in starts again at its first step, because the engine ended its transaction, gets that first step with a `notice` saying why: `code_burned`, `subject_mismatch`, `expired`.
- **Final redirect** (`"result": "redirect"`): the `location` the browser goes to, taken from the interaction record and the realm, never from the request.

A form post gets the same as a `303 See Other`. Anything the API refuses is an **error**: a problem document (below).

A `notice` is carried once: by the result of the JSON answer, or, after a form post, by the next step read; every later read carries none. It names no account, and before a factor succeeded it is the same for every identifier (ADR-017 Decision 4). An upstream provider that did not sign the person in, and a refused upstream link, come back the same way, as the `upstream` and `upstream_link` steps' `error` (#1081): the auth server shows no page of its own for them.

## Steps

Each step is named `urn:qauth:ia:<name>:v1-rc.0`. A step read names the current step (`step`), the other steps the engine accepts next (`alternatives`), their params keyed by step name (`params`) and, after a refused answer, the reason (`error`): the shape of the FiPA endpoint's answer, so a new step is a new name and a new member, not a break. A step's params are what any reader of the interaction id may see; its personal data needs the flow cookie. Each step's schema file holds the whole step as one record (params, answer, personal data, errors and `amr`) with its example, which the implementation reuses as a test vector. The params and answer fields keep the step grammar's names on both transports, which is why they are `snake_case` while the envelope is `camelCase`.

| Step                                  | Transports      | Answer fields            | Errors                                                        | `amr`        | Personal data                              |
| ------------------------------------- | --------------- | ------------------------ | ------------------------------------------------------------- | ------------ | ------------------------------------------ |
| [`identifier`](#identifier)           | Both            | `login_hint`             | —                                                             | —            | `login_hint`                               |
| [`password`](#password)               | Both            | `password`, `login_hint` | `invalid_credentials`                                         | `pwd`        | `identifier`                               |
| [`email_code`](#email_code)           | Both            | `otp`                    | `invalid_credentials`, `code_expired`                         | —            | `identifier`                               |
| [`new_password`](#new_password)       | Both            | `new_password`           | `password_rejected`                                           | —            | `identifier`                               |
| [`password_reset`](#password_reset)   | Both            | `login_hint`             | —                                                             | —            | —                                          |
| [`captcha`](#captcha)                 | Both            | `captcha_token`          | `captcha_failed`                                              | —            | —                                          |
| [`webauthn_get`](#webauthn_get)       | Both            | `webauthn_response`      | `invalid_credentials`                                         | `pop`, `mfa` | `identifier`                               |
| [`webauthn_create`](#webauthn_create) | Both            | `webauthn_response`      | `invalid_credentials`                                         | —            | `identifier`, `user`, `excludeCredentials` |
| [`totp`](#totp)                       | Both            | `otp`                    | `invalid_credentials`                                         | `otp`        | `identifier`                               |
| [`recovery_code`](#recovery_code)     | Interaction API | `recovery_code`          | `invalid_credentials`                                         | —            | `identifier`                               |
| [`recovery_codes`](#recovery_codes)   | Interaction API | `acknowledged`           | —                                                             | —            | `codes`                                    |
| [`totp_setup`](#totp_setup)           | Interaction API | `otp`                    | `invalid_credentials`                                         | —            | `identifier`, `secret`, `otpauth_uri`      |
| [`consent`](#consent)                 | Interaction API | `decision`, `remember`   | —                                                             | —            | `identifier`                               |
| [`select_account`](#select_account)   | Interaction API | `account`                | `account_unavailable`                                         | —            | `accounts`                                 |
| [`upstream`](#upstream)               | Interaction API | `provider`               | `provider_unavailable`, `provider_declined`, `provider_error` | —            | —                                          |
| [`upstream_link`](#upstream_link)     | Interaction API | `decision`               | `already_linked`, `provider_linked`, `account_unavailable`    | —            | —                                          |
| [`register`](#register)               | Interaction API | —                        | —                                                             | —            | —                                          |
| [`sign_in`](#sign_in)                 | Interaction API | —                        | —                                                             | —            | —                                          |
| [`device_code`](#device_code)         | Interaction API | `user_code`              | `invalid_user_code`                                           | —            | —                                          |
| [`device_confirm`](#device_confirm)   | Interaction API | `decision`               | —                                                             | —            | `location`, `network`, `user_agent`        |
| [`logout_confirm`](#logout_confirm)   | Interaction API | `decision`               | —                                                             | —            | `accounts`                                 |

"Both" means the Interaction API and the FiPA endpoint. Where a step only the Interaction API serves would come next, the FiPA endpoint answers `redirect_to_web`.

### identifier

`urn:qauth:ia:identifier:v1-rc.0` — Asks who is signing in.

Identifier-first sign-in (ADR-020 §3). Every identifier, known or unknown, gets the same next step, so the screen reveals nothing about which accounts exist (ADR-017 Decision 4). Offered as an alternative of a later step, it is the account switch: answering it ends the interaction and starts a new one for the same authorization request, and the result is a redirect to the ceremony app’s page of the new interaction. Nothing proved for the first account carries over (#592). Beside `select_account` it is "Use another account", which ends no session: it adds an account, and the accounts the chooser lists stay signed in (ADR-019 Decision 3). Beside any other step it is "Not you?", which also signs the browser out of the account the screen shows, and of no other account, so that the next person or the next app on a shared device does not continue as that account; its label says that it signs out (#964). The account shown is the one a sign-in during the interaction proved, the signed-in user a consent is for or, while nobody has signed in during the interaction, the account the identifier the person gave names. Its sessions that end: the one a sign-in during the interaction started (#896); the session the browser was already signed in with when the interaction started, such as for a consent or a sign-in the app asked for again, when it is that account’s (#964); and, when the server can check the browser’s session cookie, the session it names if that belongs to the same account (a sign-in again in another tab). The cookie is cleared when it names one of them. A session of another account stays.

- Params: —
- Schema: [steps/identifier.json](/interaction/v1-rc.0/steps/identifier.json)

### password

`urn:qauth:ia:password:v1-rc.0` — Asks for the password.

The password factor. A rejected password, an unknown account and a disabled account give the same `invalid_credentials`, after the same timing floor (ADR-017 Decisions 3 and 4). Works without JavaScript: the form posts straight to the auth server with the step’s CSRF value (ADR-019 Decision 5).

- Params: —
- Schema: [steps/password.json](/interaction/v1-rc.0/steps/password.json)

### email_code

`urn:qauth:ia:email_code:v1-rc.0` — Asks for the code mailed to the account’s address.

An emailed code proves control of a mailbox: it verifies a password account and recovers an account. It is never a sign-in factor and adds no `amr` value (ADR-017 Decision 5). For `recovery`, an address that gets no mail (no account, or no password) gets a phantom code: the step comes with the same `expires_in` and `resend_after`, and its answers are refused with the same errors at the same times as a real code’s (`invalid_credentials` for a wrong code, `code_expired` once `expires_in` has passed), so neither error tells a known address from an unknown one. An answer with no `otp` asks for the code again. Works without JavaScript.

- Params: `purpose`, `length`, `expires_in`, `resend_after`
- Schema: [steps/email_code.json](/interaction/v1-rc.0/steps/email_code.json)

### new_password

`urn:qauth:ia:new_password:v1-rc.0` — Asks for a new password.

Sets a password through the one password policy (ADR-017 Decision 8): at registration, at the end of a reset, or when an admin or a breach-list match requires a new one (ADR-020 §3). The reasons of a refusal are returned, never prose. The page marks the field for password managers, with the identifier from the personal data as the username. Works without JavaScript.

- Params: `purpose`, `min_length`, `max_length`, `reasons`
- Schema: [steps/new_password.json](/interaction/v1-rc.0/steps/new_password.json)

### password_reset

`urn:qauth:ia:password_reset:v1-rc.0` — Starts a password reset.

A path marker: answering it starts a reset. The next step is `email_code` with `purpose` `recovery` for every address, known or not; mail goes only to a known address with a password. An unknown address gets a phantom code, with the same `expires_in` and `resend_after` and the same error sequence as a real one, so the reset says nothing about whether the address has an account. A reset never unlocks an account whose strongest authenticator is stronger than email (ADR-017 Decision 8).

- Params: —
- Schema: [steps/password_reset.json](/interaction/v1-rc.0/steps/password_reset.json)

### captcha

`urn:qauth:ia:captcha:v1-rc.0` — Asks for a bot challenge answer.

A bot challenge, when a soft threshold requires one; the pending step resumes after it (ADR-017 Decisions 4 and 7). By default the built-in proof of work, whose script the ceremony app serves from the realm origin. An operator may name a hosted provider for the sign-up and sign-in pages only (ADR-019 Decision 5). A required challenge needs JavaScript and is never skipped. The built-in proof of work (`provider` `pow`) is solved as follows. The answer, `captcha_token`, is a nonce: 1 to 16 ASCII digits `0` to `9`, with no sign and no leading zero (`0` itself is a nonce). The engine takes the SHA-256 digest of the UTF-8 bytes of the challenge, a colon and the nonce, `<challenge>:<nonce>`, with the challenge as the text it is, not base64url-decoded. It accepts the nonce when that digest starts with at least `difficulty` zero bits, read from the most significant bit of its first byte. Any such nonce passes; trying 0, 1, 2 and so on finds one after about 2^`difficulty` hashes. A puzzle takes one answer: a wrong nonce gets the step back with `captcha_failed` and a new challenge. A token the answer’s schema refuses is an invalid answer: it is not checked, and the challenge stays. QAuth’s shared test vectors, `test-vectors/interaction/proof-of-work.json` in its repository, hold cases to check a solver against.

- Params: `provider`, `challenge`, `difficulty`, or `provider`, `name`, `site_key`
- Schema: [steps/captcha.json](/interaction/v1-rc.0/steps/captcha.json)

### webauthn_get

`urn:qauth:ia:webauthn_get:v1-rc.0` — Asks for a passkey.

Passkey sign-in: the WebAuthn Level 3 request options as JSON, for `PublicKeyCredential.parseRequestOptionsFromJSON()`. Discoverable credentials only: the options never carry `allowCredentials`, so the step read reveals no account’s passkeys (ADR-017 Decision 4, ADR-019 Decision 6). The engine checks that the passkey belongs to the transaction’s account. The RP ID is the realm’s host (ADR-019 Decision 2). Needs JavaScript.

- Params: `challenge`, `rpId`, `timeout`, `userVerification`
- Schema: [steps/webauthn_get.json](/interaction/v1-rc.0/steps/webauthn_get.json)

### webauthn_create

`urn:qauth:ia:webauthn_create:v1-rc.0` — Offers or asks to create a passkey.

Passkey enrolment. `options` is the WebAuthn Level 3 creation options as JSON without `user` and `excludeCredentials`, which are the account’s own data and come with the personal data; the page joins the two for `PublicKeyCredential.parseCreationOptionsFromJSON()`. The RP ID is the realm’s host and locks at the first enrolment (ADR-019 Decision 2). Enrolment adds no `amr` value. Needs JavaScript.

- Params: `optional`, `options`
- Schema: [steps/webauthn_create.json](/interaction/v1-rc.0/steps/webauthn_create.json)

### totp

`urn:qauth:ia:totp:v1-rc.0` — Asks for the code of the authenticator app.

A TOTP second factor (RFC 6238) with the fixed parameters of ADR-020 §3: SHA-1, six digits, 30 seconds, one step of tolerance. An accepted code is never accepted twice (ADR-017 Decision 8). Works without JavaScript.

- Params: `digits`
- Schema: [steps/totp.json](/interaction/v1-rc.0/steps/totp.json)

### recovery_code

`urn:qauth:ia:recovery_code:v1-rc.0` — Asks for one of the account’s recovery codes.

A recovery code stands in for a second factor after the first, or for the passkey of a passkey-only account. Only the hosted pages redeem one; the FiPA endpoint answers `redirect_to_web` for that path. It adds no `amr` value and never `mfa`, so a policy that needs a second factor makes the person bind a new one before the transaction completes (ADR-017 Decisions 4 and 8). Works without JavaScript.

- Params: —
- Schema: [steps/recovery_code.json](/interaction/v1-rc.0/steps/recovery_code.json)

### recovery_codes

`urn:qauth:ia:recovery_codes:v1-rc.0` — Shows a new set of recovery codes once.

A new recovery-code set: issued at the first enrolment of a second factor, at the registration of a passkey-only account, and when the person regenerates the set (ADR-017 Decision 8). The codes are personal data: readable with the flow cookie while this step is current, and never after. The answer confirms the person saved them.

- Params: `count`
- Schema: [steps/recovery_codes.json](/interaction/v1-rc.0/steps/recovery_codes.json)

### totp_setup

`urn:qauth:ia:totp_setup:v1-rc.0` — Sets up an authenticator app.

TOTP enrolment, with the fixed parameters of ADR-020 §3. The secret is personal data: readable with the flow cookie while this step is current, and never after. It is bound only after a first valid code (ADR-017 Decision 8). A verified account binds its first TOTP after a fresh sign-in, with no code mailed to its address: the account decides, never a channel (Decision 8, amended 2026-11-08). An unclaimed account (a password account not yet verified) binds none. The step adds no `amr` value of its own, but the first valid code that binds the secret stands for the sign-in’s `totp` step: the sign-in it completes proves `otp`, with no second code asked. The page shows the secret as a QR code and as text.

- Params: `algorithm`, `digits`, `period`
- Schema: [steps/totp_setup.json](/interaction/v1-rc.0/steps/totp_setup.json)

### consent

`urn:qauth:ia:consent:v1-rc.0` — Asks the person to allow or deny what the client asks for.

The OAuth consent decision (#629). The interaction’s `client` names the client, verified domain first (ADR-019 Decision 6), and an AI agent is named as one in QAuth’s own words (ADR-014 §11). The grant is exactly the scope set shown here, which the interaction holds: the answer cannot add a scope. A dangerous scope and `prompt=consent` always reach this step, and an AI agent never skips it; a first-party client may skip it only through the administrative waiver (ADR-017 Decision 9). Works without JavaScript.

- Params: `scopes`, `resources`, `audience`, `agent`, `remember_default`
- Schema: [steps/consent.json](/interaction/v1-rc.0/steps/consent.json)

### select_account

`urn:qauth:ia:select_account:v1-rc.0` — Asks which signed-in account to continue with.

The account chooser for `prompt=select_account`, when the browser holds sessions for several accounts of the realm (ADR-019 Decision 3, ADR-020 §3). The list is personal data. "Use another account" answers the `identifier` step, offered beside this one: that starts a new interaction for the same authorization request, and the result is a redirect to its page (#592). It ends no session: the accounts the list shows stay signed in (#964). Needs JavaScript, to read the list.

- Params: —
- Schema: [steps/select_account.json](/interaction/v1-rc.0/steps/select_account.json)

### upstream

`urn:qauth:ia:upstream:v1-rc.0` — Offers sign-in through an upstream identity provider.

The person picks one of the realm’s upstream identity providers: generic OpenID Connect, or an AuthMethod plugin. It is offered beside the `identifier` step, before anyone is named, alike for every account (ADR-017 Decision 4); on the sign-in to the account an upstream identity joins (`upstream_link`), the provider being linked is left out (#1080). An answer names one provider of the list; the answer’s result is a redirect to the provider (`result: redirect`, or `303` to it for a form post). The provider sends the browser back to `/upstream/<provider>/callback` on the realm host, which checks the answer against the transaction kept server-side for this interaction and its flow cookie, signs in the account that holds that upstream identity, or, for an identity no account holds, asks at the `upstream_link` step whether it starts a new account or joins an existing one, and continues the interaction (on the sign-in to the account an identity joins, an identity no account holds signs in to nothing and creates nothing): the next step’s ceremony page, or the final redirect. A sign-in through a provider ranks with the password in the downgrade rule, below a passkey (ADR-017 Decision 4), and adds no `amr` value. A provider an operator hides is not listed here and stays reachable through the authorization request’s `qauth_upstream` parameter. When the provider does not sign the person in, its callback sends the browser back to the ceremony page, nothing goes to the client, and this step is the current one again, with the other ways in as its alternatives, its `error` and the provider in `error_provider` (#1081): `provider_declined`, the person cancelled or refused at the provider (OAuth `access_denied`); `provider_error`, the provider answered another error. An answer naming a provider that cannot be started is refused with `provider_unavailable`. Any other failure of the callback, a provider switched off before its answer came back among them, is an error page with the request’s trace id. Works without JavaScript: each provider is a button of a plain form post.

- Params: `providers`, `error_provider`
- Schema: [steps/upstream.json](/interaction/v1-rc.0/steps/upstream.json)

### upstream_link

`urn:qauth:ia:upstream_link:v1-rc.0` — Asks whether an upstream identity QAuth does not know starts a new account or joins an existing one.

Shown once an upstream identity provider proved an identity no account of the realm holds (#670; ADR-020 §3). The person picks a new account with that identity, which is offered only where the realm allows sign-up and the new account can be verified (`create`), or the account they already have, which they then sign in to in this interaction under its MFA policy: the `identifier` step, and every step that account’s sign-in asks for. That sign-in offers the realm’s other upstream providers beside its first step, never the one being linked (#1080): one proves the account only through an identity the account already holds, a passkey the account holds is still asked for after it, and an identity no account holds signs in to nothing and creates nothing. No password reset is offered. The identity joins that account only once that sign-in completes, in the same browser and the same interaction. A link refused when it would be written comes back to this step with its reason as `error`, the reason `user.upstream_link_failed` records (#1081): `already_linked`, another account holds the identity; `provider_linked`, the account signed in to already holds an identity of this provider; `account_unavailable`, that account can no longer take a link. Nothing was linked and nothing went to the client. The step then offers no choice: `create` is `false`, an answer is refused with `invalid_answer`, and the page says why and offers the cancel, which ends the authorization request with `access_denied` (an account page’s link goes back to its page). Where the sign-in to the account had already finished the interaction, the step is the first of a new interaction for the same request, and the answer that finished it leads to that interaction’s ceremony page. Nothing on the step names the identity or the account: no address and no hint, and no account is ever found by an attribute such as an email address. Works without JavaScript: each choice is a button of a plain form post.

- Params: `provider`, `create`
- Schema: [steps/upstream_link.json](/interaction/v1-rc.0/steps/upstream_link.json)

### register

`urn:qauth:ia:register:v1-rc.0` — Turns a sign-in into a registration.

A path marker (#1079): answering it turns the sign-in into a registration in the same interaction, for the same authorization request, at the registration’s first round, as `prompt=create` (OpenID Connect Prompt Create 1.0) would have started it (ADR-017 Decision 8): the `captcha` step first where the realm or the client requires one, then the address step (`identifier`), with a passkey to create the account with before it while passkey sign-in is on, and `sign_in` beside it. The request the interaction holds does not change, and the registration ends as one `prompt=create` started: in a code for that request, with no `amr` and no `auth_time`. Offered as an alternative of a sign-in’s first step, before anyone is named, alike for every account (ADR-017 Decision 4), and only while the realm allows sign-up (`accounts.allowSignUp`), the client’s operator-set `hosted_flows` name `register` and the request carries no `max_age` and no `prompt=login`: the rules `prompt=create` meets at the authorization endpoint, but for the `openid` scope, which only `prompt=create` needs. Never offered on a sign-in to join an upstream identity to an account (`upstream_link`) nor on the account page’s sign-in. The rules are read again on every round: an answer to it once they no longer hold is refused with `invalid_answer`, and the sign-in stays where it was. The page shows it as “Create an account”. Works without JavaScript.

- Params: —
- Schema: [steps/register.json](/interaction/v1-rc.0/steps/register.json)

### sign_in

`urn:qauth:ia:sign_in:v1-rc.0` — Turns a registration back into a sign-in.

A path marker (#1079), the way back from `register`: answering it turns the registration into a sign-in in the same interaction, for the same authorization request, at the sign-in’s first round: the `identifier` step, with a passkey before it while passkey sign-in is on and the realm’s upstream providers beside it. Offered as an alternative of a registration’s address step, before anyone is named and before any mailbox is proved, whether the registration began with `prompt=create` or with `register`. Nothing the registration kept carries over: the sign-in starts empty. After the mailbox is proved, an address an account holds goes on to that account’s sign-in by itself, as before. The page shows it as “I have an account”. Works without JavaScript.

- Params: —
- Schema: [steps/sign_in.json](/interaction/v1-rc.0/steps/sign_in.json)

### device_code

`urn:qauth:ia:device_code:v1-rc.0` — Asks for the code the device shows.

Code entry for the OAuth 2.0 device authorization grant (RFC 8628 §3.3). Unknown, expired and used codes give the same `invalid_user_code`. Entry is rate-limited per code, per session and per address. A person who arrives through `verification_uri_complete` skips this step and still confirms on `device_confirm` (ADR-020 §3). Works without JavaScript.

- Params: `length`
- Schema: [steps/device_code.json](/interaction/v1-rc.0/steps/device_code.json)

### device_confirm

`urn:qauth:ia:device_confirm:v1-rc.0` — Asks the person to confirm the device in front of them.

The explicit confirmation of a device authorization, always asked, also after `verification_uri_complete` (ADR-020 §3). The screen warns that nobody else should have given the person the code, and shows where the request came from: the requesting device’s approximate location, network and user agent, which are personal data, and its start time. The consent step always follows, even for a client that may skip consent elsewhere. The device details come with the personal data, so this step needs JavaScript: a page shows them before it offers `confirm`.

- Params: `user_code`, `requested_at`
- Schema: [steps/device_confirm.json](/interaction/v1-rc.0/steps/device_confirm.json)

### logout_confirm

`urn:qauth:ia:logout_confirm:v1-rc.0` — Asks the person to confirm signing out.

The confirmation of an RP-initiated logout (ADR-019 Decision 4). The interaction’s `client` names the app that asked, when the request identified one. A browser may hold several accounts’ sessions, so the person signs out of this account or of every account on the browser (ADR-019 Decision 3). Works without JavaScript, without the account list.

- Params: —
- Schema: [steps/logout_confirm.json](/interaction/v1-rc.0/steps/logout_confirm.json)

## Brand

Every step read carries the realm's `brand`: the theme tier of ADR-019 Decision 5. It holds a logo an admin uploaded (served from the realm origin), light and dark colours, a font from the safe list (`system`, `inter`, `noto_sans`, `atkinson_hyperlegible`, `ibm_plex_sans`, `source_sans_3`), links to the terms, the privacy notice and help, the realm's strings by locale, and whether dark mode is enabled. There are no uploaded templates, CSS or script. A realm that set nothing gets the defaults: `system` and dark mode enabled, and every member left out keeps the ceremony app's own value.

## Errors

An error is an RFC 9457 problem details document (`application/problem+json`) with a stable `code` and a `trace_id`, as on the other API families ([API conventions](/reference/api-conventions/#errors)). Its `type` and `title` are the code's entry on [Problem types](/reference/problem-types/). It carries no `detail`, `instance` or `errors` list: a page shows its own text for the code, with the trace id. A page treats a code it does not know by its HTTP status.

| Code                     | Status | Meaning                                                                                                                                                                                              |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bad_request`            | 400    | The request is malformed and no more specific code applies.                                                                                                                                          |
| `invalid_answer`         | 400    | The answer does not match the schema of the step it names, names a step the interaction does not offer, or repeats a field. The engine was not called.                                               |
| `forbidden`              | 403    | The request is not same-origin, or its CSRF value is missing, already used or not the current step’s. The engine was not called.                                                                     |
| `interaction_expired`    | 410    | The interaction is unknown, expired or finished, the flow cookie does not belong to it, or a finish came after the browser session its sign-in started had ended. Every reason gets this one answer. |
| `content_too_large`      | 413    | The request body is larger than the server accepts.                                                                                                                                                  |
| `unsupported_media_type` | 415    | The request body is neither `application/json` nor `application/x-www-form-urlencoded`.                                                                                                              |
| `misdirected_request`    | 421    | The server does not answer for the host the request names.                                                                                                                                           |
| `too_many_requests`      | 429    | Too many requests. `Retry-After` says when to try again.                                                                                                                                             |
| `internal_error`         | 500    | The server failed. `trace_id` finds the failure in the server log.                                                                                                                                   |
| `service_unavailable`    | 503    | The server cannot answer now, for example while a store the engine needs is down. It fails closed.                                                                                                   |

## Paths

- The prefix `/interaction/v1-rc.0/wallet/` is reserved for the wallet return leg (ADR-013). No operation of this document is served under it.
- The auth server serves this document at `/interaction/v1-rc.0/openapi.json`.

## Replacement apps

A sign-in UI that replaces the reference ceremony app and follows this contract is a supported setup (#618). Beside the contract, it needs:

- **A typed client.** Generate one from [openapi.json](/interaction/v1-rc.0/openapi.json) with any OpenAPI 3.1 client generator, and generate it again when the path's release candidate changes. QAuth's own client, `libs/shared/interaction-client`, is generated the same way, for the reference ceremony app. It is not published as a package, and neither is its proof-of-work solver: the SDKs QAuth publishes are those of [ADR-018](/reference/records/adr/018-1-0-scope-and-stability/#6-sdks-and-the-rust-core) §6, and what this API promises is its document and its step schemas, not a client library.
- **A solver for the built-in proof of work.** The [`captcha`](#captcha) step states its rule, which is all a solver needs. Check a solver against `test-vectors/interaction/proof-of-work.json`, the shared test vectors QAuth's own check and solver run.
- **A hosted provider's script**, when the operator named a hosted provider for the bot challenge: the provider's own, loaded from the script hosts the operator listed (ADR-019 Decision 5).

---

# SSF events

URL: https://docs.qauth.dev/reference/ssf-events/

<!-- Generated by `pnpm exec nx run shared-events:schema-export` from libs/shared/events. Do not edit by hand. -->

QAuth's [SSF transmitter](/operate/ssf-transmitter/) sends the events that record a security
change to receivers' streams, as Security Event Tokens (SETs, RFC 8417). Each is sent as a CAEP 1.0
or RISC 1.0 event where one says the same thing, and as a QAuth-defined event where none does.
Resource servers and relying parties use them to stop honouring a revoked session, grant or
credential before its tokens expire ([ADR-019 Decision 8](/reference/records/adr/019-deployment-topology-and-trust-boundaries/)).

The [event registry](/reference/events/) marks every type that records a security change: a
session, a grant, a token, a credential, a key or an account that a receiver may have to act on.
Each security type declares the SSF event it is sent as, or that it has none; the registry's test
fails when one declares neither, so no feature adds a security event and forgets SSF. This page is
generated from those declarations.

## The SET

A SET carries one event and these claims:

- `iss`: the realm's issuer; `aud`: the receiver's `client_id`.
- `jti`: the event's id, and `iat`: the event's time, in seconds. A retry sends the same SET,
  so a receiver drops a duplicate by its `jti`.
- `sub_id`: the subject (SSF 1.0 §3, RFC 9493), as below.
- `events`: one member, keyed by the SSF event's URI.

It carries no `sub` and no `exp` (SSF 1.0 §4.1.2, §4.1.7). Its header names the signing key
(`kid`) and `typ: secevent+jwt`; the keys are at the transmitter's `jwks_uri`.

## Common members

Every mapped event carries `event_timestamp`, the time the event happened in seconds (CAEP
1.0 §2). It carries `initiating_entity` when QAuth knows who invoked it: `user` for a person acting on their own account, `admin` for an administrator (a person acting on an admin event, or an operator on the server host), and `system` for QAuth itself. A client acting for itself names none.
A mapping may fix it instead, as the replay policy does.

## Subjects

- A user is `iss_sub`: the realm's issuer and the user's id.
- A user's session is a `complex` subject (SSF 1.0 §3.2): `user` as above, and `session` as
  `opaque` with the session id, the `sid` the user's ID tokens carry. A `user.signed_out`
  that ended one session names it so, and a receiver ends that session alone; one that ended every
  session of the user names the user alone. A stream that added the user receives both.
- A client is `uri` when its `client_id` is an absolute URI, as an agent client's Client ID
  Metadata Document URL is, and `opaque` with the `client_id` otherwise.
- A key is `opaque` with its `kid`.

The transmitter's `default_subjects` is `NONE`: a stream receives an event only when it
requested the event and its receiver added the subject, except an event about a key, which every
stream of the realm that requested it receives. An event marked as going to the event's client
reaches only the stream whose receiver is that client: it tells of the user's dealings with that
one client, which another receiver has no need to see.

A receiver may add a user only when the user is related to it: the user has an active consent for
the receiver's client or a live refresh token it was issued, or, for a receiver that serves as a
resource server, a live refresh token whose audience names it. Any other user, and a user id that
does not exist, is refused with `403`, as SSF 1.0 §8.1.3.2 prescribes for a subject the receiver
may not add. A user subject lasts as long as its relation: the hourly `ssf-subject-sweep` job
deletes it once the relation has ended and every event about the user has reached the stream, so
the SET that tells of the end still arrives. A disabled user is related to no receiver, so after
`account-disabled` reaches a stream the sweep deletes the user's subject there, and
`account-enabled` reaches only a stream the sweep has not cleared yet: once the user is enabled,
the receiver adds them again. The [SSF transmitter](/operate/ssf-transmitter/) guide gives the
whole rule.

## Mapping

| QAuth event type                                                          | SSF event                                                 | Subject                               | Delivered to                                                | Members besides `event_timestamp`                                                                                                                              |
| ------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`user.signed_out`](/reference/events/#usersigned_out-v1-rc0)             | `session-revoked` (CAEP 1.0 §3.1)                         | the user, `iss_sub` or `complex`      | every stream that added the subject                         | `initiating_entity` from the actor                                                                                                                             |
| [`user.password_reset`](/reference/events/#userpassword_reset-v1-rc0)     | `credential-change` (CAEP 1.0 §3.3)                       | the user, `iss_sub`                   | every stream that added the subject                         | `credential_type`: `"password"`; `change_type`: `"update"`; `initiating_entity` from the actor                                                                 |
| [`user.disabled`](/reference/events/#userdisabled-v1-rc0)                 | `account-disabled` (RISC 1.0 §2.3)                        | the user, `iss_sub`                   | every stream that added the subject                         | `initiating_entity` from the actor                                                                                                                             |
| [`user.enabled`](/reference/events/#userenabled-v1-rc0)                   | `account-enabled` (RISC 1.0 §2.4)                         | the user, `iss_sub`                   | every stream that added the subject                         | `initiating_entity` from the actor                                                                                                                             |
| [`user.password_changed`](/reference/events/#userpassword_changed-v1-rc0) | `credential-change` (CAEP 1.0 §3.3)                       | the user, `iss_sub`                   | every stream that added the subject                         | `credential_type`: `"password"`; `change_type`: `"update"`; `initiating_entity` from the actor                                                                 |
| [`consent.revoked`](/reference/events/#consentrevoked-v1-rc0)             | `token-claims-change` (CAEP 1.0 §3.2)                     | the user, `iss_sub`                   | the stream of the event’s client, when it added the subject | `claims`: `{"scope":""}`; `initiating_entity` from the actor                                                                                                   |
| [`token.family_revoked`](/reference/events/#tokenfamily_revoked-v1-rc0)   | `session-revoked` (CAEP 1.0 §3.1)                         | the user, `iss_sub`                   | the stream of the event’s client, when it added the subject | `reason_admin`: by `data.reason`; `initiating_entity`: `"policy"`                                                                                              |
| [`token.revoked`](/reference/events/#tokenrevoked-v1-rc0)                 | [`token-revoked`](#token-revoked) (QAuth)                 | the user, `iss_sub`                   | the stream of the event’s client, when it added the subject | `token_type_hint`: `data.typeHint`; `initiating_entity` from the actor                                                                                         |
| [`client.secret_rotated`](/reference/events/#clientsecret_rotated-v1-rc0) | `credential-change` (CAEP 1.0 §3.3)                       | the client, `uri` or `opaque`         | the stream of the event’s client, when it added the subject | `credential_type`: `"client-secret"`; `change_type`: `"update"`; `initiating_entity`: `"admin"`                                                                |
| [`api_key.created`](/reference/events/#api_keycreated-v1-rc0)             | `credential-change` (CAEP 1.0 §3.3)                       | the event’s client, `uri` or `opaque` | the stream of the event’s client, when it added the subject | `credential_type`: `"api-key"`; `change_type`: `"create"`; `initiating_entity`: `"admin"`                                                                      |
| [`api_key.revoked`](/reference/events/#api_keyrevoked-v1-rc0)             | `credential-change` (CAEP 1.0 §3.3)                       | the event’s client, `uri` or `opaque` | the stream of the event’s client, when it added the subject | `credential_type`: `"api-key"`; `change_type`: `"revoke"`; `initiating_entity`: `"admin"`                                                                      |
| [`wallet.linked`](/reference/events/#walletlinked-v1-rc0)                 | `credential-change` (CAEP 1.0 §3.3)                       | the user, `iss_sub`                   | every stream that added the subject                         | `credential_type`: `"verifiable-credential"`; `change_type`: by `data.rebound` (`true` → `"update"`, `false` → `"create"`); `initiating_entity` from the actor |
| [`key.emergency_retired`](/reference/events/#keyemergency_retired-v1-rc0) | [`key-emergency-retired`](#key-emergency-retired) (QAuth) | the key, `opaque` with its `kid`      | every stream of the realm that requested it                 | `kid`: `data.keyId`; `purpose`: `data.purpose`; `initiating_entity` from the actor                                                                             |

Notes on the mapping:

- [`user.disabled`](/reference/events/#userdisabled-v1-rc0): Sent without `reason`: RISC 1.0 names only `hijacking` and `bulk-account`, and QAuth records no reason for the switch.
- [`consent.revoked`](/reference/events/#consentrevoked-v1-rc0): A withdrawn consent covered every scope the client held for the user, so the `scope` of its tokens for that user is now empty, and QAuth revoked the refresh tokens the consent covered.
- [`token.family_revoked`](/reference/events/#tokenfamily_revoked-v1-rc0): A refresh family is the client’s standing session for the user, so its revocation is `session-revoked`. The replay policy revoked it, so `initiating_entity` is `policy`.
- [`token.revoked`](/reference/events/#tokenrevoked-v1-rc0): Sent only when the revoked token was a user’s: the event’s subject. A revocation that matched no token of the client, or a refresh token whose family was revoked already, records the event without one, and no stream receives it.
- [`client.secret_rotated`](/reference/events/#clientsecret_rotated-v1-rc0): Sent only to the stream of the client whose credential changed, never to another receiver that added that client: a receiver learns of its own credentials only. A developer managing a client acts as its administrator, so `initiating_entity` is `admin`.
- [`api_key.created`](/reference/events/#api_keycreated-v1-rc0): Sent only to the stream of the client whose credential changed, never to another receiver that added that client: a receiver learns of its own credentials only. A developer managing a client acts as its administrator, so `initiating_entity` is `admin`.
- [`api_key.revoked`](/reference/events/#api_keyrevoked-v1-rc0): Sent only to the stream of the client whose credential changed, never to another receiver that added that client: a receiver learns of its own credentials only. A developer managing a client acts as its administrator, so `initiating_entity` is `admin`.
- [`key.emergency_retired`](/reference/events/#keyemergency_retired-v1-rc0): Defined ahead of emergency retirement itself (#551), which emits it; nothing emits it before then.

## Security events with no SSF event

| QAuth event type                                                                              | Why it has no SSF event                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`user.client_session_ended`](/reference/events/#userclient_session_ended-v1-rc0)             | The end of a session is user.signed_out, sent as CAEP 1.0 `session-revoked`. This event is the per-client notice of OpenID Connect Back-Channel Logout 1.0, delivered as a logout token to the client, not as a SET.                                                                                                                                          |
| [`user.recovery_code_used`](/reference/events/#userrecovery_code_used-v1-rc0)                 | CAEP 1.0 has no event for a sign-in that used a fallback authenticator, and `credential-change` is for a credential created, revoked, updated or deleted: a used code is spent, not changed.                                                                                                                                                                  |
| [`user.recovery_codes_failed`](/reference/events/#userrecovery_codes_failed-v1-rc0)           | Neither CAEP 1.0 nor RISC 1.0 has an event for failed attempts at an account’s credential: the account is not disabled and no credential changed.                                                                                                                                                                                                             |
| [`user.upstream_linked`](/reference/events/#userupstream_linked-v1-rc0)                       | CAEP 1.0 `credential-change` names its credential by a type it lists (a password, a FIDO key, a verifiable credential), and none is an identity at another provider; no type is agreed with receivers yet.                                                                                                                                                    |
| [`user.upstream_unlinked`](/reference/events/#userupstream_unlinked-v1-rc0)                   | CAEP 1.0 `credential-change` names its credential by a type it lists (a password, a FIDO key, a verifiable credential), and none is an identity at another provider; no type is agreed with receivers yet.                                                                                                                                                    |
| [`user.upstream_link_failed`](/reference/events/#userupstream_link_failed-v1-rc0)             | Nothing changed: no credential was created, changed or deleted.                                                                                                                                                                                                                                                                                               |
| [`user.credential_added`](/reference/events/#usercredential_added-v1-rc0)                     | CAEP 1.0 `credential-change` tells a platform passkey (`fido2-platform`) from a roaming one (`fido2-roaming`), and QAuth does not record which kind of authenticator created a passkey.                                                                                                                                                                       |
| [`user.credential_removed`](/reference/events/#usercredential_removed-v1-rc0)                 | CAEP 1.0 `credential-change` tells a platform passkey (`fido2-platform`) from a roaming one (`fido2-roaming`), and QAuth does not record which kind of authenticator created a passkey.                                                                                                                                                                       |
| [`user.recovery_codes_regenerated`](/reference/events/#userrecovery_codes_regenerated-v1-rc0) | CAEP 1.0 `credential-change` lists no credential type for a set of recovery codes, and none is agreed with receivers yet.                                                                                                                                                                                                                                     |
| [`user.verified`](/reference/events/#userverified-v1-rc0)                                     | Neither CAEP 1.0 nor RISC 1.0 defines an event for an account an operator verified, and none is agreed with receivers yet.                                                                                                                                                                                                                                    |
| [`step_up.elevated`](/reference/events/#step_upelevated-v1-rc0)                               | CAEP 1.0 §3.4 `assurance-level-change` signals that the authentication method changed, and needs the level before and after in a namespace. QAuth’s step-up asks for a fresh sign-in with the same method and records no assurance level, so that event would say nothing true. It maps once step-up can raise the level, with passkeys or TOTP (ADR-018 §3). |
| [`client.deleted`](/reference/events/#clientdeleted-v1-rc0)                                   | No CAEP 1.0 or RISC 1.0 event describes a client’s suspension or deletion: RISC `account-disabled` is about an account a person signs in to.                                                                                                                                                                                                                  |
| [`client.suspended`](/reference/events/#clientsuspended-v1-rc0)                               | No CAEP 1.0 or RISC 1.0 event describes a client’s suspension or deletion: RISC `account-disabled` is about an account a person signs in to.                                                                                                                                                                                                                  |
| [`client.suspension_lifted`](/reference/events/#clientsuspension_lifted-v1-rc0)               | No CAEP 1.0 or RISC 1.0 event describes a client’s suspension or deletion: RISC `account-disabled` is about an account a person signs in to.                                                                                                                                                                                                                  |
| [`client.first_party_changed`](/reference/events/#clientfirst_party_changed-v1-rc0)           | No CAEP 1.0 or RISC 1.0 event describes a change of trust in a client. The tokens the removal revoked were the client’s, not a person’s session.                                                                                                                                                                                                              |
| [`client.verified_domain_changed`](/reference/events/#clientverified_domain_changed-v1-rc0)   | No CAEP 1.0 or RISC 1.0 event describes a change of trust in a client: it changes what screens show about the client, not a person’s session or credentials.                                                                                                                                                                                                  |

## QAuth-defined events

Where no CAEP 1.0 or RISC 1.0 event says what happened, QAuth defines one. Its identifier is
`urn:qauth:secevent:<name>:v<N>`, a URN rather than a URL so that it never looks like a standard
event, and versioned so that a standard one can later sit beside it (ADR-018 §5). Until QAuth 1.0.0
every QAuth-defined identifier is a release candidate, `:v<N>-rc.<M>`, and nothing about it is
promised: a breaking change raises `<M>`. The release that ships 1.0.0 drops the suffix. A
receiver ignores members it does not know (SSF 1.0 §4.2.3).

### token-revoked

- Identifier: `urn:qauth:secevent:token-revoked:v1-rc.0`
- Sent for: [`token.revoked`](/reference/events/#tokenrevoked-v1-rc0)

A client revoked a token of the subject at the RFC 7009 revocation endpoint. The SET goes to the stream of that client only. QAuth defines it because no CAEP event matches: `session-revoked` would say the whole session ended, and `credential-change` is about a credential the subject authenticates with.

| Member              | Required | Meaning                                                                                   |
| ------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `event_timestamp`   | yes      | When the event happened, in seconds since the epoch (CAEP 1.0 §2).                        |
| `initiating_entity` | no       | Who invoked it, as CAEP 1.0 §2 names it; see [Common members](#common-members).           |
| `token_type_hint`   | no       | The `token_type_hint` the client sent, such as `refresh_token`. Absent when it sent none. |

### key-emergency-retired

- Identifier: `urn:qauth:secevent:key-emergency-retired:v1-rc.0`
- Sent for: [`key.emergency_retired`](/reference/events/#keyemergency_retired-v1-rc0)

An operator retired a key of the realm that may be compromised (ADR-019 Decision 9). It left the JWKS at once and no verifier in the auth server accepts it. A verifier drops the key the SET names. The subject is the key, as an `opaque` identifier holding its `kid`, and every stream of the realm that requested the event receives it.

| Member              | Required | Meaning                                                                         |
| ------------------- | -------- | ------------------------------------------------------------------------------- |
| `event_timestamp`   | yes      | When the event happened, in seconds since the epoch (CAEP 1.0 §2).              |
| `initiating_entity` | no       | Who invoked it, as CAEP 1.0 §2 names it; see [Common members](#common-members). |
| `kid`               | yes      | The `kid` of the retired key.                                                   |
| `purpose`           | no       | What the key was for, such as `token_signing`.                                  |

---

# Admin permissions

URL: https://docs.qauth.dev/reference/admin-permissions/

<!-- Generated from apps/auth-server/src/app/helpers/admin-permissions.ts by its tests. Do not edit by hand: change the registry and run `pnpm nx test auth-server -- -u`. -->

The admin API is to authorize each request by scope and by role
([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/), Decision 7).
A role grants permissions. The token's scopes decide which classes of those permissions this
token may use. This page lists the scopes, every permission and the built-in roles, and states
the rule the admin API will enforce. No admin API route reads the catalog yet, so the rule
protects nothing today; the `qauth:` scope namespace is already reserved, as listed below. The page is
generated from the registry in `apps/auth-server/src/app/helpers/admin-permissions.ts`.

## Scopes

| Scope                  | Allows               | Meaning                                                                                                                                                |
| ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `qauth:admin:read`     | read permissions     | Reads configuration and state. Changes nothing.                                                                                                        |
| `qauth:admin:write`    | write permissions    | Changes display data and operational settings, with none of the effects of a security operation.                                                       |
| `qauth:admin:security` | security permissions | Performs a security operation, defined by its effect in ADR-019 Decision 7, such as changing what can authenticate an account or what a token asserts. |

- The three scopes are independent. No scope implies another: `qauth:admin:write` does not
  satisfy a read permission, and `qauth:admin:security` satisfies neither a read nor a write
  permission.
- A request that needs a write permission and a security permission needs both scopes.
- Scopes are matched exactly and case-sensitively (RFC 6749 §3.3).
- Every scope in the `qauth:` namespace, in any case, is QAuth's. A realm's dynamic
  registration allowlist cannot hold one, so dynamic registration drops one like any other scope
  outside the allowlist, and the developer API refuses one with `invalid_client_metadata`. A
  Client ID Metadata Document's `scope` is never stored, so one there is ignored. Discovery
  never lists one. Other servers' scopes such as `admin:org` are ordinary scopes.

## How a request is authorized

Under the rule the admin API will enforce, a permission is effective for a request when both
hold:

1. one of the caller's admin roles grants it, and
2. the token carries the scope of its class.

So a token with only `qauth:admin:write` never uses a security permission, whatever role the caller
holds. An admin API operation names the permission it needs in its `x-qauth-permission`
extension ([API conventions](/reference/api-conventions/#openapi)). An operation whose request
decides whether it is a security operation, such as a policy patch, names a write permission and
a security permission, and a request that touches both needs both.

The caller's roles come from its admin grants, which name a role and a realm, or every realm. They
are read from the database on every request, never from the token, so a revoked grant counts from
the next request ([Admin authority](/reference/api-conventions/#admin-authority)). The token
endpoint already applies the scope side: it issues an admin scope only to an account whose live
grants reach that scope's class, through a client that lists the admin API's audience.

## Permissions

| Permission                 | Class    | Scope                  | Resource          | Description                                                                                                                                                                                             |
| -------------------------- | -------- | ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `realms.read`              | read     | `qauth:admin:read`     | `realms`          | Read a realm's representation, with its settings and policies.                                                                                                                                          |
| `realms.export`            | read     | `qauth:admin:read`     | `realms`          | Export a realm's configuration as a realm file, which holds no secret value.                                                                                                                            |
| `realms.import.plan`       | read     | `qauth:admin:read`     | `realms`          | Compute the dry-run plan of a realm-file import: every change it would make and the permissions each needs. It applies nothing.                                                                         |
| `realms.policies.write`    | write    | `qauth:admin:write`    | `realms.policies` | Change a realm policy whose change is not a security operation, such as a token lifespan.                                                                                                               |
| `realms.policies.security` | security | `qauth:admin:security` | `realms.policies` | Change a realm policy whose change is a security operation, such as loosening the sign-in methods or the password policy.                                                                               |
| `plugins.read`             | read     | `qauth:admin:read`     | `plugins`         | Read the AuthMethod plugins installed in the deployment and a realm's state of each, never a secret value (#600).                                                                                       |
| `plugins.security`         | security | `qauth:admin:security` | `plugins`         | Enable, configure and disable an AuthMethod plugin in a realm: each changes which upstream credentials sign users in (#600).                                                                            |
| `secrets.seal`             | write    | `qauth:admin:write`    | `secrets`         | Seal a value for a security operation's secret member in a realm: it changes nothing, and the operation that sets the value still needs its own permission and an approval (#984).                      |
| `users.security`           | security | `qauth:admin:security` | `users`           | Verify an account as the operator, so it counts as verified for sign-in and for owning an agent and an unclaimed account is claimed (#1052).                                                            |
| `clients.read`             | read     | `qauth:admin:read`     | `clients`         | List and read every client of a realm, whoever owns it, and preview a change of one; never a client's secret (#632).                                                                                    |
| `clients.write`            | write    | `qauth:admin:write`    | `clients`         | Change a client's settings whose change is not a security operation, such as its name or a shorter token lifetime, and suspend a client (#632).                                                         |
| `clients.security`         | security | `qauth:admin:security` | `clients`         | Register and delete a client, lift a suspension, and change a client's settings whose change is a security operation, such as its redirect URIs, its authentication method or first-party trust (#632). |
| `approvals.read`           | read     | `qauth:admin:read`     | `approvals`       | Read the approval requests of security operations and where each one stands.                                                                                                                            |
| `approvals.approve`        | security | `qauth:admin:security` | `approvals`       | Approve another admin's security operation, with a fresh passkey.                                                                                                                                       |

A permission has exactly one class. A permission that performs a security operation has an id of
its own and the class `security`; it never shares an id with a write permission, so no custom
role reaches a security operation through `qauth:admin:write`.

## Built-in roles

| Role             | Classes               | Permissions                                                                                                                                                                                                                                                                 | Description                                                     |
| ---------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `viewer`         | read                  | `realms.read`, `realms.export`, `realms.import.plan`, `plugins.read`, `clients.read`, `approvals.read`                                                                                                                                                                      | Reads everything an admin can read.                             |
| `editor`         | read, write           | `realms.read`, `realms.export`, `realms.import.plan`, `realms.policies.write`, `plugins.read`, `secrets.seal`, `clients.read`, `clients.write`, `approvals.read`                                                                                                            | Reads, and makes every change that is not a security operation. |
| `security-admin` | read, write, security | `realms.read`, `realms.export`, `realms.import.plan`, `realms.policies.write`, `realms.policies.security`, `plugins.read`, `plugins.security`, `secrets.seal`, `users.security`, `clients.read`, `clients.write`, `clients.security`, `approvals.read`, `approvals.approve` | Reads, makes every change, and performs security operations.    |

- Built-in roles are defined in code, by class, and cannot be edited. A permission added to the
  catalog joins every built-in role of its class.
- A custom role lists permission ids from the table above. An unknown id is refused, and so is a
  retired one. Its name is lower-case ASCII words joined by single hyphens, such as
  `realm-auditor`, and never reads as a built-in role's name.
- A custom role is defined in one realm, and granted only to that realm's accounts or for that
  realm. Disabling it takes its permissions from every grant at the next request.
- Admin roles are not the realm's application roles, which reach tokens as claims
  ([ADR-020](/reference/records/adr/020-ui-surfaces-and-acceptance-criteria/), fork D).

## Retired permissions

| Permission      | Class | Retired in | Description                                                                                                                                  |
| --------------- | ----- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugins.write` | write | v0.3.0     | Seal a value for an AuthMethod plugin's secret member (#600); secrets.seal, which seals for every security operation, took its place (#984). |

## Stability

The permission ids will be part of the admin API's contract, because custom roles store them.
Like every QAuth-defined identifier, they are promised from 1.0.0 on
([ADR-018 §5](/reference/records/adr/018-1-0-scope-and-stability/)); until then a release may still
rename one, and says so in its changelog. From 1.0.0:

- An id is never renamed and never reused for another meaning.
- A permission that is no longer needed is retired, not removed: it is listed under
  [Retired permissions](#retired-permissions), it grants nothing, and its id stays taken.
- A release may add permissions. A new permission joins the built-in roles of its class.

The stable-surface check compares the catalog's JSON Schema
(`apps/docs-site/public/schemas/admin-permissions.json`) with the latest release: a removed permission, or one whose
class changed, is a break it reports.

---

# Security operations

URL: https://docs.qauth.dev/reference/security-operations/

<!-- Generated from apps/auth-server/src/app/helpers/admin-operations.ts by its tests. Do not edit by hand: change the registry and run `pnpm nx test auth-server -- -u`. -->

An admin API operation needs `qauth:admin:security` because of what it does, not because of
the screen it sits on ([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/),
Decision 7). Each admin operation is defined once, in the registry in `apps/auth-server/src/app/helpers/admin-operations.ts`, with
its class, the effects that make it a security operation and the
[permissions](/reference/admin-permissions/) it needs. This page is generated from that registry.

## Effects

| Effect                 | An operation with it                                                                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `credential-path`      | Changes which credentials, links or addresses can authenticate or recover an account.                                                                   |
| `token-content`        | Changes what a token asserts or who receives it.                                                                                                        |
| `issue-for-other`      | Issues a token or session for someone other than the caller.                                                                                            |
| `administration`       | Changes who administers.                                                                                                                                |
| `import`               | Imports a realm file, or promotes a sandbox configuration, whose diff holds any other effect.                                                           |
| `federation-operator`  | Acts as a federation operator.                                                                                                                          |
| `key-custody`          | Rotates a key, rotates the KEK or retires a key.                                                                                                        |
| `realm-lifecycle`      | Deletes a realm or transfers its ownership.                                                                                                             |
| `authority-tree-power` | Revokes by agent or disables a transmitter.                                                                                                             |
| `posture-loosening`    | Loosens the environment posture, lengthens a token or session lifetime or the key rotation interval, or shortens or switches off audit-event retention. |
| `bulk-revocation`      | Revokes sessions or refresh-token families in bulk.                                                                                                     |

The list is closed. A definition that names another value is refused, and a request whose
classification names one counts as a security operation. The tags are published on each admin
operation of the OpenAPI document as `x-qauth-effects`
([API conventions](/reference/api-conventions/#openapi)).

## Rules

- An operation is of class `security` if and only if it has at least one effect. The registry
  refuses a `read` or `write` operation with an effect, and a `security` operation with none.
- Its class is the strictest class among its permissions (`read` < `write` < `security`). So an
  operation with an effect needs a `security` permission, which only `qauth:admin:security` lets a
  token use: no role reaches it through `qauth:admin:write`.
- An operation whose request decides what it needs, such as a policy patch or a realm-file import,
  declares the strictest case (class `security`, every effect it may have and every permission it
  may need) and a `classify` function. `classify` is pure: it reads copies of the request's
  method, path parameters, query and body, and the operation's current state, and returns the
  class, the effects and the permissions that request needs, within the declaration. A merge
  patch's field that `classify` has no rule for fails closed only when `classify` takes the
  changed fields from the body, with `mergePatchLeafPaths(body)` (which walks the body's own
  keys: an array is one field, a `null` member is a change), and classifies them with
  `classifyByField`, which throws on a field its table does not hold. A request-dependent merge
  patch operation uses that pattern; a `classify` that reads only the fields it expects never
  sees the others.
- By effect, a policy change that lengthens an access-token, refresh-token or session lifetime or
  the key rotation interval, or shortens or switches off audit-event retention, is
  `posture-loosening`, a security change. Shortening a lifetime or lengthening retention is a
  write.
- An operation that reads state to classify names the version of the state it read
  (`stateVersion`). The classification carries it, a request without `If-Match` is answered
  428 and one whose `If-Match` names another version 412, both before the handler, and the handler's write is conditional on that
  version (or loads, classifies and writes in one transaction under `SELECT … FOR UPDATE`), so
  it never writes state other than the state it classified.
- The admin pipeline classifies every request after validation and before the handler. The
  handler receives the classification and cannot lower it, and every later stage reads the same
  one. The path parameters, query and body it classified are frozen: a stage that changes them
  fails the request. A binary body cannot be frozen, so the classification carries its SHA-256
  digest (`bodyDigest`), which approval and apply bind to. The listener's authorization stage
  (`authorize`) is required and runs on every request right after the classification.
- Fail closed: when `classify` throws, meets a field it has no rule for, or returns an unknown
  member, effect, class or permission, or more than the operation declares, the request needs the
  operation as declared: `security`, with every declared effect and permission.
- At boot, the admin listener refuses a route that names no registered operation, and one whose
  `operationId`, `x-qauth-class`, `x-qauth-permission`, `x-qauth-effects` or
  `x-qauth-two-admin` differs from the registry. The classification stage is registered before
  every route, and checks each route again on its first request. In CI, the API conventions check
  fails when an admin operation of the OpenAPI document disagrees with the registry.
- Every admin operation, of any class, is served by exactly one route: the admin listener refuses
  to boot a second route that names an operation another route already serves. A `HEAD` route
  beside it is checked as any route, but is never the operation's route.
- A security operation runs only with a fresh approval bound to that exact request
  ([API conventions](/reference/api-conventions/#approvals)). So each one an admin route performs
  registers a renderer (`render`): what its approver is shown of one request, typed display data
  built from the filed request alone, when the approval is filed. The approval stores it, and never
  the body. The admin listener refuses to boot such a route without
  one. Filing an approval (`approvals.create`) and withdrawing one (`approvals.cancel`) need
  what the operation it is for needs, so they declare every effect and permission and decide per
  request; they are the only security operations that run without an approval.
- The approval binds the request as its route parses it, so the route of a security operation
  parses all of it, and the admin listener refuses to boot one that does not: it has one method, a
  Zod object schema for its path parameters that names every parameter of its URL, a Zod body
  schema under every method that carries a body (all but `GET`, `HEAD` and `TRACE`), and a
  Zod query schema if it has one. Its handler reads only the parsed path parameters, query and
  body, and those schemas are deterministic: no default a parse makes up anew, such as a random id
  or the current time, since the filed request and its retry are parsed apart.
- A security operation takes a secret only sealed. An approval keeps `op_hash`, a digest of the
  request it binds, with its nonce, and a copy of the approvals table taken while it is open (a
  dump, a replica, a WAL archive) lets anyone test a guessed body against them; so a secret, such
  as a password or a client secret, is never in a security operation's body in the clear. The
  operation declares the members of its body that carry one (`secretMembers`, JSON Pointers in
  which `*` stands for every member of a record or item of an array), each takes
  `{ "sealed": … }` (`SEALED_VALUE_SCHEMA`), and the admin listener refuses to boot its route
  when its body schema holds a declared member to any other schema. A caller seals the value first
  with `secrets.seal`, which encrypts it with the realm's `data_at_rest` key for that
  operation, that member and the request's path parameters, with what the route binds beside them
  (`config.sealScope`, such as the package and type of the plugin a configure names), changes
  nothing and records no value. The handler opens it only for its own operation, that member, its
  own path parameters and the realm, and refuses one sealed for any other with 400. The
  operation's renderer names a secret member and never shows its sealed value: an approval whose
  renderer does is never filed. The listener cannot tell a secret from a plain string by its
  schema, so a member the operation does not declare is not checked: the operation that sets a
  secret declares it, in its body. A security operation takes no secret in its path or query.
- A security operation's handler makes an effect outside the database, such as a KMS or KEK call,
  a mail or an outbound request, only through a record its transaction writes and that is acted
  on after the commit (an outbox), or after the commit itself. An operation that rolls back leaves
  its approval `approved`, so a retry may run it again: an effect made before the rollback
  would be made twice, or once with no change and no audit row to show for it.

These are not security operations:

- Sending a set-up or reset link to the contact address already on the account. The link reaches
  only the person a self-service reset reaches. Copying the link is a security operation.
- Brand strings and links. They are display data, under `qauth:admin:write`.
- Anything outside the admin API. The developer API's changes to a client the caller owns
  ([ADR-012](/reference/records/adr/012-dynamic-client-ownership/)) and the account API's changes
  to the caller's own account keep their own rules.

## Operations

| Operation                 | Class    | Effects                                                                                                                                                                                                    | Permissions                                                                                                                                                                                                                                                                 | Description                                                                                                                                                                                                                                                                                                                                               |
| ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secrets.seal`            | write    | none                                                                                                                                                                                                       | `secrets.seal`                                                                                                                                                                                                                                                              | Seal a value for one secret member of a security operation in a realm: it changes nothing, and answers the value encrypted for that operation, member and realm, which that operation's request then carries.                                                                                                                                             |
| `realms.get`              | read     | none                                                                                                                                                                                                       | `realms.read`                                                                                                                                                                                                                                                               | Read a realm: its name, whether it is enabled and the operator realm, its times, and its policies, each secret field only as whether it is set.                                                                                                                                                                                                           |
| `realms.policies.update`  | security | `credential-path`, `token-content`, `posture-loosening`, `administration`                                                                                                                                  | `realms.policies.write`, `realms.policies.security`, `realms.read`                                                                                                                                                                                                          | Change a realm's policies with a JSON Merge Patch against the version it names; each field it changes needs what its annotation says, a security change an approval, and a secret field only sealed; it answers the realm, so it needs realms.read too. Decided per request. Takes `/mail/smtp/password`, `/mail/resend/apiKey` only sealed.              |
| `realms.policies.preview` | read     | none                                                                                                                                                                                                       | `realms.read`                                                                                                                                                                                                                                                               | Preview a change of a realm's policies: what the patch realms.policies.update takes would change, field by field, each before and after with its direction, class, effects and scopes, and what the save would need, its approval included; it writes nothing and shows a secret field only as set or not set.                                            |
| `plugins.list`            | read     | none                                                                                                                                                                                                       | `plugins.read`                                                                                                                                                                                                                                                              | List the AuthMethod plugins installed in the deployment, with the realm's state of each: on or off, its config, and which secret members hold a value.                                                                                                                                                                                                    |
| `plugins.get`             | read     | none                                                                                                                                                                                                       | `plugins.read`                                                                                                                                                                                                                                                              | Read one installed AuthMethod plugin with the realm's state of it; secret members show only whether they hold a value, and a state another package or type wrote says so.                                                                                                                                                                                 |
| `plugins.update`          | security | `credential-path`                                                                                                                                                                                          | `plugins.security`                                                                                                                                                                                                                                                          | Replace an AuthMethod plugin's configuration in a realm, set or clear its secret members, checked against the plugin's config schema, and record the installed package and type it is written for; it never changes plugin code. Takes `/secrets/*` only sealed.                                                                                          |
| `plugins.enable`          | security | `credential-path`                                                                                                                                                                                          | `plugins.security`                                                                                                                                                                                                                                                          | Enable an AuthMethod plugin in a realm, so its sign-in routes answer there; its configuration must pass the plugin's config schema and have been written for the installed package and type, and the request names the version of the state it enables.                                                                                                   |
| `plugins.disable`         | security | `credential-path`                                                                                                                                                                                          | `plugins.security`                                                                                                                                                                                                                                                          | Disable an AuthMethod plugin in a realm: its sign-in routes answer 404 there, and its configuration is kept; the request names the version of the state it disables.                                                                                                                                                                                      |
| `users.verify`            | security | `credential-path`                                                                                                                                                                                          | `users.security`                                                                                                                                                                                                                                                            | Verify an account as the operator: it counts as verified beside its primary identity, for sign-in and for owning an agent, and an unclaimed account is claimed; email_verified is not changed. The approval binds the account and its credentials as they stood when it was filed; a disabled account, and one an operator already verified, are refused. |
| `clients.list`            | read     | none                                                                                                                                                                                                       | `clients.read`                                                                                                                                                                                                                                                              | List every client of a realm, whoever owns it, newest first, one page at a time, optionally those whose client_id or name holds a search text; never a secret.                                                                                                                                                                                            |
| `clients.get`             | read     | none                                                                                                                                                                                                       | `clients.read`                                                                                                                                                                                                                                                              | Read a client of a realm, whoever owns it, with its ETag; never a secret.                                                                                                                                                                                                                                                                                 |
| `clients.create`          | security | `token-content`                                                                                                                                                                                            | `clients.security`                                                                                                                                                                                                                                                          | Register a client no developer owns, provisioned by the operator, with its redirect URIs, authentication method and trust; a secret, for a client that authenticates with one, is answered once.                                                                                                                                                          |
| `clients.update`          | security | `token-content`, `posture-loosening`, `administration`                                                                                                                                                     | `clients.write`, `clients.security`, `clients.read`                                                                                                                                                                                                                         | Change a client with a JSON Merge Patch against the version it names; each field it changes needs what the client field table says, and every change of a client that holds an admin scope is a security change; a security change needs an approval; a CIMD client is refused; it answers the client, so it needs clients.read too. Decided per request. |
| `clients.preview`         | read     | none                                                                                                                                                                                                       | `clients.read`                                                                                                                                                                                                                                                              | Preview a change of a client: what the patch clients.update takes would change, field by field, each before and after with its direction, class, effects and scopes, and what the save would need, its approval included; it writes nothing.                                                                                                              |
| `clients.delete`          | security | `token-content`                                                                                                                                                                                            | `clients.security`                                                                                                                                                                                                                                                          | Delete a client with its refresh tokens, consents and API keys, against the version it names; a CIMD client is refused.                                                                                                                                                                                                                                   |
| `clients.enable`          | security | `token-content`                                                                                                                                                                                            | `clients.security`                                                                                                                                                                                                                                                          | Lift a client's suspension, against the version it names, and switch on a client no developer owns: it obtains tokens again.                                                                                                                                                                                                                              |
| `clients.disable`         | security | `administration`                                                                                                                                                                                           | `clients.write`, `clients.security`                                                                                                                                                                                                                                         | Suspend a client, against the version it names: it obtains no token until clients.enable lifts the suspension, and its owner cannot lift it; a write, unless the client holds an admin scope. Decided per request.                                                                                                                                        |
| `approvals.create`        | security | `credential-path`, `token-content`, `issue-for-other`, `administration`, `import`, `federation-operator`, `key-custody`, `realm-lifecycle`, `authority-tree-power`, `posture-loosening`, `bulk-revocation` | `realms.read`, `realms.export`, `realms.import.plan`, `realms.policies.write`, `realms.policies.security`, `plugins.read`, `plugins.security`, `secrets.seal`, `users.security`, `clients.read`, `clients.write`, `clients.security`, `approvals.read`, `approvals.approve` | File an approval request for one request of a security operation: it needs the security permissions that operation declares, or all it declares when it has none. Decided per request.                                                                                                                                                                    |
| `approvals.get`           | read     | none                                                                                                                                                                                                       | `approvals.read`                                                                                                                                                                                                                                                            | Read an approval request: its requester, an approver of it, or an admin who may approve it.                                                                                                                                                                                                                                                               |
| `approvals.cancel`        | security | `credential-path`, `token-content`, `issue-for-other`, `administration`, `import`, `federation-operator`, `key-custody`, `realm-lifecycle`, `authority-tree-power`, `posture-loosening`, `bulk-revocation` | `realms.read`, `realms.export`, `realms.import.plan`, `realms.policies.write`, `realms.policies.security`, `plugins.read`, `plugins.security`, `secrets.seal`, `users.security`, `clients.read`, `clients.write`, `clients.security`, `approvals.read`, `approvals.approve` | Withdraw an approval request the caller filed: it needs the security permissions the operation it is for declares, or all it declares when it has none. Decided per request.                                                                                                                                                                              |

## Reserved operations

Other areas register the operations below, and the Registered column says which are registered.
When one is registered, the registry refuses it unless it is a security operation that carries at
least the effects listed, and refuses an id that differs from one only in case. An operation may
carry more effects. Only an operation marked "per request" may decide per request what it needs,
with `classify`, and it lists every effect it may have; every other one needs its declaration on
every request. Each entry is listed under each of its effects. The table lives in
`apps/auth-server/src/app/helpers/admin-operations-reserved.ts`.

### `credential-path`

| Operation                          | Effects                                                                   | Per request | Registered | Source                                              | Description                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------- | ----------- | ---------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `users.links.copy`                 | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, ADR-020 §3                      | Copy a one-time set-up or reset link, returned once to the admin who copies it.                                                                                                                                                                                                                                                                                             |
| `users.identifiers.update`         | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, ADR-020 §3                      | Change an account's identifier or contact address.                                                                                                                                                                                                                                                                                                                          |
| `users.password.set`               | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, ADR-020 §3                      | Set an account's password.                                                                                                                                                                                                                                                                                                                                                  |
| `users.passkeys.create`            | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, ADR-020 §3                      | Add a passkey to an account.                                                                                                                                                                                                                                                                                                                                                |
| `users.credentials.create`         | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, ADR-020 §3                      | Add any other credential to an account, such as a TOTP secret or an upstream identity.                                                                                                                                                                                                                                                                                      |
| `users.passkeys.delete`            | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, ADR-020 §3                      | Remove a passkey from an account.                                                                                                                                                                                                                                                                                                                                           |
| `users.totp.delete`                | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, ADR-020 §3                      | Remove an account's TOTP.                                                                                                                                                                                                                                                                                                                                                   |
| `users.recoveryCodes.delete`       | `credential-path`                                                         | no          | no         | ADR-019 Decision 7                                  | Remove an account's recovery codes.                                                                                                                                                                                                                                                                                                                                         |
| `users.linkedAccounts.delete`      | `credential-path`                                                         | no          | no         | ADR-019 Decision 7                                  | Unlink an upstream or wallet account from an account.                                                                                                                                                                                                                                                                                                                       |
| `users.idJagSubjects.create`       | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, ADR-011 gate 14                 | Link an enterprise ID-JAG subject to an account, the one link an admin may make.                                                                                                                                                                                                                                                                                            |
| `users.verify`                     | `credential-path`                                                         | no          | yes        | ADR-019 Decision 7, ADR-015 Decision 8, #1052, #682 | Verify an account as the operator: it counts as verified for sign-in and for owning an agent, and an unclaimed account is claimed, so another person's mailbox proof no longer ends it.                                                                                                                                                                                     |
| `upstreamProviders.create`         | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, #714                            | Add an upstream identity provider.                                                                                                                                                                                                                                                                                                                                          |
| `upstreamProviders.update`         | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, #714                            | Change an upstream identity provider.                                                                                                                                                                                                                                                                                                                                       |
| `upstreamProviders.disable`        | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, #714                            | Disable an upstream identity provider.                                                                                                                                                                                                                                                                                                                                      |
| `upstreamProviders.delete`         | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, #714                            | Remove an upstream identity provider.                                                                                                                                                                                                                                                                                                                                       |
| `upstreamProviders.mappers.create` | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, #714                            | Add a mapper to an upstream provider's claims.                                                                                                                                                                                                                                                                                                                              |
| `upstreamProviders.mappers.update` | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, #714                            | Change a mapper of an upstream provider's claims.                                                                                                                                                                                                                                                                                                                           |
| `upstreamProviders.mappers.delete` | `credential-path`                                                         | no          | no         | ADR-019 Decision 7, #714                            | Remove a mapper of an upstream provider's claims.                                                                                                                                                                                                                                                                                                                           |
| `trustedIssuers.create`            | `credential-path`                                                         | no          | no         | ADR-019 Decision 7                                  | Trust a credential issuer for wallet sign-in.                                                                                                                                                                                                                                                                                                                               |
| `trustedIssuers.update`            | `credential-path`                                                         | no          | no         | ADR-019 Decision 7                                  | Change a trusted credential issuer.                                                                                                                                                                                                                                                                                                                                         |
| `trustedIssuers.delete`            | `credential-path`                                                         | no          | no         | ADR-019 Decision 7                                  | Stop trusting a credential issuer.                                                                                                                                                                                                                                                                                                                                          |
| `plugins.enable`                   | `credential-path`                                                         | no          | yes        | ADR-019 Decision 7, #600                            | Enable an AuthMethod plugin in a realm.                                                                                                                                                                                                                                                                                                                                     |
| `plugins.update`                   | `credential-path`                                                         | no          | yes        | ADR-019 Decision 7, #600                            | Change an AuthMethod plugin's configuration in a realm.                                                                                                                                                                                                                                                                                                                     |
| `realms.policies.update`           | `credential-path`, `token-content`, `posture-loosening`, `administration` | yes         | yes        | ADR-019 Decision 7, #514, #517                      | Change realm policies: the mail transport and sender, the sign-in, password and brute-force policy, the registration policy, the environment ceiling, token and session lifetimes, the key rotation interval, audit-event retention and the two-admin set; lengthening a lifetime or the rotation interval, or shortening or switching off retention, is posture-loosening. |

### `token-content`

| Operation                          | Effects                                                                   | Per request | Registered | Source                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------- | ----------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `realms.policies.update`           | `credential-path`, `token-content`, `posture-loosening`, `administration` | yes         | yes        | ADR-019 Decision 7, #514, #517 | Change realm policies: the mail transport and sender, the sign-in, password and brute-force policy, the registration policy, the environment ceiling, token and session lifetimes, the key rotation interval, audit-event retention and the two-admin set; lengthening a lifetime or the rotation interval, or shortening or switching off retention, is posture-loosening.                                                                       |
| `clients.create`                   | `token-content`                                                           | no          | yes        | ADR-019 Decision 7, #518, #632 | Register a client, with its redirect URIs, authentication method and trust.                                                                                                                                                                                                                                                                                                                                                                       |
| `clients.update`                   | `token-content`, `posture-loosening`, `administration`                    | yes         | yes        | ADR-019 Decision 7, #518, #632 | Change a client: its redirect URIs, post-logout redirect URIs, back-channel logout URI, authentication method and keys, grant types, first-party trust, verified domain, PKCE or DPoP, client_credentials scopes, qauth: scopes, environment, token lifetimes or agent-type fields; lengthening a client's token lifetime or switching PKCE or DPoP off is posture-loosening; any change of a client that obtains admin tokens is administration. |
| `clients.secret.rotate`            | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #518       | Rotate a client's secret, returned once to the admin who rotates it.                                                                                                                                                                                                                                                                                                                                                                              |
| `clients.registrationToken.rotate` | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #518       | Rotate a client's registration access token (RFC 7592), returned once to the admin who rotates it.                                                                                                                                                                                                                                                                                                                                                |
| `clients.delete`                   | `token-content`                                                           | no          | yes        | ADR-019 Decision 7, #518, #632 | Delete a client.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `scopes.create`                    | `token-content`                                                           | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Add a scope to the catalog.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scopes.update`                    | `token-content`                                                           | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Change a scope of the catalog.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `scopes.delete`                    | `token-content`                                                           | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Remove a scope from the catalog.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `mappers.create`                   | `token-content`                                                           | no          | no         | ADR-019 Decision 7             | Add a token mapper.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `mappers.update`                   | `token-content`                                                           | no          | no         | ADR-019 Decision 7             | Change a token mapper.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `mappers.delete`                   | `token-content`                                                           | no          | no         | ADR-019 Decision 7             | Remove a token mapper.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `resourceServers.create`           | `token-content`                                                           | no          | no         | ADR-019 Decision 7             | Register a resource server and its audience.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `resourceServers.update`           | `token-content`                                                           | no          | no         | ADR-019 Decision 7             | Change a resource server or its audience.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `resourceServers.delete`           | `token-content`                                                           | no          | no         | ADR-019 Decision 7             | Remove a resource server and its audience.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `roles.create`                     | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Define a realm role.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `roles.update`                     | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Change a realm role, its name or composites.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `roles.delete`                     | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Delete a realm role.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `groups.create`                    | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Define a group.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `groups.update`                    | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Change a group.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `groups.delete`                    | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Delete a group.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `groups.roles.assign`              | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Map a realm role to a group, so the group's members hold it.                                                                                                                                                                                                                                                                                                                                                                                      |
| `groups.roles.remove`              | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Remove a realm role from a group.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `users.roles.assign`               | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Assign a role to an account.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `users.roles.remove`               | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Remove a role from an account.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `groups.members.add`               | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Add an account to a group.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `groups.members.remove`            | `token-content`                                                           | no          | no         | ADR-019 Decision 7, #683       | Remove an account from a group.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `webhooks.create`                  | `token-content`                                                           | no          | no         | #537                           | Add a webhook subscription.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `webhooks.update`                  | `token-content`                                                           | no          | no         | #537                           | Change a webhook subscription.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `webhooks.delete`                  | `token-content`                                                           | no          | no         | #537                           | Remove a webhook subscription.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `webhooks.rotateSecret`            | `token-content`                                                           | no          | no         | #537                           | Rotate a webhook subscription's signing secret.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `webhooks.test`                    | `token-content`                                                           | no          | no         | #537                           | Send a test event to a webhook subscription's destination.                                                                                                                                                                                                                                                                                                                                                                                        |
| `ssfStreams.create`                | `token-content`                                                           | no          | no         | #537                           | Add a Shared Signals stream.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `ssfStreams.update`                | `token-content`                                                           | no          | no         | #537                           | Change a Shared Signals stream's destination.                                                                                                                                                                                                                                                                                                                                                                                                     |
| `ssfStreams.delete`                | `token-content`                                                           | no          | no         | #537                           | Remove a Shared Signals stream.                                                                                                                                                                                                                                                                                                                                                                                                                   |

### `issue-for-other`

| Operation                     | Effects           | Per request | Registered | Source                   | Description                                                   |
| ----------------------------- | ----------------- | ----------- | ---------- | ------------------------ | ------------------------------------------------------------- |
| `users.actChainTokens.create` | `issue-for-other` | no          | no         | ADR-019 Decision 7, #523 | Issue an act-chain token to an admin who acts for an account. |

### `administration`

| Operation                | Effects                                                                   | Per request | Registered | Source                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------- | ----------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `realms.policies.update` | `credential-path`, `token-content`, `posture-loosening`, `administration` | yes         | yes        | ADR-019 Decision 7, #514, #517 | Change realm policies: the mail transport and sender, the sign-in, password and brute-force policy, the registration policy, the environment ceiling, token and session lifetimes, the key rotation interval, audit-event retention and the two-admin set; lengthening a lifetime or the rotation interval, or shortening or switching off retention, is posture-loosening.                                                                       |
| `clients.update`         | `token-content`, `posture-loosening`, `administration`                    | yes         | yes        | ADR-019 Decision 7, #518, #632 | Change a client: its redirect URIs, post-logout redirect URIs, back-channel logout URI, authentication method and keys, grant types, first-party trust, verified domain, PKCE or DPoP, client_credentials scopes, qauth: scopes, environment, token lifetimes or agent-type fields; lengthening a client's token lifetime or switching PKCE or DPoP off is posture-loosening; any change of a client that obtains admin tokens is administration. |
| `admins.create`          | `administration`                                                          | no          | no         | ADR-019 Decision 7, #679       | Create an admin account.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `admins.delete`          | `administration`                                                          | no          | no         | ADR-019 Decision 7, #679       | Remove an admin account.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `adminGrants.create`     | `administration`                                                          | no          | no         | ADR-019 Decision 7, #679       | Grant an admin role to an account in a realm.                                                                                                                                                                                                                                                                                                                                                                                                     |
| `adminGrants.delete`     | `administration`                                                          | no          | no         | ADR-019 Decision 7, #679       | Remove an admin role from an account.                                                                                                                                                                                                                                                                                                                                                                                                             |
| `adminRoles.create`      | `administration`                                                          | no          | no         | ADR-019 Decision 7, #679       | Create a custom admin role.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `adminRoles.update`      | `administration`                                                          | no          | no         | ADR-019 Decision 7, #679       | Change the permissions of a custom admin role.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `adminRoles.delete`      | `administration`                                                          | no          | no         | ADR-019 Decision 7, #679       | Delete a custom admin role.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `serviceAccounts.create` | `administration`                                                          | no          | no         | ADR-019 Decision 7, #679       | Create a service account for the admin API.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `serviceAccounts.delete` | `administration`                                                          | no          | no         | ADR-019 Decision 7, #679       | Remove a service account.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `clients.disable`        | `administration`                                                          | yes         | yes        | ADR-019 Decision 7, #632       | Suspend a client. Suspending one that obtains admin tokens takes the admin API from whoever signs in through it.                                                                                                                                                                                                                                                                                                                                  |

### `import`

| Operation              | Effects  | Per request | Registered | Source                                 | Description                                       |
| ---------------------- | -------- | ----------- | ---------- | -------------------------------------- | ------------------------------------------------- |
| `realms.imports.apply` | `import` | yes         | no         | ADR-019 Decisions 7 and 11, #531, #555 | Apply a realm-file import or a sandbox promotion. |

### `federation-operator`

| Operation                               | Effects                              | Per request | Registered | Source                         | Description                                                             |
| --------------------------------------- | ------------------------------------ | ----------- | ---------- | ------------------------------ | ----------------------------------------------------------------------- |
| `federation.entityConfiguration.update` | `federation-operator`                | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Change the realm's federation entity configuration and authority hints. |
| `federation.subordinates.create`        | `federation-operator`                | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Add a federation subordinate.                                           |
| `federation.subordinates.update`        | `federation-operator`                | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Change a federation subordinate.                                        |
| `federation.subordinates.delete`        | `federation-operator`                | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Remove a federation subordinate.                                        |
| `federation.metadataPolicy.update`      | `federation-operator`                | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Change the federation metadata policy and its constraints.              |
| `federation.trustMarks.create`          | `federation-operator`                | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Issue a trust mark.                                                     |
| `federation.trustMarks.delete`          | `federation-operator`                | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Revoke a trust mark.                                                    |
| `federation.registrations.approve`      | `federation-operator`                | no          | no         | ADR-019 Decision 7, #731       | Approve an explicit federation registration.                            |
| `federation.keys.rotate`                | `federation-operator`, `key-custody` | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Rotate the federation keys.                                             |

### `key-custody`

| Operation                | Effects                              | Per request | Registered | Source                         | Description                                      |
| ------------------------ | ------------------------------------ | ----------- | ---------- | ------------------------------ | ------------------------------------------------ |
| `federation.keys.rotate` | `federation-operator`, `key-custody` | no          | no         | ADR-019 Decision 7, ADR-020 §3 | Rotate the federation keys.                      |
| `keys.rotate`            | `key-custody`                        | no          | no         | ADR-019 Decision 9, #544       | Rotate a realm's key before its rotation is due. |
| `keys.retire`            | `key-custody`                        | no          | no         | ADR-019 Decision 9             | Retire a key, which leaves the JWKS at once.     |
| `kek.rotate`             | `key-custody`                        | no          | no         | ADR-019 Decision 9, #545       | Rotate the KEK and re-wrap every stored key.     |

### `realm-lifecycle`

| Operation                   | Effects           | Per request | Registered | Source             | Description                   |
| --------------------------- | ----------------- | ----------- | ---------- | ------------------ | ----------------------------- |
| `realms.delete`             | `realm-lifecycle` | no          | no         | ADR-019 Decision 7 | Delete a realm.               |
| `realms.ownership.transfer` | `realm-lifecycle` | no          | no         | ADR-019 Decision 7 | Transfer a realm's ownership. |

### `authority-tree-power`

| Operation              | Effects                | Per request | Registered | Source                      | Description                                                              |
| ---------------------- | ---------------------- | ----------- | ---------- | --------------------------- | ------------------------------------------------------------------------ |
| `agents.revoke`        | `authority-tree-power` | no          | no         | ADR-019 Decision 7, ADR-014 | Revoke by agent: end every grant and token of an agent's authority tree. |
| `transmitters.disable` | `authority-tree-power` | no          | no         | ADR-019 Decision 7, ADR-014 | Disable a registered transmitter.                                        |

### `posture-loosening`

| Operation                | Effects                                                                   | Per request | Registered | Source                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------- | ----------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `realms.policies.update` | `credential-path`, `token-content`, `posture-loosening`, `administration` | yes         | yes        | ADR-019 Decision 7, #514, #517 | Change realm policies: the mail transport and sender, the sign-in, password and brute-force policy, the registration policy, the environment ceiling, token and session lifetimes, the key rotation interval, audit-event retention and the two-admin set; lengthening a lifetime or the rotation interval, or shortening or switching off retention, is posture-loosening.                                                                       |
| `clients.update`         | `token-content`, `posture-loosening`, `administration`                    | yes         | yes        | ADR-019 Decision 7, #518, #632 | Change a client: its redirect URIs, post-logout redirect URIs, back-channel logout URI, authentication method and keys, grant types, first-party trust, verified domain, PKCE or DPoP, client_credentials scopes, qauth: scopes, environment, token lifetimes or agent-type fields; lengthening a client's token lifetime or switching PKCE or DPoP off is posture-loosening; any change of a client that obtains admin tokens is administration. |

### `bulk-revocation`

| Operation                    | Effects           | Per request | Registered | Source           | Description                                                |
| ---------------------------- | ----------------- | ----------- | ---------- | ---------------- | ---------------------------------------------------------- |
| `clients.sessions.revokeAll` | `bulk-revocation` | no          | no         | ADR-020 §3, #625 | Revoke every session and refresh-token family of a client. |
| `realms.sessions.revokeAll`  | `bulk-revocation` | no          | no         | ADR-020 §3, #550 | Revoke sessions of a realm in bulk.                        |

### Security cases

An operation marked "per request" must meet its entry's security cases: at boot, the registry
runs its `classify` on each case and refuses the operation when a case gets less than the
effects listed (it is then a `security` request), or fails closed because `classify` does
not understand it. So a `classify` that answers `write` for every request cannot take the
reservation. The change that registers the operation writes the cases in the representation it
ships, and may add cases but never drop one or lower its effects.

#### `realms.policies.update`

- lowers the password minimum length: at least `credential-path`.
- lowers the password score: at least `credential-path`.
- switches brute-force protection off: at least `credential-path`.
- shortens the lockout: at least `credential-path`.
- lets anyone sign up: at least `credential-path`.
- raises the environment ceiling: at least `posture-loosening`.
- lengthens the access-token lifetime: at least `posture-loosening`.
- lengthens the refresh-token lifetime: at least `posture-loosening`.
- gives a field its looser default: at least `token-content`.
- widens the scopes dynamic registration allows: at least `token-content`.
- changes the mail transport: at least `credential-path`.
- sets the SMTP password: at least `credential-path`.
- clears the SMTP password: at least `credential-path`.
- changes the two-admin set: at least `administration`.

#### `clients.update`

- adds a redirect URI: at least `token-content`.
- adds a post-logout redirect URI: at least `posture-loosening`.
- sets a back-channel logout URI: at least `token-content`.
- sets the token endpoint authentication method to none: at least `token-content`.
- replaces the JWKS: at least `token-content`.
- moves the keys to a JWKS URI: at least `token-content`.
- switches PKCE off: at least `posture-loosening`.
- switches DPoP binding off: at least `posture-loosening`.
- makes the client first-party: at least `token-content`.
- removes first-party trust: at least `token-content`.
- sets the verified domain: at least `token-content`.
- changes the verified domain: at least `token-content`.
- lifts the client_credentials scope list: at least `token-content`.
- widens the client_credentials scope list: at least `token-content`.
- loosens the environment: at least `posture-loosening`.
- adds a grant type: at least `token-content`.
- makes the client an agent: at least `token-content`.
- gives an agent a mode: at least `token-content`.
- adds a scope of the qauth: namespace: at least `token-content`.
- lengthens the access-token lifetime: at least `posture-loosening`.
- gives the refresh-token lifetime back to the realm's: at least `posture-loosening`.
- adds a scope to a client_credentials client without a list: at least `token-content`.
- renames a client that obtains admin tokens: at least `administration`.

#### `clients.disable`

- suspends a client that obtains admin tokens: at least `administration`.

#### `realms.imports.apply`

- lowers the password policy: at least `import`.
- adds a redirect URI to a client: at least `import`.

## Stability

The effect tags and the operation ids will be part of the admin API's contract. Like every
QAuth-defined identifier, they are promised from 1.0.0 on
([ADR-018 §5](/reference/records/adr/018-1-0-scope-and-stability/)); until then a release may still
rename one, and says so in its changelog. A reserved entry may be renamed by the change that
registers its operation, but never weakened.

---

# Realm policies

URL: https://docs.qauth.dev/reference/realm-policies/

<!-- Generated from libs/server/realm-policy by its tests. Do not edit by hand: change the schema and run `pnpm nx test docs-checks -- -u`. -->

A realm's policies are its own settings: token lifetimes, the sign-in and password rules, client
registration, mail and the environment posture
([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/), Decision 10).
They are defined once, as a typed schema with a version, in `libs/server/realm-policy`. The admin API's
realm representation, the realm file, the diff of two configurations and the rule that decides
which changes are security operations all come from it, and so does this page.

Most of them already live on the realm row: the access, development access and refresh token
lifetimes, the verified-account, password and brute-force policy, the environment ceiling, the
scopes a dynamically registered client may hold, whether and from which hosts the realm accepts a
Client ID Metadata Document, the mail transport and sender, and whether the hosted sign-in offers
a passkey after a password sign-in. The rest are still read from the environment, for every realm:
the verification link's lifetime and resend rule. Nothing reads the `admin` group yet. Once a
policy lives on the realm row, the environment only seeds a new realm's value, and the realm row
owns it from then on.

A secret field, such as the SMTP password, is never in the policies: the realm keeps its value in
its secret store, encrypted with the realm's data-at-rest key, and the representation shows only
whether it is set (`passwordSet`). The environment seeds the first realm's secrets once, at the
first boot that can encrypt them. A policy update that selects the `smtp` transport without its
host, port, user, sender address and password, or `resend` without its sender address and API key,
is refused, and so is one that selects `smtp` or changes its host, port or TLS mode without giving
the password again, or that names `localhost`, a non-public IP address or a cloud metadata address as
its SMTP host when the operator's `SMTP_ALLOWED_HOSTS` does not list it (a metadata address never).

Schema version: `1-rc.1`.

## How a change is classified

Each field says which way is stricter:

- **lower** or **higher**: a number, such as a lifetime or a threshold.
- `true` or `false`: a flag.
- **closer to** a value: an enum with an explicit order, from the loosest value to the strictest.
- **fewer entries**: a set of allowed values, such as scopes or trusted domains.
- **more entries**: a set of required values.
- **not ordered**: a change is neither a tightening nor a loosening.

A change is a tightening when it moves toward stricter, a loosening when it moves the other way,
and neutral when the field is not ordered. A change the schema cannot place counts as a loosening,
so an unknown direction fails closed: a value outside an enum's order, a set change that both adds
and removes an allowed value, and a direction the schema does not know.

The Class column says when a change needs `qauth:admin:security` instead of `qauth:admin:write`
([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/), Decision 7):
never, only when it loosens, or on any change, in either direction. A security change carries the
[effects](/reference/security-operations/#effects) that make it one. A change of several fields
needs what its strictest change needs.

## Defaults and seeding

- The Default column is the value of a realm whose environment does not set the key in Seeded
  from. The environment only seeds: changing a key later changes no existing realm.
- A field added within a schema version always has a default, so a stored document that predates
  it still parses.
- **Secret** fields, such as the SMTP password, are write-only. Their value is never stored in the
  policy document and never returned: the realm representation shows only whether one is set, as
  `<name>Set`, and the realm file never holds one. A write sets one with its value and clears it
  with `null`; leaving it out keeps it, and a `<name>Set` sent back from the representation
  changes nothing. Setting or clearing a secret is always a security operation.
- **Environment-bound** fields describe the environment a realm runs in, such as its mail transport
  or a trust list. Promoting a sandbox configuration to a live realm leaves them out unless each is
  selected ([ADR-019](/reference/records/adr/019-deployment-topology-and-trust-boundaries/),
  Decision 11).

## Groups

### `tokens`

| Field                                          | Default  | Seeded from                 | Stricter when | Class                                                        | Description                                                                                                                                                                                                                                                        |
| ---------------------------------------------- | -------- | --------------------------- | ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tokens.accessTokenLifespanSeconds`            | `900`    | `ACCESS_TOKEN_LIFESPAN`     | lower         | `security` when loosened (`posture-loosening`), else `write` | How long an access token for a staging or production client is valid, in seconds, at most 86400 (a day).                                                                                                                                                           |
| `tokens.developmentAccessTokenLifespanSeconds` | `28800`  | `DEV_ACCESS_TOKEN_LIFESPAN` | lower         | `security` when loosened (`posture-loosening`), else `write` | How long an access token for a development client is valid, in seconds, at most 86400 (a day); no staging or production client receives it.                                                                                                                        |
| `tokens.refreshTokenLifespanSeconds`           | `604800` | `REFRESH_TOKEN_LIFESPAN`    | lower         | `security` when loosened (`posture-loosening`), else `write` | How long a refresh token is valid, in seconds, at most 7776000 (90 days), from its issue; a browser-based client's rotated token (a public client with an `https` redirect URI) never outlives the one it replaces, so its family ends with its first (RFC 10017). |
| `tokens.adminAccessTokenLifespanSeconds`       | `600`    | none                        | lower         | `security` when loosened (`posture-loosening`), else `write` | How long an access token for the admin API is valid, in seconds, at most 900, so a token whose audience is the admin API never lives longer, whatever the other lifetimes say (ADR-019 Decision 7: admin tokens are short-lived).                                  |

### `accounts`

| Field                             | Default | Seeded from                | Stricter when | Class                                                      | Description                                                                                                                                                                                                                                                                                    |
| --------------------------------- | ------- | -------------------------- | ------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accounts.requireVerifiedAccount` | `true`  | `REQUIRE_VERIFIED_ACCOUNT` | `true`        | `security` when loosened (`credential-path`), else `write` | Whether the legacy login routes (`POST /auth/login`, `POST /ui/login`) refuse an unverified account's right password with the answer a wrong password gets; the Interaction API verifies such an account inline with an emailed code, whatever this says.                                      |
| `accounts.allowSignUp`            | `false` | `ALLOW_SIGN_UP`            | `false`       | `security` when loosened (`credential-path`), else `write` | Whether a person may create a new account through the hosted sign-in, from an unknown upstream identity (#639) or with `prompt=create` (#640, for a client whose `hosted_flows` name `register`), or through the legacy `POST /auth/register` (since 0.2.1; it answers 403 while this is off). |

### `password`

| Field                       | Default | Seeded from                   | Stricter when                                             | Class                                                      | Description                                                                                                                                                                                                                                                                               |
| --------------------------- | ------- | ----------------------------- | --------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `password.minLength`        | `15`    | `PASSWORD_MIN_LENGTH`         | higher                                                    | `security` when loosened (`credential-path`), else `write` | The fewest characters (Unicode code points, after NFC normalisation) a new password may have, from 8 to 64; below 15 is a recorded deviation from NIST SP 800-63B-4 while a password can be the only factor.                                                                              |
| `password.minScore`         | `2`     | `PASSWORD_MIN_SCORE`          | higher                                                    | `security` when loosened (`credential-path`), else `write` | The lowest zxcvbn strength score, from 0 to 4, a new password may have.                                                                                                                                                                                                                   |
| `password.breachListSource` | `off`   | `PASSWORD_BREACH_LIST_SOURCE` | closer to `k_anonymity` (`off` < `local` < `k_anonymity`) | `security` when loosened (`credential-path`), else `write` | Which breach list new and presented passwords are checked against: off (the default), a list the operator supplies, or a k-anonymity range lookup through the egress client that sends only the first five hex characters of the password's SHA-1; a failed check never blocks a sign-in. |

### `bruteForce`

| Field                       | Default | Seeded from                     | Stricter when | Class                                                      | Description                                                                                                      |
| --------------------------- | ------- | ------------------------------- | ------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `bruteForce.enabled`        | `true`  | `FAILED_LOGIN_TRACKING_ENABLED` | `true`        | `security` when loosened (`credential-path`), else `write` | Whether repeated failed sign-ins for one identifier lock it out for a while; when off, failures are only logged. |
| `bruteForce.maxAttempts`    | `5`     | `FAILED_LOGIN_MAX_ATTEMPTS`     | lower         | `security` when loosened (`credential-path`), else `write` | How many failed sign-ins within the window lock an identifier out.                                               |
| `bruteForce.windowSeconds`  | `900`   | `FAILED_LOGIN_WINDOW`           | higher        | `security` when loosened (`credential-path`), else `write` | The window, in seconds, over which failed sign-ins are counted, at most 86400 (a day).                           |
| `bruteForce.lockoutSeconds` | `900`   | `FAILED_LOGIN_LOCKOUT_DURATION` | higher        | `security` when loosened (`credential-path`), else `write` | How long, in seconds, a locked-out identifier is refused before any password check, at most 86400 (a day).       |

### `botChallenge`

| Field                           | Default | Seeded from                         | Stricter when | Class                                                      | Description                                                                                                                                                                                                                                                    |
| ------------------------------- | ------- | ----------------------------------- | ------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `botChallenge.requiredAtSignUp` | `false` | `BOT_CHALLENGE_REQUIRED_AT_SIGN_UP` | `true`        | `security` when loosened (`credential-path`), else `write` | Whether every `prompt=create` registration passes the bot challenge before its address is asked for, whatever the client; it then needs JavaScript, a client that cannot serve the challenge cannot register, and the legacy `POST /auth/register` ignores it. |
| `botChallenge.difficulty`       | `18`    | `BOT_CHALLENGE_DIFFICULTY`          | higher        | `security` when loosened (`credential-path`), else `write` | How many leading zero bits the built-in proof of work asks for; each one doubles the work of the page that solves it, and 18 takes a browser a second or two.                                                                                                  |

### `passkeys`

| Field                       | Default | Seeded from                   | Stricter when | Class   | Description                                                                                                                                                                                                                               |
| --------------------------- | ------- | ----------------------------- | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `passkeys.offerAfterSignIn` | `true`  | `PASSKEY_OFFER_AFTER_SIGN_IN` | `true`        | `write` | Whether the hosted sign-in offers to add a passkey after a password sign-in, to a verified account whose only factor is that password, while passkeys are on (`WEBAUTHN_ENABLED`); a passkey added from the account page is not affected. |

### `registration`

| Field                                           | Default                                        | Seeded from                           | Stricter when                                            | Class                                                    | Description                                                                                                                                                                      |
| ----------------------------------------------- | ---------------------------------------------- | ------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `registration.dynamicRegistrationAllowedScopes` | `openid`, `profile`, `email`, `offline_access` | `DEFAULT_DYNAMIC_REGISTRATION_SCOPES` | fewer entries                                            | `security` when loosened (`token-content`), else `write` | The scopes a dynamically registered client may hold; a scope outside the list is dropped from the registration, and no scope of the reserved qauth: namespace can be listed.     |
| `registration.cimd.enabled`                     | `true`                                         | `CIMD_ENABLED`                        | `false`                                                  | `security` when loosened (`token-content`), else `write` | Whether an HTTPS URL is accepted as a client_id, its metadata fetched from that URL (Client ID Metadata Documents).                                                              |
| `registration.cimd.trustPolicy`                 | `accept-any-https`                             | `CIMD_TRUST_POLICY`                   | closer to `allowlist` (`accept-any-https` < `allowlist`) | `security` when loosened (`token-content`), else `write` | Which hosts a metadata-document client_id may have: any HTTPS host, or only the trusted domains.                                                                                 |
| `registration.cimd.trustedDomains`              | empty                                          | `CIMD_TRUSTED_DOMAINS`                | fewer entries                                            | `security` when loosened (`token-content`), else `write` | The hosts the allowlist policy accepts, stored in lower case; an entry `*.example.com` accepts every subdomain of `example.com` but not `example.com` itself. Environment-bound. |

### `mail`

| Field                                   | Default | Seeded from                                        | Stricter when | Class                                                        | Description                                                                                                                                        |
| --------------------------------------- | ------- | -------------------------------------------------- | ------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mail.provider`                         | `mock`  | `EMAIL_PROVIDER`                                   | not ordered   | `security` on any change (`credential-path`)                 | Which transport sends the realm mail: mock (logs only), resend or smtp. Environment-bound.                                                         |
| `mail.fromAddress`                      | none    | `EMAIL_FROM_ADDRESS`                               | not ordered   | `security` on any change (`credential-path`)                 | The address the realm mail is sent from. Environment-bound.                                                                                        |
| `mail.fromName`                         | `QAuth` | `EMAIL_FROM_NAME`                                  | not ordered   | `security` on any change (`credential-path`)                 | The sender name the realm mail shows. Environment-bound.                                                                                           |
| `mail.smtp.host`                        | none    | `SMTP_HOST`                                        | not ordered   | `security` on any change (`credential-path`)                 | The SMTP server the smtp transport connects to. Environment-bound.                                                                                 |
| `mail.smtp.port`                        | none    | `SMTP_PORT`                                        | not ordered   | `security` on any change (`credential-path`)                 | The port of the SMTP server. Environment-bound.                                                                                                    |
| `mail.smtp.secure`                      | `true`  | `SMTP_SECURE`                                      | not ordered   | `security` on any change (`credential-path`)                 | Whether the SMTP connection uses TLS from its start. Environment-bound.                                                                            |
| `mail.smtp.user`                        | none    | `SMTP_USER`                                        | not ordered   | `security` on any change (`credential-path`)                 | The user name the smtp transport signs in with. Environment-bound.                                                                                 |
| `mail.smtp.password`                    | none    | `SMTP_PASSWORD`                                    | not ordered   | `security` on any change (`credential-path`)                 | The password the smtp transport signs in with. Secret: write-only, never stored in the policy document, shown as `passwordSet`. Environment-bound. |
| `mail.resend.apiKey`                    | none    | `RESEND_API_KEY`                                   | not ordered   | `security` on any change (`credential-path`)                 | The API key the resend transport sends with. Secret: write-only, never stored in the policy document, shown as `apiKeySet`. Environment-bound.     |
| `mail.verificationTokenExpirySeconds`   | `86400` | `EMAIL_VERIFICATION_TOKEN_EXPIRY`                  | lower         | `security` when loosened (`posture-loosening`), else `write` | How long a verification link is valid, in seconds, at least one hour. Environment-bound.                                                           |
| `mail.invalidateExistingTokensOnResend` | `true`  | `EMAIL_VERIFICATION_INVALIDATE_EXISTING_ON_RESEND` | `true`        | `write`                                                      | Whether sending a new verification link makes the earlier ones invalid, so only the latest works. Environment-bound.                               |

### `posture`

| Field                          | Default      | Seeded from | Stricter when                                                     | Class                                                        | Description                                                                                                                                                              |
| ------------------------------ | ------------ | ----------- | ----------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `posture.maxEnvironmentLaxity` | `production` | none        | closer to `production` (`development` < `staging` < `production`) | `security` when loosened (`posture-loosening`), else `write` | The laxest environment profile a client of the realm may get; a client set to a laxer one gets this one. Environment-bound. [More](/operate/environment-authorization/). |

### `admin`

| Field                               | Default | Seeded from | Stricter when | Class                                       | Description                                                                                                        |
| ----------------------------------- | ------- | ----------- | ------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `admin.twoAdminMandatoryOperations` | empty   | none        | more entries  | `security` on any change (`administration`) | The admin operations that need a second admin approval in this realm, by operation id.                             |
| `admin.workloadIssuers`             | empty   | none        | fewer entries | `security` on any change (`administration`) | The HTTPS issuers whose workload tokens a CI service account may exchange for admin API tokens. Environment-bound. |

## Versions

The schema version is a string. Until QAuth 1.0.0 it is `1-rc.<M>`, and nothing about it is
promised: a breaking change raises `<M>`
([ADR-018 §5](/reference/records/adr/018-1-0-scope-and-stability/)). From the release that ships
1.0.0 it is `1`, and inside version 1 every change is additive: a new field comes with a default,
and no field is removed. Other areas add their groups to the same schema, such as browser sessions
and sign-in methods; a group's name is taken once.

A realm keeps its policies under the schema version they were written in. A release that changes
the version reads a document of an older one through an upgrade it ships, which never reads a
field looser than stored, and its first boot stores the document under the new version. A
document of a later version, which a newer node wrote during a rolling upgrade, is read with the
older node's schema and never written by it.

The effects named above are the closed list of 11 effect tags on
[Security operations](/reference/security-operations/).

---

# Flow graphs

URL: https://docs.qauth.dev/reference/flow-graphs/

QAuth's flows are written as semantic graphs in delurio's `delurio-graph/0` format
([ADR-021](/reference/records/adr/021-flows-and-ui-as-semantic-graphs/)). A graph is the
specification of a flow: its states, every way it ends, and the guarantees it keeps. delurio
renders each one as a page with its diagram, served under `/graphs/` (the links are in the list
below; the pages are generated at build time, so they are not content pages of this site).

**None of these graphs is approved yet.** Each one carries a status:

- `captured` records what QAuth does today;
- `proposed` is a design under review.

The YAML in [`graphs/` on GitHub](https://github.com/qauth-labs/qauth/tree/main/graphs) is the
source of record. A rendered page is a view of it and says so at its top; read a graph's status
and history on GitHub. The graphs are outside QAuth's 1.0 stability promise (ADR-021 Decision 6).

<GraphList />

Every rendered page also has its diagram as Mermaid source, at `flow.mmd` next to the page. The
same list, with links for language models, is in `/llms.txt`.

---

# Flow graphs

QAuth's flows are specified as delurio semantic graphs (ADR-021). None of them is approved yet: `captured` records what QAuth does today, `proposed` is a design under review. The YAML on GitHub is the source of record; each page here is a view rendered from it, and the graphs are outside QAuth's 1.0 stability promise.

- [Open the hosted account page, and start its sign-in ceremonies](https://docs.qauth.dev/graphs/flows/account/account-page/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/account/account-page; diagram https://docs.qauth.dev/graphs/flows/account/account-page/flow.mmd
- [Change the account's sign-in methods and sessions from the hosted account page](https://docs.qauth.dev/graphs/flows/account/account-page-changes/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/account/account-page-changes; diagram https://docs.qauth.dev/graphs/flows/account/account-page-changes/flow.mmd
- [Unlink an upstream account from the account](https://docs.qauth.dev/graphs/flows/account/unlink-upstream/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/account/unlink-upstream; diagram https://docs.qauth.dev/graphs/flows/account/unlink-upstream/flow.mmd
- [Enable and disable an AuthMethod plugin in a realm](https://docs.qauth.dev/graphs/flows/admin/plugin-enable/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/admin/plugin-enable; diagram https://docs.qauth.dev/graphs/flows/admin/plugin-enable/flow.mmd
- [Verify an account's address after its correct password](https://docs.qauth.dev/graphs/flows/core/account-verification/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/account-verification; diagram https://docs.qauth.dev/graphs/flows/core/account-verification/flow.mmd
- [Authorize a client for the signed-in user](https://docs.qauth.dev/graphs/flows/core/authorization/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/authorization; diagram https://docs.qauth.dev/graphs/flows/core/authorization/flow.mmd
- [Tell each app a browser session signed in to that the session ended](https://docs.qauth.dev/graphs/flows/core/backchannel-logout/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/backchannel-logout; diagram https://docs.qauth.dev/graphs/flows/core/backchannel-logout/flow.mmd
- [Register a client, and refuse an agent to an owner who is not verified](https://docs.qauth.dev/graphs/flows/core/client-registration/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/client-registration; diagram https://docs.qauth.dev/graphs/flows/core/client-registration/flow.mmd
- [Ask the signed-in person to allow a client's access, as a step of the Interaction API](https://docs.qauth.dev/graphs/flows/core/consent/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/consent; diagram https://docs.qauth.dev/graphs/flows/core/consent/flow.mmd
- [Ask the user to approve a client's access](https://docs.qauth.dev/graphs/flows/core/consent-page/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/consent-page; diagram https://docs.qauth.dev/graphs/flows/core/consent-page/flow.mmd
- [Sign the browser out at an app's request, and send it back to the app](https://docs.qauth.dev/graphs/flows/core/logout/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/logout; diagram https://docs.qauth.dev/graphs/flows/core/logout/flow.mmd
- [Sign out with an access token](https://docs.qauth.dev/graphs/flows/core/logout-token/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/logout-token; diagram https://docs.qauth.dev/graphs/flows/core/logout-token/flow.mmd
- [Sign in with a passkey, prove it on a passkey-bound account, and bind one after a sign-in](https://docs.qauth.dev/graphs/flows/core/passkey/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/passkey; diagram https://docs.qauth.dev/graphs/flows/core/passkey/flow.mmd
- [Register an account with a passkey alone, and recover it with a recovery code](https://docs.qauth.dev/graphs/flows/core/passkey-sign-up/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/passkey-sign-up; diagram https://docs.qauth.dev/graphs/flows/core/passkey-sign-up/flow.mmd
- [Reset a password, the mailbox first, never past another authenticator](https://docs.qauth.dev/graphs/flows/core/password-reset/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/password-reset; diagram https://docs.qauth.dev/graphs/flows/core/password-reset/flow.mmd
- [Redeem a recovery code in place of a lost factor, and show a new set once](https://docs.qauth.dev/graphs/flows/core/recovery-code/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/recovery-code; diagram https://docs.qauth.dev/graphs/flows/core/recovery-code/flow.mmd
- [Decide a sign-in, one round at a time](https://docs.qauth.dev/graphs/flows/core/sign-in/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/sign-in; diagram https://docs.qauth.dev/graphs/flows/core/sign-in/flow.mmd
- [Sign in with a password in the browser](https://docs.qauth.dev/graphs/flows/core/sign-in-page/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/sign-in-page; diagram https://docs.qauth.dev/graphs/flows/core/sign-in-page/flow.mmd
- [Sign in with a password for tokens](https://docs.qauth.dev/graphs/flows/core/sign-in-token/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/sign-in-token; diagram https://docs.qauth.dev/graphs/flows/core/sign-in-token/flow.mmd
- [Register a password account, the mailbox first](https://docs.qauth.dev/graphs/flows/core/sign-up/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/sign-up; diagram https://docs.qauth.dev/graphs/flows/core/sign-up/flow.mmd
- [Prove a bound TOTP after the first factor, and bind a new one when the MFA policy needs it](https://docs.qauth.dev/graphs/flows/core/totp/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/totp; diagram https://docs.qauth.dev/graphs/flows/core/totp/flow.mmd
- [Link an upstream account to an existing account by signing in to it](https://docs.qauth.dev/graphs/flows/federation/upstream-link/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/federation/upstream-link; diagram https://docs.qauth.dev/graphs/flows/federation/upstream-link/flow.mmd
- [Sign in, or sign up, through one of the realm's upstream identity providers](https://docs.qauth.dev/graphs/flows/federation/upstream-sign-in/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/federation/upstream-sign-in; diagram https://docs.qauth.dev/graphs/flows/federation/upstream-sign-in/flow.mmd
- [Sign in at an upstream provider through an AuthMethod](https://docs.qauth.dev/graphs/flows/federation/upstream-step/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/federation/upstream-step; diagram https://docs.qauth.dev/graphs/flows/federation/upstream-step/flow.mmd