Authentication

A request proves who sent it in one of these ways. Each operation lists the schemes it accepts.

Scheme	Carried as
`apiKeyAuth`	API key in the `x-api-key` header
`bearerAuth`	HTTP `bearer`
`Klock`	HTTP `Klock`
`delegatedBearer`	HTTP `bearer`
`transferRunnerToken`	HTTP `bearer`
`transferKlockV1`	API key in the `X-Transfer-Klock` header

`apiKeyAuth`

A key issued for one database, as prk_<prefix>.<secret>. It is shown
once when issued and stored only as a hash, so it cannot be read back.

`bearerAuth`

The token from /signin or /verify. Every token carries a jti and
has a session behind it, so one can be signed out without changing the
signing key and ending everybody's day.

`Klock`

Klock v2: a device-bound session. Every request carries
Authorization: Klock <grant> — the grant is a JWS the API signed when
the session was opened (or last refreshed), naming the session, the
device key's thumbprint and the capabilities it may carry — and an
RFC 9421 HTTP message signature (Signature-Input, Signature) made by
that device key over the request, the body included. The API checks the
grant, the signature, the nonce (single-use for anything that changes
state, and for any request made with a live admin:* capability), then
the session row, which must exist and be live. The capabilities are the
grant's intersected with what the account may do right now, so a
demoted team role or a withdrawn admin scope takes effect at once.

A refusal is { error, message } with a code from the klock error
catalog (KlockErrorCode), and a 401 carries
WWW-Authenticate: Klock error="<code>".

Where no grant exists yet — opening a session, the guest grant, and a
service session that has not synced its grant — the header is
Authorization: Klock device=<thumbprint> instead, signed the same way
by the device key (whose public key travels in the body, or in
Klock-Device-Pub). Every route that takes a bearer token also takes
this scheme.

`delegatedBearer`

A delegated MCP client token, prorm_dt_<…>, made with
POST /security/mcp/clients and shown once. It is accepted only by
GET /security/mcp/capabilities and POST /security/mcp/call — never
by a route that takes an account's own bearer — and every call is
re-checked against the MCP tool registry and the token's delegated
capabilities. It never carries an admin:* capability.

`transferRunnerToken`

The shared MIGRATE_RUNNER_TOKEN the platform's transfer runner holds.
Accepted only by POST /transfer/jobs/{jobId}/events; with no token
configured, nothing matches it.

`transferKlockV1`

A v1 transfer klock report MAC for a local job — base64url
HMAC-SHA256 with the job's klockSecret over transfer/report/v1, a
zero byte, and <jobId>.<status>.<30-second window>. Also accepted as
Authorization: klock <mac>. Only POST /transfer/jobs/{jobId}/events.

apiKeyAuth#

bearerAuth#

Klock#

delegatedBearer#