# API

Every operation of the strazad HTTP API by method and path, with its summary, the credential it takes, its request body, its answers and the objects they carry, from the OpenAPI document.


The strazad HTTP API is the REST surface of the server, and every tool that talks to strazad speaks it: strazactl, the console, the self-service page, the Straza approver app and the straza client. Its contract is the OpenAPI 3.1 document `pkg/api/openapi.yaml` in the repository, at version 0.166.0, and two tests in the server package fail the build when the route table and the document diverge. This page lists every operation the document declares, 141 operations on 117 paths, and `make docs-gen` rewrites it from the document.

Paths are relative to the server's public URL, so on a standalone server with its default listener the users list is `http://127.0.0.1:8420/v1/admin/users`. Every request and answer body is JSON. A route under `/v1/admin` answers 400 to a request body that carries a field the route does not take, and the answer names the field. On the same listener, outside this document, sit the MCP gateway at `/mcp`, the SCIM 2.0 endpoint whose contract is the SCIM profile specification, the console under `/console/`, the self-service page under `/approvals/`, the metrics endpoint at `/metrics` and the built-in issuer under `/oidc/`, which signs people in through the browser at `/oidc/authorize` and with a code at `/oidc/device` in the standalone profile, and in the enterprise profile serves the client credentials grant with its discovery document, so an AI agent can authenticate at Straza itself, and the same two sign-in pages for the break-glass admin alone.

## Authentication

The document declares 6 security schemes. `adminAPIToken` is an HTTP bearer token, described in the document as "An admin API token (prefix wat_), which a person mints in the console under Settings, API tokens, with a scope and an expiry. On the connect routes since 0.155.0 a read needs apps:read, a write needs apps:write, and full grants both, as on the admin API. A token is no user, so each request names the user it acts for. Since 0.157.0 a token that Straza cannot read from its database is refused with 503 and a Retry-After header, the same answer for a real token and a forged one", and 4 of the 141 operations declare it. 101 of the 141 operations declare `adminBearer`, an HTTP bearer token described in the document as "A session token or an ID token whose user holds the straza-admin role or a role mapped in admin.roleAreas, or an admin API token (prefix wat_, minted by strazactl api-token create) whose scope covers the route's area. The scim area of the same token is what opens /scim/v2. A session that a coding harness checked in is refused whatever roles its user holds, because the agent in that harness holds the token; the sessions of the console and the self-service page pass. Since 0.155.0 a session that strazactl started is refused with 403 and one login failure, because strazactl no longer signs in. The user must be a person: an AI agent or a service account is refused on every admin route whatever roles it holds, a session whose user is disabled or locked is refused on its next request, and an ID token of a disabled or locked user is refused with 403 and one login failure record. A session token bound to a key is accepted only under the DPoP scheme with a proof, as sessionDPoP says. Since 0.157.0 an admin API token that Straza cannot read from its database is refused with 503 and a Retry-After header, the same answer for a real token and a forged one". `approverBearer` is an HTTP bearer token, described in the document as "The approver device token a phone or a browser receives at approver enrollment; every other token kind is refused", and 6 of the 141 operations declare it. 11 of the 141 operations declare `sessionBearer`, an HTTP bearer token described in the document as "The session token a client received at check-in; it names the only session the route acts on. A token bound to a key is refused under this scheme and goes under sessionDPoP". `sessionDPoP` is an HTTP DPoP token, described in the document as "A session token bound to a key, which /v1/checkin mints with cnf.jkt on the key lane and on an AI agent's id_token check-in with a proof, sent as Authorization DPoP with a proof from that key in the DPoP header (RFC 9449). The proof has the request's method as htm, its URL without the query as htu, under the origin the DPoP parameter names, a fresh jti, the newest DPoP-Nonce the server sent as nonce, and ath, the base64url SHA-256 of the token. Such a token with no valid proof, or under Bearer, is refused with 401, the WWW-Authenticate error invalid_dpop_proof and one authn proof failure record. A missing or stale nonce answers the nonce challenge, and a token without cnf under this scheme is refused as an invalid token. The push stream is proven once, when it opens", and 13 of the 141 operations declare it. 6 of the 141 operations declare `userBearer`, an HTTP bearer token described in the document as "A person's session token or ID token. An admin API token is refused because it carries no user, so it can neither decide nor speak for itself. An ID token of a disabled or locked user is refused with 403 and one login failure record. A session token bound to a key is accepted only under the DPoP scheme with a proof, as sessionDPoP says". The 15 operations that declare none are `GET /healthz`, `GET /readyz`, `GET /version`, `GET /.well-known/straza/jwks.json`, `GET /.well-known/straza/snapshot-keys.json`, `GET /.well-known/straza/client-assertion-jwks.json`, `GET /.well-known/straza/idp.json`, `POST /v1/enroll`, `POST /v1/checkin`, `GET /v1/harness-config`, `GET /v1/connect/callback`, `POST /v1/approval/callbacks/slack`, `POST /v1/approver/enroll`, `POST /v1/approver/refresh/challenge` and `POST /v1/approver/refresh`, and their tables below say `none` in the last column.

Which token a bearer route takes depends on the route, and the scheme each operation declares names its lane. The admin routes under `/v1/admin/` take a session token or a console login token whose user holds the `straza-admin` role or a role mapped to admin areas, or an admin API token (prefix `wat_`) whose scope covers the area, and refuse everything else with 401 or 403 and a sentence naming the missing scope. `/v1/decide`, `/v1/audit/batch`, `/v1/push` and `/v1/session/revoke` take the session token a client received at check-in, and that token names the only session they act on. `/v1/audit/batch` also files a record under an earlier session its record names, when that session belongs to the same user on the same device. `/v1/snapshot` takes the same token in the enterprise profile and answers without one in the standalone profile. `/v1/self`, `/v1/approvals/self/enroll-token` and the approve and deny routes under `/v1/admin/approvals/` take any active user's session or login token and refuse an admin API token, and the handler checks the approver roles itself. `/v1/connect` and `/v1/connect/{app}` take a user's session, an AI agent's included, or an admin API token whose scope holds `apps:read` for a read or `apps:write` for a change and that names the user it acts for. The POST of `/v1/connect/callback` and `/v1/self/servers` take a user's session only. The `/v1/approver/` routes take the approver device token a phone receives at enrollment and refuse every other token kind. An operation that declares no scheme is either public by design (the probes, the discovery documents and the harness config, none of which carries a secret) or carries its credential inside the request: the enroll and check-in bodies, the `DPoP` proof header of a key enrollment, a key check-in and an AI agent's ID-token check-in, the one-time enroll token of the approver enrollment, the device-key signature over a refresh challenge, and the Slack signature header on the Slack callback.

A device that enrolled with a key proves every request with that key, as RFC 9449 describes. Its enroll and check-in requests carry a `DPoP` header with a proof, a JWT the device's Ed25519 key signs for that one request, and the session token the key lane mints is bound to the key by its `cnf.jkt` claim. On a check-in the proof also signs the body's counter in its `ctr` claim, so nobody without the key can change the counter. Each proof id (`jti`) is spent in the store that every replica shares, on a check-in once the device is identified, on an enrollment once the ID token verifies and on an AI agent's ID-token check-in once its ID token and proof verify, so a replayed proof is refused with 401 on any replica, with one login failure on a check-in and no record on an enrollment. Because a counter at or below the last one accepted revokes the device, a client sends each counter at most once, records it before sending, resends it only after the nonce challenge with a fresh proof, and never runs two key check-ins for one device at once. Only a person then enrolls a machine key, so an AI agent or a service account is refused with 403 and one login failure. The straza client enrolls a person's machine and checks it in only with a key, so a device it enrolled without one is refused with 403 on every lane. strazactl no longer signs in, so its device token is refused as well, and no client checks in with a device token. A person's key enrollment reports where its key is kept in `custody`, and a kind below the server's `governance.minCustody` is refused with 403 at the enrollment, at every key check-in and at every refresh of the device's sessions. The server cannot prove the reported kind, and an AI agent's key carries none. An AI agent's ID-token check-in may carry a proof as well, without `ctr`, and the session token it mints is then bound to the proof's key in the same way. Without a proof it still mints a token without the binding on the standalone profile, and the enterprise profile refuses it. A person's key enrollment also needs a sign-in made for that key: the ID token's nonce names the key, a browser sign-in is at most 10 minutes old, and `governance.minSignIn` can refuse a device code sign-in. Each enrollment brings a new key: a key already enrolled for the user is refused with 409, and a re-enrollment with a new key replaces the old one and starts the counter at 0. With the bound token, a request sends `Authorization: DPoP <token>` and a fresh proof whose `ath` claim hashes the token, on every route that takes a session token. The origin of a proof's `htu` must be the origin of `server.publicUrl`, and the origin the request arrived on is accepted as well only when `server.publicUrl` is unset, or when both are loopback hosts with the same scheme and port. The same token under `Bearer`, or with no valid proof, is refused with 401, `WWW-Authenticate: DPoP error="invalid_dpop_proof"` and one audit record, so a copied token works nowhere else. Every proof carries the server's newest nonce. When a proof has no nonce or a stale one, the answer is 401 with `WWW-Authenticate: DPoP error="use_dpop_nonce"` and a fresh nonce in the `DPoP-Nonce` header, and the client signs the request again with it. Every answer to a request that carried a `DPoP` header carries a fresh `DPoP-Nonce`, and the client keeps the newest one for its next proof. A token without the binding keeps the `Bearer` scheme, and nothing changes for it.

## Errors

An error answer is a JSON object whose `error` field is a sentence that says what failed, and on a 5xx or a recovered panic the object also carries `correlation_id`, the value of the `X-Request-Id` response header and of the matching server log record. Every answer carries `X-Request-Id`. A client-supplied id of at most 64 printable ASCII bytes is echoed, and anything else is replaced by a minted UUIDv7. When the server cannot reach its store while checking a credential it answers 503 with a `Retry-After` header and a generic body, which tells the client to retry and never to drop a credential. The approver surface adds a `code` field the phone app branches on before it touches its hardware key, one of `missing_token`, `token_expired`, `token_invalid`, `device_revoked`, `user_inactive`, `challenge_rejected`, `not_authorized`, `invalid_cursor` or `service_unavailable`.

## Health and discovery

Probes and discovery documents that every client reads before it authenticates.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/healthz` | Liveness probe (no auth, no dependencies dialed) | none |
| GET | `/readyz` | Readiness probe, pings store and bus (3 s bound) | none |
| GET | `/version` | Build/profile stamp plus the approver pin block (contract-bearing) | none |
| GET | `/.well-known/straza/jwks.json` | Token-verification JWKS (Cache-Control max-age=60) | none |
| GET | `/.well-known/straza/snapshot-keys.json` | Policy-snapshot signing keys clients pin at enroll (Cache-Control max-age=60) | none |
| GET | `/.well-known/straza/client-assertion-jwks.json` | Public keys of the client assertion key, the JWKS URL of every agent's client at the identity provider (Cache-Control max-age=30) | none |
| GET | `/.well-known/straza/idp.json` | Login discovery, which issuer a client authenticates against | none |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /healthz` | 200 | an object with `status` |
| `GET /readyz` | 200 | `ReadyStatus` |
| `GET /readyz` | 503 | `ReadyStatus` |
| `GET /version` | 200 | `VersionStatus` |
| `GET /.well-known/straza/jwks.json` | 200 | an object with `keys` |
| `GET /.well-known/straza/jwks.json` | 500 | `Error` |
| `GET /.well-known/straza/snapshot-keys.json` | 200 | `SnapshotKeys` |
| `GET /.well-known/straza/client-assertion-jwks.json` | 200 | an object with `keys` |
| `GET /.well-known/straza/client-assertion-jwks.json` | 503 | `Error` |
| `GET /.well-known/straza/idp.json` | 200 | `IdPDiscovery` |
| `GET /.well-known/straza/idp.json` | 503 | an object with `error` |

## Enrollment and check-in

A client enrolls its device here, starts a session, and fetches the signed policy snapshot, the managed harness config and the push stream.

| Method | Path | Summary | Security |
|---|---|---|---|
| POST | `/v1/enroll` | Enroll an authenticated identity on a device | none |
| POST | `/v1/checkin` | Start or refresh a session; returns session token and packs | none |
| GET | `/v1/push` | Stream kill-switch revocations and policy refresh hints as server-sent events, scoped to the caller's own session, device and user | `sessionBearer` or `sessionDPoP` |
| GET | `/v1/snapshot` | Fetch the active signed policy snapshot (CBOR; ETag = snapshot id) | `sessionBearer` or `sessionDPoP` |
| GET | `/v1/harness-config` | Fetch the signed, server-rendered managed harness config for one harness and platform | none |
| POST | `/v1/session/revoke` | End the session the caller's own token names (logout) | `sessionBearer` or `sessionDPoP` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/enroll` | `id_token` | string | yes | The ID token of the person's sign-in at the identity provider. |
| `POST /v1/enroll` | `client_kind` | string |  | The kind of client that enrols and holds the credential. One of `kit` or `human`. |
| `POST /v1/enroll` | `device` | object |  |  |
| `POST /v1/enroll` | `custody` | object |  | Where the device key is held, required on a key enrollment. |
| `POST /v1/enroll` | `machine_binding` | string |  | A value the key holder derives from the machine's identity, required on a key enrollment. |
| `POST /v1/enroll` | `counter` | integer |  | The key's check-in counter at enrollment, which must be 0. |
| `POST /v1/checkin` | `id_token` | string |  |  |
| `POST /v1/checkin` | `device_token` | string |  |  |
| `POST /v1/checkin` | `session_token` | string |  |  |
| `POST /v1/checkin` | `device_id` | string |  |  |
| `POST /v1/checkin` | `counter` | integer |  | The key lane's check-in counter, higher than the last one the server accepted for the device. |
| `POST /v1/checkin` | `harness` | object |  |  |
| `POST /v1/checkin` | `attestation` | object |  |  |
| `POST /v1/checkin` | `client` | object |  | The straza build making the check-in; older clients omit it and the server records it on the session unverified. |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `POST /v1/enroll` | 200 | `EnrollResponse` |
| `POST /v1/enroll` | 400 | `Error` |
| `POST /v1/enroll` | 401 | `ProofRefused` |
| `POST /v1/enroll` | 403 | `Error` |
| `POST /v1/enroll` | 409 | `Error` |
| `POST /v1/enroll` | 503 | `ServiceUnavailable` |
| `POST /v1/checkin` | 200 | `CheckinResponse` |
| `POST /v1/checkin` | 400 | `Error` |
| `POST /v1/checkin` | 401 | `ProofRefused` |
| `POST /v1/checkin` | 403 | `Error` |
| `POST /v1/checkin` | 503 | `ServiceUnavailable` |
| `GET /v1/push` | 200 | a text/event-stream body |
| `GET /v1/push` | 401 | `ProofRefused` |
| `GET /v1/push` | 503 | `Error` |
| `GET /v1/snapshot` | 200 | a application/cbor body |
| `GET /v1/snapshot` | 304 | an empty body |
| `GET /v1/snapshot` | 401 | `ProofRefused` |
| `GET /v1/snapshot` | 503 | `Error` |
| `GET /v1/harness-config` | 200 | `HarnessConfigDocument` |
| `GET /v1/harness-config` | 304 | an empty body |
| `GET /v1/harness-config` | 404 | `Error` |
| `POST /v1/session/revoke` | 200 | an object with `status` and `session` |
| `POST /v1/session/revoke` | 401 | `ProofRefused` |
| `POST /v1/session/revoke` | 500 | `Error` |

## Decisions and audit ingest

The server decision endpoint, the git grants and the ingest of client-spooled audit events.

| Method | Path | Summary | Security |
|---|---|---|---|
| POST | `/v1/decide` | Evaluate one canonical event against the caller's session and return the decision | `sessionBearer` or `sessionDPoP` |
| POST | `/v1/audit/batch` | Ingest a batch of client-spooled audit events (`straza service` drains its spool here) | `sessionBearer` or `sessionDPoP` |
| POST | `/v1/grants/resolve` | Say whether Straza serves git for a repo URL, and name the server and the canonical repo | `sessionDPoP` |
| POST | `/v1/grants` | Decide one git fetch or push of one repo and answer a short git grant for its resource server | `sessionDPoP` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/decide` | `event` | `CanonicalEvent` | yes |  |
| `POST /v1/decide` | `agentType` | string |  | The delegate kind the harness attributed the call to, absent for the main agent; it lands on the server's audit record. |
| `POST /v1/decide` | `agentId` | string |  | The delegate instance id, absent for the main agent. |
| `POST /v1/decide` | `nativeTool` | string |  | The harness's own name of a classified local tool, such as Bash for shell.exec, which a policy rule that names harness tools reads. |
| `POST /v1/decide` | `toolInput` | object |  | The input of a classified local tool for the audit record, as the client cut it. |
| `POST /v1/audit/batch` | `events` | list of object |  |  |
| `POST /v1/grants/resolve` | `upstream` | string | yes | The URL git was given, such as https://github.com/Strazahq/straza.git. |
| `POST /v1/grants` | `upstream` | string | yes | The URL git was given, as the resolve route takes it. |
| `POST /v1/grants` | `op` | string | yes | The git operation the grant opens. One of `fetch` or `push`. |
| `POST /v1/grants` | `refs` | list of `GitRefUpdate` |  | The ref updates a push names, allowed with op push only. |
| `POST /v1/grants` | `waitSeconds` | integer |  | How long a hold may keep this request waiting, from 0 to approval.gatewayHoldSeconds. |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `POST /v1/decide` | 200 | `Decision` |
| `POST /v1/decide` | 400 | `Error` |
| `POST /v1/decide` | 401 | `ProofRefused` |
| `POST /v1/audit/batch` | 200 | an object with `accepted` and `refused` |
| `POST /v1/audit/batch` | 400 | `Error` |
| `POST /v1/audit/batch` | 401 | `ProofRefused` |
| `POST /v1/audit/batch` | 403 | `Error` |
| `POST /v1/audit/batch` | 413 | `Error` |
| `POST /v1/audit/batch` | 429 | an object with `error` |
| `POST /v1/audit/batch` | 503 | an object with `error` |
| `POST /v1/grants/resolve` | 200 | `GitResolveResponse` |
| `POST /v1/grants/resolve` | 400 | `Error` |
| `POST /v1/grants/resolve` | 401 | `ProofRefused` |
| `POST /v1/grants/resolve` | 403 | `Error` |
| `POST /v1/grants/resolve` | 404 | `GitRefusal` |
| `POST /v1/grants/resolve` | 409 | `GitRefusal` |
| `POST /v1/grants` | 200 | `GitGrantResponse` |
| `POST /v1/grants` | 202 | `GitGrantHeld` |
| `POST /v1/grants` | 400 | `Error` |
| `POST /v1/grants` | 401 | `ProofRefused` |
| `POST /v1/grants` | 403 | an object with `error` |
| `POST /v1/grants` | 404 | `GitRefusal` |
| `POST /v1/grants` | 409 | `GitRefusal` |
| `POST /v1/grants` | 503 | an object with `error` and `correlation_id` |

## The calling user

What a signed-in person reads and does about themself: identity, OAuth connections and approver enrollment.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/connect` | List the acting user's connection on every caller-kind MCP server (oauth or token), never a value | `adminAPIToken` or `sessionBearer` or `sessionDPoP` |
| GET | `/v1/connect/callback` | OAuth provider redirect target (browser-facing): redeems and stores nothing, and hands the provider's answer to the Credentials tab | none |
| POST | `/v1/connect/callback` | Finish a provider sign-in for the signed-in user, only when the state names that user | `sessionBearer` or `sessionDPoP` |
| POST | `/v1/connect/{app}` | Connect the acting user to one MCP server: paste a token on a token-kind server, or begin the OAuth sign-in on an oauth-kind server | `adminAPIToken` or `sessionBearer` or `sessionDPoP` |
| PATCH | `/v1/connect/{app}` | Allow or forbid the owner's sponsored agents to run on this connection | `adminAPIToken` or `sessionBearer` or `sessionDPoP` |
| DELETE | `/v1/connect/{app}` | Remove the acting user's connection on one MCP server, OAuth or pasted token | `adminAPIToken` or `sessionBearer` or `sessionDPoP` |
| POST | `/v1/approvals/self/enroll-token` | Mint a one-time approver enroll token for the CALLING user (self-service) | `userBearer` |
| GET | `/v1/self` | The calling user's identity, admin standing, and enrollment eligibility | `userBearer` |
| GET | `/v1/self/servers` | The servers the acting user reaches or is connected to, with the state of their account on each | `sessionBearer` or `sessionDPoP` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/connect/callback` | `code` | string | yes | The one-time code the provider handed the browser |
| `POST /v1/connect/callback` | `state` | string | yes | The signed state of the sign-in |
| `POST /v1/connect/{app}` | `token` | string |  | The pasted token (token-kind servers only |
| `POST /v1/connect/{app}` | `expires_at` | string |  | When the token stops working |
| `POST /v1/connect/{app}` | `user` | string |  | Act for this user (username or id), for a person who is the user's sponsor or an administrator. |
| `PATCH /v1/connect/{app}` | `allow_agents` | boolean | yes |  |
| `PATCH /v1/connect/{app}` | `user` | string |  | Act for this user, for a person who is the user's sponsor or an administrator. |
| `POST /v1/approvals/self/enroll-token` | `channel` | string | yes | Which device class this token may enroll. One of `mobile` or `browser`. |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/connect` | 200 | a list of `ConnectStatus` |
| `GET /v1/connect` | 401 | `ProofRefused` |
| `GET /v1/connect` | 403 | `Error` |
| `GET /v1/connect` | 404 | `Error` |
| `GET /v1/connect` | 503 | `ServiceUnavailable` |
| `GET /v1/connect/callback` | 303 | an empty body |
| `GET /v1/connect/callback` | 400 | a text/html body |
| `POST /v1/connect/callback` | 200 | an object with `app`, `provider`, `kind` and `allow_agents` |
| `POST /v1/connect/callback` | 400 | an empty body |
| `POST /v1/connect/callback` | 401 | `ProofRefused` |
| `POST /v1/connect/callback` | 403 | an empty body |
| `POST /v1/connect/callback` | 409 | an empty body |
| `POST /v1/connect/callback` | 500 | an empty body |
| `POST /v1/connect/callback` | 502 | an empty body |
| `POST /v1/connect/callback` | 503 | `ServiceUnavailable` |
| `POST /v1/connect/{app}` | 200 | an object with `app`, `provider`, `authorize_url`, `page_url`, `expires_in`, `user`, `kind`, `fingerprint`, `expires_at`, `set_by` and `allow_agents` |
| `POST /v1/connect/{app}` | 400 | `Error` |
| `POST /v1/connect/{app}` | 401 | `ProofRefused` |
| `POST /v1/connect/{app}` | 403 | `Error` |
| `POST /v1/connect/{app}` | 404 | `Error` |
| `POST /v1/connect/{app}` | 409 | `Error` |
| `POST /v1/connect/{app}` | 502 | an empty body |
| `POST /v1/connect/{app}` | 503 | `ServiceUnavailable` |
| `PATCH /v1/connect/{app}` | 200 | an object with `app`, `user` and `allow_agents` |
| `PATCH /v1/connect/{app}` | 400 | `Error` |
| `PATCH /v1/connect/{app}` | 401 | `ProofRefused` |
| `PATCH /v1/connect/{app}` | 403 | `Error` |
| `PATCH /v1/connect/{app}` | 404 | `Error` |
| `PATCH /v1/connect/{app}` | 503 | `ServiceUnavailable` |
| `DELETE /v1/connect/{app}` | 200 | an object with `app`, `user` and `status` |
| `DELETE /v1/connect/{app}` | 401 | `ProofRefused` |
| `DELETE /v1/connect/{app}` | 403 | `Error` |
| `DELETE /v1/connect/{app}` | 404 | `Error` |
| `DELETE /v1/connect/{app}` | 503 | `ServiceUnavailable` |
| `POST /v1/approvals/self/enroll-token` | 200 | `ApproverEnrollTokenResponse` |
| `POST /v1/approvals/self/enroll-token` | 400 | `Error` |
| `POST /v1/approvals/self/enroll-token` | 401 | `Error` |
| `POST /v1/approvals/self/enroll-token` | 403 | `Error` |
| `POST /v1/approvals/self/enroll-token` | 429 | `Error` |
| `GET /v1/self` | 200 | an object with `username`, `user_kind`, `admin_grants`, `enroll_channels` and `sponsored` |
| `GET /v1/self` | 401 | `Error` |
| `GET /v1/self/servers` | 200 | a list of `ServerRow` |
| `GET /v1/self/servers` | 401 | `ProofRefused` |
| `GET /v1/self/servers` | 403 | `Error` |
| `GET /v1/self/servers` | 404 | `Error` |
| `GET /v1/self/servers` | 503 | `ServiceUnavailable` |

## Users and devices

Users, their enrolled devices, locks and the revocation rows the kill switch writes.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/users` | List users, with filters, a sort and enriched rows on the paged lane | `adminBearer` |
| POST | `/v1/admin/users` | Create a local user | `adminBearer` |
| GET | `/v1/admin/users/{id}` | Read one user, enriched with effective roles, locks, last seen, counts and the agent assertion-key posture | `adminBearer` |
| PATCH | `/v1/admin/users/{id}` | Update user fields (email, display, status, password) | `adminBearer` |
| DELETE | `/v1/admin/users/{id}` | Soft-delete a user (revokes sessions, ends role assignments with one audit record each, removes OAuth grants, an agent's key and approver devices, emits revocation) | `adminBearer` |
| POST | `/v1/admin/users/{id}/lock` | Lock a user (Straza-lane revocation that survives identity manager writes) | `adminBearer` |
| POST | `/v1/admin/users/{id}/unlock` | Unlock a user (lift every revocation lane) | `adminBearer` |
| GET | `/v1/admin/users/{id}/devices` | List a user's enrolled devices, an empty array when there are none, 404 for an unknown user | `adminBearer` |
| DELETE | `/v1/admin/users/{id}/devices/{deviceId}` | Revoke a device enrollment, so the machine's key starts no more sessions | `adminBearer` |
| GET | `/v1/admin/revocations` | List revocation rows, the rows the lock and kill-switch lanes write | `adminBearer` |
| GET | `/v1/admin/users/{id}/nhi-key` | Read an agent's assertion-key posture (presence, creation time and fingerprint), never the key | `adminBearer` |
| PUT | `/v1/admin/users/{id}/nhi-key` | Register (or rotate) an agent's headless assertion key | `adminBearer` |
| DELETE | `/v1/admin/users/{id}/nhi-key` | Revoke an agent's headless assertion key | `adminBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/admin/users` | `username` | string | yes |  |
| `POST /v1/admin/users` | `email` | string |  |  |
| `POST /v1/admin/users` | `display` | string |  |  |
| `POST /v1/admin/users` | `title` | string |  |  |
| `POST /v1/admin/users` | `password` | string |  | A person's password for the built-in sign-in page. |
| `POST /v1/admin/users` | `kind` | string |  | nhi provisions an agent identity, such as a headless AI agent. One of `human` or `nhi`. |
| `POST /v1/admin/users` | `user_type` | string |  | The type of an nhi, an AI agent or a service account. One of `agent` or `service`. |
| `PATCH /v1/admin/users/{id}` | `email` | string |  |  |
| `PATCH /v1/admin/users/{id}` | `display` | string |  |  |
| `PATCH /v1/admin/users/{id}` | `title` | string |  |  |
| `PATCH /v1/admin/users/{id}` | `status` | string |  | One of `active` or `disabled`. |
| `PATCH /v1/admin/users/{id}` | `password` | string |  | A person's new password. |
| `PATCH /v1/admin/users/{id}` | `user_type` | string |  | set or clear (empty) the typology; standalone-admin lane, since enterprise masters this over SCIM. One of `human`, `agent`, `service` or ``. |
| `PATCH /v1/admin/users/{id}` | `agency_mode` | string |  | One of `interactive`, `supervised`, `autonomous` or ``. |
| `PATCH /v1/admin/users/{id}` | `sponsor` | string |  |  |
| `PATCH /v1/admin/users/{id}` | `swarm_id` | string |  |  |
| `PATCH /v1/admin/users/{id}` | `ephemeral` | boolean |  |  |
| `PATCH /v1/admin/users/{id}` | `entra_agent_id` | string |  | Sets the client id of the Entra agent identity the agent acts as at Entra, a GUID in any case, stored in lower case. |
| `POST /v1/admin/users/{id}/lock` | `reason` | string | yes | shown on the audit chain and in the SCIM lock block |
| `POST /v1/admin/users/{id}/lock` | `origin` | string |  | One of `admin` or `external`. |
| `PUT /v1/admin/users/{id}/nhi-key` | `public_key` | string | yes | base64 (std) raw Ed25519 public key, 32 bytes |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/users` | 200 | a list of `User` |
| `POST /v1/admin/users` | 201 | `User` |
| `POST /v1/admin/users` | 400 | `Error` |
| `POST /v1/admin/users` | 409 | `Error` |
| `GET /v1/admin/users/{id}` | 200 | `User` |
| `GET /v1/admin/users/{id}` | 404 | `Error` |
| `PATCH /v1/admin/users/{id}` | 200 | `User` |
| `PATCH /v1/admin/users/{id}` | 400 | `Error` |
| `PATCH /v1/admin/users/{id}` | 404 | `Error` |
| `PATCH /v1/admin/users/{id}` | 409 | `Error` |
| `PATCH /v1/admin/users/{id}` | 500 | `Error` |
| `DELETE /v1/admin/users/{id}` | 200 | `Status` |
| `DELETE /v1/admin/users/{id}` | 404 | `Error` |
| `DELETE /v1/admin/users/{id}` | 500 | `Error` |
| `POST /v1/admin/users/{id}/lock` | 200 | an object with `id`, `locked`, `origin` and `reason` |
| `POST /v1/admin/users/{id}/lock` | 400 | `Error` |
| `POST /v1/admin/users/{id}/lock` | 404 | `Error` |
| `POST /v1/admin/users/{id}/lock` | 500 | `Error` |
| `POST /v1/admin/users/{id}/unlock` | 200 | an object with `id` and `locked` |
| `POST /v1/admin/users/{id}/unlock` | 404 | `Error` |
| `GET /v1/admin/users/{id}/devices` | 200 | a list of `Device` |
| `GET /v1/admin/users/{id}/devices` | 404 | `Error` |
| `DELETE /v1/admin/users/{id}/devices/{deviceId}` | 200 | `Status` |
| `DELETE /v1/admin/users/{id}/devices/{deviceId}` | 404 | `Error` |
| `DELETE /v1/admin/users/{id}/devices/{deviceId}` | 500 | `Error` |
| `GET /v1/admin/revocations` | 200 | a list of object |
| `GET /v1/admin/users/{id}/nhi-key` | 200 | an object with `user_id`, `registered`, `created` and `fingerprint` |
| `GET /v1/admin/users/{id}/nhi-key` | 404 | `Error` |
| `PUT /v1/admin/users/{id}/nhi-key` | 200 | `Status` |
| `PUT /v1/admin/users/{id}/nhi-key` | 400 | `Error` |
| `PUT /v1/admin/users/{id}/nhi-key` | 404 | `Error` |
| `PUT /v1/admin/users/{id}/nhi-key` | 500 | `Error` |
| `DELETE /v1/admin/users/{id}/nhi-key` | 200 | `Status` |
| `DELETE /v1/admin/users/{id}/nhi-key` | 404 | `Error` |
| `DELETE /v1/admin/users/{id}/nhi-key` | 500 | `Error` |

## Roles, assignments and knowledge packs

Roles with the roles they compose, the assignments that give a person a role and the knowledge packs attached to them.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/roles` | List roles | `adminBearer` |
| POST | `/v1/admin/roles` | Create a role, global or owned by one server | `adminBearer` |
| GET | `/v1/admin/roles/{id}/export` | Export the role as a canonical version-control document in application/yaml, name-keyed, id-free and byte-stable across exports | `adminBearer` |
| PATCH | `/v1/admin/roles/{id}` | Update a role's description, since the name and the kind are fixed at create | `adminBearer` |
| DELETE | `/v1/admin/roles/{id}` | Delete a role and cascade its assignments and access rows, 409 when a policy set, the product or a server still names it | `adminBearer` |
| GET | `/v1/admin/roles/{id}/implications` | List the roles this role composes, where each edge id is the composed role's id, the value the DELETE path takes | `adminBearer` |
| POST | `/v1/admin/roles/{id}/implications` | Add a composition edge (rejected if it would create a cycle) | `adminBearer` |
| DELETE | `/v1/admin/roles/{id}/implications/{implicationId}` | Remove a composition edge, named by the composed role's id, effective at the subjects' next check-in | `adminBearer` |
| GET | `/v1/admin/assignments` | List role assignments (optionally filtered by subject) | `adminBearer` |
| POST | `/v1/admin/assignments` | Assign a role to a user (optionally time-boxed; group subjects retired with the unified role model) | `adminBearer` |
| DELETE | `/v1/admin/assignments/{id}` | Remove an assignment | `adminBearer` |
| GET | `/v1/admin/packs` | List knowledge packs | `adminBearer` |
| POST | `/v1/admin/packs` | Create a knowledge pack (checksum computed server-side) | `adminBearer` |
| DELETE | `/v1/admin/packs/{id}` | Delete a knowledge pack that no role is bound to | `adminBearer` |
| POST | `/v1/admin/packs/{id}/bindings` | Bind a knowledge pack to a role | `adminBearer` |
| DELETE | `/v1/admin/packs/{id}/bindings/{bindingId}` | Unbind a knowledge pack from a role, named by the role id, exactly as the packs list serves each binding's id | `adminBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/admin/roles` | `name` | string | yes |  |
| `POST /v1/admin/roles` | `description` | string |  |  |
| `POST /v1/admin/roles` | `kind` | string |  | One of `business`, `application`, `approver` or `straza`. |
| `POST /v1/admin/roles` | `server` | string |  | The name of the server that owns the role. |
| `POST /v1/admin/roles` | `tools` | list of string |  | The tool names a server-owned role reaches on its server, required with server. |
| `POST /v1/admin/roles` | `covers` | `Covers` |  | Which objects of the server's pinned type a server-owned role covers. |
| `PATCH /v1/admin/roles/{id}` | `description` | string |  |  |
| `PATCH /v1/admin/roles/{id}` | `kind` | string |  | One of `business`, `application`, `approver` or `straza`. |
| `POST /v1/admin/roles/{id}/implications` | `implies_role_id` | string | yes |  |
| `POST /v1/admin/assignments` | `id` | string |  |  |
| `POST /v1/admin/assignments` | `subject_kind` | string | yes | One of `user`. |
| `POST /v1/admin/assignments` | `subject_id` | string | yes |  |
| `POST /v1/admin/assignments` | `role_id` | string | yes |  |
| `POST /v1/admin/assignments` | `valid_from` | string |  |  |
| `POST /v1/admin/assignments` | `valid_to` | string |  |  |
| `POST /v1/admin/assignments` | `origin` | string |  | The lane that wrote the row, scim for an identity manager group membership and admin for the admin API. One of `scim` or `admin`. |
| `POST /v1/admin/packs` | `id` | string |  |  |
| `POST /v1/admin/packs` | `name` | string | yes |  |
| `POST /v1/admin/packs` | `version` | string |  |  |
| `POST /v1/admin/packs` | `content` | string |  |  |
| `POST /v1/admin/packs` | `bindings` | list of object |  | Which roles receive this knowledge pack; empty means bound to nothing, so no session ever sees it. |
| `POST /v1/admin/packs/{id}/bindings` | `role_id` | string | yes |  |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/roles` | 200 | a list of `Role` |
| `POST /v1/admin/roles` | 201 | `Role` |
| `POST /v1/admin/roles` | 400 | `Error` |
| `POST /v1/admin/roles` | 403 | `Error` |
| `POST /v1/admin/roles` | 404 | `Error` |
| `POST /v1/admin/roles` | 409 | `DirectConflict` |
| `POST /v1/admin/roles` | 503 | `DirectBusy` |
| `GET /v1/admin/roles/{id}/export` | 200 | a application/yaml body |
| `GET /v1/admin/roles/{id}/export` | 403 | `Error` |
| `GET /v1/admin/roles/{id}/export` | 404 | `Error` |
| `PATCH /v1/admin/roles/{id}` | 200 | `Role` |
| `PATCH /v1/admin/roles/{id}` | 400 | `Error` |
| `PATCH /v1/admin/roles/{id}` | 404 | `Error` |
| `PATCH /v1/admin/roles/{id}` | 409 | `DirectConflict` |
| `PATCH /v1/admin/roles/{id}` | 503 | `DirectBusy` |
| `DELETE /v1/admin/roles/{id}` | 200 | `RoleDeleted` |
| `DELETE /v1/admin/roles/{id}` | 404 | `Error` |
| `DELETE /v1/admin/roles/{id}` | 409 | `DirectConflict` |
| `DELETE /v1/admin/roles/{id}` | 503 | `DirectBusy` |
| `GET /v1/admin/roles/{id}/implications` | 200 | a list of object |
| `GET /v1/admin/roles/{id}/implications` | 404 | `Error` |
| `POST /v1/admin/roles/{id}/implications` | 201 | an empty body |
| `POST /v1/admin/roles/{id}/implications` | 400 | `Error` |
| `POST /v1/admin/roles/{id}/implications` | 409 | `DirectConflict` |
| `POST /v1/admin/roles/{id}/implications` | 503 | `DirectBusy` |
| `DELETE /v1/admin/roles/{id}/implications/{implicationId}` | 200 | `Status` |
| `DELETE /v1/admin/roles/{id}/implications/{implicationId}` | 404 | `Error` |
| `DELETE /v1/admin/roles/{id}/implications/{implicationId}` | 409 | `DirectConflict` |
| `DELETE /v1/admin/roles/{id}/implications/{implicationId}` | 503 | `DirectBusy` |
| `GET /v1/admin/assignments` | 200 | a list of `Assignment` |
| `POST /v1/admin/assignments` | 201 | `Assignment` |
| `POST /v1/admin/assignments` | 409 | `Error` |
| `DELETE /v1/admin/assignments/{id}` | 200 | `Status` |
| `DELETE /v1/admin/assignments/{id}` | 404 | `Error` |
| `GET /v1/admin/packs` | 200 | a list of `Pack` |
| `POST /v1/admin/packs` | 201 | `Pack` |
| `POST /v1/admin/packs` | 409 | `Error` |
| `DELETE /v1/admin/packs/{id}` | 200 | `Status` |
| `DELETE /v1/admin/packs/{id}` | 404 | `Error` |
| `DELETE /v1/admin/packs/{id}` | 409 | an object with `error` |
| `POST /v1/admin/packs/{id}/bindings` | 201 | `PackBinding` |
| `DELETE /v1/admin/packs/{id}/bindings/{bindingId}` | 200 | `Status` |
| `DELETE /v1/admin/packs/{id}/bindings/{bindingId}` | 404 | `Error` |

## PolicySets

Stored PolicySets, with validation, simulation and activation into the signed snapshot.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/default-denials` | List the tools that were denied because no policy rule covers them | `adminBearer` |
| GET | `/v1/admin/policies` | List stored PolicySets (summary-only envelope with filters, paging, and a per-role facet) | `adminBearer` |
| PUT | `/v1/admin/policies` | Upsert a PolicySet from YAML (validated; a new set stays draft, edits to a live set stay unpublished until it is activated) | `adminBearer` |
| GET | `/v1/admin/policies/event-support` | Read the harness support matrix for policy events, the one source of truth for event coverage | `adminBearer` |
| GET | `/v1/admin/policies/{name}` | Fetch one stored PolicySet in full, yaml included (the editor's read, since the list is summary-only) | `adminBearer` |
| DELETE | `/v1/admin/policies/{name}` | Delete a stored PolicySet (drafts only; active sets must be deactivated first) | `adminBearer` |
| POST | `/v1/admin/policies/validate` | Validate PolicySet YAML with the real parser (Policy Builder; no state change) | `adminBearer` |
| POST | `/v1/admin/policies/simulate` | Evaluate one event+subject against the active snapshot, optionally overlaying a draft PolicySet (Policy Builder what-if; no state change) | `adminBearer` |
| POST | `/v1/admin/policies/{name}/activate` | Turn one PolicySet on or off and publish that change alone in a new snapshot | `adminBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `PUT /v1/admin/policies` | `the document` | application/yaml | yes | The PolicySet document to store, as YAML text. |
| `POST /v1/admin/policies/validate` | `the document` | application/yaml | yes | The PolicySet document to check, as YAML text; nothing is stored. |
| `POST /v1/admin/policies/simulate` | `event` | object | yes | canonical policy event (kind, tool, command, paths, app, toolName, workspace, args). |
| `POST /v1/admin/policies/simulate` | `subject` | object |  |  |
| `POST /v1/admin/policies/simulate` | `draft` | string |  | PolicySet YAML overlaid in place of its same-named stored set |
| `POST /v1/admin/policies/{name}/activate` | `status` | string |  | One of `active` or `draft`. |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/default-denials` | 200 | an object with `since`, `truncated`, `servers` and `tools` |
| `GET /v1/admin/policies` | 200 | an object with `items`, `total`, `limit`, `offset` and `roles` |
| `GET /v1/admin/policies` | 400 | `Error` |
| `PUT /v1/admin/policies` | 200 | `PolicySet` |
| `PUT /v1/admin/policies` | 201 | `PolicySet` |
| `PUT /v1/admin/policies` | 400 | `Error` |
| `PUT /v1/admin/policies` | 409 | `DirectConflict` |
| `PUT /v1/admin/policies` | 503 | `DirectBusy` |
| `GET /v1/admin/policies/event-support` | 200 | an object with `events` and `harnesses` |
| `GET /v1/admin/policies/{name}` | 200 | `PolicySet` |
| `GET /v1/admin/policies/{name}` | 404 | `Error` |
| `DELETE /v1/admin/policies/{name}` | 204 | an empty body |
| `DELETE /v1/admin/policies/{name}` | 404 | `Error` |
| `DELETE /v1/admin/policies/{name}` | 409 | `DirectConflict` |
| `DELETE /v1/admin/policies/{name}` | 503 | `DirectBusy` |
| `POST /v1/admin/policies/validate` | 200 | an object with `ok`, `name`, `rules`, `priority`, `matchRoles`, `capture`, `warnings` and `advisories` |
| `POST /v1/admin/policies/validate` | 400 | `Error` |
| `POST /v1/admin/policies/simulate` | 200 | an object with `active`, `draft`, `object`, `subject` and `snapshot` |
| `POST /v1/admin/policies/simulate` | 400 | `Error` |
| `POST /v1/admin/policies/simulate` | 404 | `Error` |
| `POST /v1/admin/policies/{name}/activate` | 200 | an object with `status`, `snapshot` and `changed` |
| `POST /v1/admin/policies/{name}/activate` | 400 | `Error` |
| `POST /v1/admin/policies/{name}/activate` | 404 | `Error` |
| `POST /v1/admin/policies/{name}/activate` | 409 | `DirectConflict` |
| `POST /v1/admin/policies/{name}/activate` | 503 | `DirectBusy` |

## Drafts

Drafts of changes to MCP servers, roles, access rows and policy sets, stored, checked against live state and published whole by a person.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/drafts` | List drafts, the open ones by default, newest first, with the check counts of each open draft | `adminBearer` |
| POST | `/v1/admin/drafts` | Store a new draft of documents or items checked against live state, or add them to your working draft | `adminBearer` |
| POST | `/v1/admin/drafts/check` | Check documents or items against live state and answer the verdict, storing nothing | `adminBearer` |
| GET | `/v1/admin/drafts/{id}` | Read one draft with its verdict, its revisions, the live objects it changes and its change record | `adminBearer` |
| PUT | `/v1/admin/drafts/{id}` | Replace an open draft's documents with a new revision and check it again | `adminBearer` |
| POST | `/v1/admin/drafts/{id}/discard` | Discard an open draft, which changes nothing live | `adminBearer` |
| POST | `/v1/admin/drafts/{id}/revert` | Make a new draft that undoes a published draft, checked like any other | `adminBearer` |
| POST | `/v1/admin/drafts/{id}/rebase` | Check a draft again on live state, keeping the fields it changes and taking every other field from live | `adminBearer` |
| POST | `/v1/admin/drafts/{id}/contact` | Contact a proposed remote server once, with no credential, and read its tool names | `userBearer` |
| POST | `/v1/admin/drafts/{id}/publish` | Publish a draft whole in one transaction, as a person with standing over every item who confirmed its risks | `userBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/admin/drafts` | `documents` | list of string |  | YAML streams of App, Role, PolicySet and Removal documents. |
| `POST /v1/admin/drafts` | `items` | list of `DraftBodyItem` |  |  |
| `POST /v1/admin/drafts` | `note` | string |  | At most 2,000 bytes, without invisible direction or zero-width characters. |
| `POST /v1/admin/drafts` | `working` | boolean |  | Add to the caller's working draft. |
| `POST /v1/admin/drafts` | `revision` | integer |  | Accepted and ignored. |
| `POST /v1/admin/drafts/check` | `documents` | list of string |  | YAML streams of App, Role, PolicySet and Removal documents. |
| `POST /v1/admin/drafts/check` | `items` | list of `DraftBodyItem` |  |  |
| `POST /v1/admin/drafts/check` | `note` | string |  | At most 2,000 bytes, without invisible direction or zero-width characters. |
| `POST /v1/admin/drafts/check` | `working` | boolean |  | Add to the caller's working draft. |
| `POST /v1/admin/drafts/check` | `revision` | integer |  | Accepted and ignored. |
| `PUT /v1/admin/drafts/{id}` | `revision` | integer | yes |  |
| `PUT /v1/admin/drafts/{id}` | `documents` | list of string |  |  |
| `PUT /v1/admin/drafts/{id}` | `items` | list of `DraftBodyItem` |  |  |
| `PUT /v1/admin/drafts/{id}` | `note` | string |  |  |
| `PUT /v1/admin/drafts/{id}` | `working` | boolean |  | Accepted and ignored. |
| `POST /v1/admin/drafts/{id}/discard` | `revision` | integer |  |  |
| `POST /v1/admin/drafts/{id}/discard` | `reason` | string |  | At most 500 bytes of plain text. |
| `POST /v1/admin/drafts/{id}/revert` | `note` | string |  |  |
| `POST /v1/admin/drafts/{id}/rebase` | `revision` | integer | yes |  |
| `POST /v1/admin/drafts/{id}/rebase` | `picks` | object |  | Keyed by Kind/Name, a space and the field. |
| `POST /v1/admin/drafts/{id}/contact` | `object` | string | yes | The App item of the draft to contact, as Kind/Name, such as App/github. |
| `POST /v1/admin/drafts/{id}/publish` | `revision` | integer | yes |  |
| `POST /v1/admin/drafts/{id}/publish` | `risk_digest` | string | yes | The verdict's risk_digest as the publisher read it, 64 hex characters, or empty. |
| `POST /v1/admin/drafts/{id}/publish` | `ticked` | list of string |  | The key of every risk confirmed, tick and typed, as each finding carries it. |
| `POST /v1/admin/drafts/{id}/publish` | `typed` | object |  | The text typed for each typed risk, by key. |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/drafts` | 200 | `DraftPage` |
| `GET /v1/admin/drafts` | 400 | `Error` |
| `GET /v1/admin/drafts` | 403 | `Error` |
| `GET /v1/admin/drafts` | 500 | `Error` |
| `GET /v1/admin/drafts` | 503 | `DraftsUnavailable` |
| `POST /v1/admin/drafts` | 200 | `DraftAnswer` |
| `POST /v1/admin/drafts` | 201 | `DraftAnswer` |
| `POST /v1/admin/drafts` | 400 | `Error` |
| `POST /v1/admin/drafts` | 403 | `Error` |
| `POST /v1/admin/drafts` | 409 | `Error` |
| `POST /v1/admin/drafts` | 413 | `DraftTooLarge` |
| `POST /v1/admin/drafts` | 422 | `DraftRefused` |
| `POST /v1/admin/drafts` | 503 | `DraftsUnavailable` |
| `POST /v1/admin/drafts/check` | 200 | `DraftCheckAnswer` |
| `POST /v1/admin/drafts/check` | 400 | `Error` |
| `POST /v1/admin/drafts/check` | 403 | `Error` |
| `POST /v1/admin/drafts/check` | 413 | `DraftTooLarge` |
| `POST /v1/admin/drafts/check` | 503 | `DraftsUnavailable` |
| `GET /v1/admin/drafts/{id}` | 200 | `DraftDetail` |
| `GET /v1/admin/drafts/{id}` | 403 | `Error` |
| `GET /v1/admin/drafts/{id}` | 404 | `Error` |
| `GET /v1/admin/drafts/{id}` | 503 | `DraftsUnavailable` |
| `PUT /v1/admin/drafts/{id}` | 200 | `DraftAnswer` |
| `PUT /v1/admin/drafts/{id}` | 400 | `Error` |
| `PUT /v1/admin/drafts/{id}` | 403 | `Error` |
| `PUT /v1/admin/drafts/{id}` | 404 | `Error` |
| `PUT /v1/admin/drafts/{id}` | 409 | `Error` |
| `PUT /v1/admin/drafts/{id}` | 413 | `DraftTooLarge` |
| `PUT /v1/admin/drafts/{id}` | 422 | `DraftRefused` |
| `PUT /v1/admin/drafts/{id}` | 503 | `DraftsUnavailable` |
| `POST /v1/admin/drafts/{id}/discard` | 200 | an object with `draft` |
| `POST /v1/admin/drafts/{id}/discard` | 400 | `Error` |
| `POST /v1/admin/drafts/{id}/discard` | 403 | `Error` |
| `POST /v1/admin/drafts/{id}/discard` | 404 | `Error` |
| `POST /v1/admin/drafts/{id}/discard` | 409 | `Error` |
| `POST /v1/admin/drafts/{id}/discard` | 413 | `DraftTooLarge` |
| `POST /v1/admin/drafts/{id}/discard` | 503 | `DraftsUnavailable` |
| `POST /v1/admin/drafts/{id}/revert` | 201 | `DraftAnswer` |
| `POST /v1/admin/drafts/{id}/revert` | 400 | `Error` |
| `POST /v1/admin/drafts/{id}/revert` | 403 | `Error` |
| `POST /v1/admin/drafts/{id}/revert` | 404 | `Error` |
| `POST /v1/admin/drafts/{id}/revert` | 409 | `Error` |
| `POST /v1/admin/drafts/{id}/revert` | 413 | `DraftTooLarge` |
| `POST /v1/admin/drafts/{id}/revert` | 422 | `DraftRefused` |
| `POST /v1/admin/drafts/{id}/revert` | 503 | `DraftsUnavailable` |
| `POST /v1/admin/drafts/{id}/rebase` | 200 | `DraftAnswer` |
| `POST /v1/admin/drafts/{id}/rebase` | 400 | `Error` |
| `POST /v1/admin/drafts/{id}/rebase` | 403 | `Error` |
| `POST /v1/admin/drafts/{id}/rebase` | 404 | `Error` |
| `POST /v1/admin/drafts/{id}/rebase` | 409 | `DraftConflicts` |
| `POST /v1/admin/drafts/{id}/rebase` | 413 | `DraftTooLarge` |
| `POST /v1/admin/drafts/{id}/rebase` | 422 | `DraftRefused` |
| `POST /v1/admin/drafts/{id}/rebase` | 500 | `Error` |
| `POST /v1/admin/drafts/{id}/rebase` | 503 | `DraftsUnavailable` |
| `POST /v1/admin/drafts/{id}/contact` | 200 | `DraftContacted` |
| `POST /v1/admin/drafts/{id}/contact` | 400 | `Error` |
| `POST /v1/admin/drafts/{id}/contact` | 403 | `Error` |
| `POST /v1/admin/drafts/{id}/contact` | 404 | `Error` |
| `POST /v1/admin/drafts/{id}/contact` | 409 | `Error` |
| `POST /v1/admin/drafts/{id}/contact` | 413 | `DraftTooLarge` |
| `POST /v1/admin/drafts/{id}/contact` | 502 | `Error` |
| `POST /v1/admin/drafts/{id}/contact` | 500 | `Error` |
| `POST /v1/admin/drafts/{id}/contact` | 503 | `DraftsUnavailable` |
| `POST /v1/admin/drafts/{id}/publish` | 200 | `DraftPublished` |
| `POST /v1/admin/drafts/{id}/publish` | 400 | `Error` |
| `POST /v1/admin/drafts/{id}/publish` | 403 | `Error` |
| `POST /v1/admin/drafts/{id}/publish` | 404 | `Error` |
| `POST /v1/admin/drafts/{id}/publish` | 409 | `DraftRefused` |
| `POST /v1/admin/drafts/{id}/publish` | 413 | `DraftTooLarge` |
| `POST /v1/admin/drafts/{id}/publish` | 500 | `Error` |
| `POST /v1/admin/drafts/{id}/publish` | 503 | `DraftsUnavailable` |

## Apps, tools and bindings

MCP servers, the tools they expose, the access rows that give roles access to them, their static secrets and the OAuth providers they use.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/apps` | List MCP servers with live manager status | `adminBearer` |
| POST | `/v1/admin/apps` | Install or update an MCP server from a raw app.yaml manifest | `adminBearer` |
| POST | `/v1/admin/apps/import` | Convert an MCP registry server.json into an app.yaml manifest without installing it | `adminBearer` |
| DELETE | `/v1/admin/apps/{id}` | Stop and remove an MCP server by id or name | `adminBearer` |
| POST | `/v1/admin/apps/{id}/bindings` | Give a role access to an MCP server's tools (no access row means the tools are invisible; access admits, policy decides) | `adminBearer` |
| GET | `/v1/admin/tools` | Flat list of every exposed MCP tool across running servers, with upstream descriptions, for access certification | `adminBearer` |
| GET | `/v1/admin/catalog/preview` | Preview what a subject would see in the gateway catalog, per tool, with a status and reason (visible/approve_gated/hidden_policy/no_binding/matcher_miss/not_running) | `adminBearer` |
| GET | `/v1/admin/bindings` | List access rows, each giving one role tools on one MCP server | `adminBearer` |
| DELETE | `/v1/admin/bindings/{id}` | Delete an access row, so the role loses its access to that MCP server | `adminBearer` |
| GET | `/v1/admin/apps/{id}/secrets` | List an MCP server's static secrets with fingerprints, the server's own row first | `adminBearer` |
| POST | `/v1/admin/apps/{id}/secrets` | Store a static secret for an MCP server, the server's own secret or one role's override (value never echoed; stored encrypted) | `adminBearer` |
| DELETE | `/v1/admin/apps/{id}/secrets` | Remove the server's own secret | `adminBearer` |
| DELETE | `/v1/admin/apps/{id}/secrets/{role}` | Remove one role's secret override | `adminBearer` |
| GET | `/v1/admin/apps/{id}/objects` | Read a server's object list, the last good listing with the roles that cover each entry, one page at a time | `adminBearer` |
| POST | `/v1/admin/apps/{id}/objects/refresh` | Ask for a listing of a server's objects now instead of at the next 10-minute listing | `adminBearer` |
| POST | `/v1/admin/apps/{id}/objects/credential` | Store the listing credential Straza lists a server's objects with (value never echoed; stored encrypted) | `adminBearer` |
| DELETE | `/v1/admin/apps/{id}/objects/credential` | Remove the listing credential of a server | `adminBearer` |
| POST | `/v1/admin/apps/{id}/objects/draft` | Open a draft that pins the objects a server declares in its tool marks | `adminBearer` |
| GET | `/v1/admin/oauth/providers` | List the oauth providers this server is configured with, never their client secrets | `adminBearer` |
| GET | `/v1/admin/access/grant-only` | Access rows whose tools run on the access row alone, with no policy rule naming them | `adminBearer` |
| POST | `/v1/admin/apps/{id}/health` | Trigger an immediate health probe for an MCP server (by id or name) and return the refreshed state | `adminBearer` |
| POST | `/v1/admin/apps/{id}/enable` | Resume an admin-paused or stopped MCP server from its persisted manifest (by id or name) | `adminBearer` |
| POST | `/v1/admin/apps/{id}/disable` | Admin-pause an MCP server, stopping it and keeping it stopped across GitOps ticks and restarts (by id or name) | `adminBearer` |
| GET | `/v1/admin/apps/{id}/logs` | Fetch recent runtime log lines for an MCP server (by id or name) | `adminBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/admin/apps` | `the document` | application/yaml | yes | The MCP server manifest to install or update, as YAML text in the app.yaml shape. |
| `POST /v1/admin/apps/{id}/bindings` | `role` | string | yes |  |
| `POST /v1/admin/apps/{id}/bindings` | `tools` | list of string |  |  |
| `POST /v1/admin/apps/{id}/bindings` | `covers` | `Covers` |  | Which objects of the server's pinned type the role covers. |
| `POST /v1/admin/apps/{id}/secrets` | `role` | string |  | Optional; absent stores the server's own secret. |
| `POST /v1/admin/apps/{id}/secrets` | `value` | string | yes |  |
| `POST /v1/admin/apps/{id}/objects/credential` | `value` | string | yes |  |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/apps` | 200 | a list of `App` |
| `POST /v1/admin/apps` | 200 | an object with `name`, `runtime`, `credential` and `tools` |
| `POST /v1/admin/apps` | 201 | `App` |
| `POST /v1/admin/apps` | 409 | an object with `error` |
| `POST /v1/admin/apps` | 422 | `Error` |
| `POST /v1/admin/apps` | 503 | `DirectBusy` |
| `POST /v1/admin/apps/import` | 200 | an object with `manifest`, `name` and `runtime` |
| `POST /v1/admin/apps/import` | 422 | `Error` |
| `DELETE /v1/admin/apps/{id}` | 200 | an object with `id` and `status` |
| `DELETE /v1/admin/apps/{id}` | 404 | `Error` |
| `DELETE /v1/admin/apps/{id}` | 409 | an object with `error` |
| `DELETE /v1/admin/apps/{id}` | 503 | `DirectBusy` |
| `POST /v1/admin/apps/{id}/bindings` | 201 | `ToolBinding` |
| `POST /v1/admin/apps/{id}/bindings` | 400 | `Error` |
| `POST /v1/admin/apps/{id}/bindings` | 404 | `Error` |
| `POST /v1/admin/apps/{id}/bindings` | 409 | `DirectConflict` |
| `POST /v1/admin/apps/{id}/bindings` | 503 | `DirectBusy` |
| `GET /v1/admin/tools` | 200 | a list of `Tool` |
| `GET /v1/admin/catalog/preview` | 200 | an object with `subject`, `notes` and `entries` |
| `GET /v1/admin/catalog/preview` | 400 | `Error` |
| `GET /v1/admin/catalog/preview` | 404 | `Error` |
| `GET /v1/admin/bindings` | 200 | a list of `ToolBinding` |
| `DELETE /v1/admin/bindings/{id}` | 200 | an empty body |
| `DELETE /v1/admin/bindings/{id}` | 400 | `Error` |
| `DELETE /v1/admin/bindings/{id}` | 404 | `Error` |
| `DELETE /v1/admin/bindings/{id}` | 409 | `DirectConflict` |
| `DELETE /v1/admin/bindings/{id}` | 503 | `DirectBusy` |
| `GET /v1/admin/apps/{id}/secrets` | 200 | a list of `AppSecret` |
| `GET /v1/admin/apps/{id}/secrets` | 404 | `Error` |
| `POST /v1/admin/apps/{id}/secrets` | 201 | `AppSecret` |
| `POST /v1/admin/apps/{id}/secrets` | 400 | `Error` |
| `POST /v1/admin/apps/{id}/secrets` | 404 | `Error` |
| `DELETE /v1/admin/apps/{id}/secrets` | 200 | an object with `id` and `status` |
| `DELETE /v1/admin/apps/{id}/secrets` | 404 | `Error` |
| `DELETE /v1/admin/apps/{id}/secrets/{role}` | 200 | an object with `id` and `status` |
| `DELETE /v1/admin/apps/{id}/secrets/{role}` | 404 | `Error` |
| `GET /v1/admin/apps/{id}/objects` | 200 | `ObjectList` |
| `GET /v1/admin/apps/{id}/objects` | 404 | `Error` |
| `POST /v1/admin/apps/{id}/objects/refresh` | 202 | an object with `app` and `dueAt` |
| `POST /v1/admin/apps/{id}/objects/refresh` | 404 | `Error` |
| `POST /v1/admin/apps/{id}/objects/refresh` | 409 | `Error` |
| `POST /v1/admin/apps/{id}/objects/refresh` | 429 | `Error` |
| `POST /v1/admin/apps/{id}/objects/credential` | 201 | `ListingCredential` |
| `POST /v1/admin/apps/{id}/objects/credential` | 400 | `Error` |
| `POST /v1/admin/apps/{id}/objects/credential` | 404 | `Error` |
| `POST /v1/admin/apps/{id}/objects/credential` | 409 | `Error` |
| `DELETE /v1/admin/apps/{id}/objects/credential` | 204 | an empty body |
| `DELETE /v1/admin/apps/{id}/objects/credential` | 404 | `Error` |
| `POST /v1/admin/apps/{id}/objects/draft` | 200 | an object with `unchanged` and `sentence` |
| `POST /v1/admin/apps/{id}/objects/draft` | 201 | `DraftAnswer` |
| `POST /v1/admin/apps/{id}/objects/draft` | 403 | `Error` |
| `POST /v1/admin/apps/{id}/objects/draft` | 404 | `Error` |
| `POST /v1/admin/apps/{id}/objects/draft` | 409 | `Error` |
| `GET /v1/admin/oauth/providers` | 200 | a list of object |
| `GET /v1/admin/access/grant-only` | 200 | an object with `rows` |
| `POST /v1/admin/apps/{id}/health` | 200 | `App` |
| `POST /v1/admin/apps/{id}/health` | 409 | an object with `error` |
| `POST /v1/admin/apps/{id}/enable` | 200 | `App` |
| `POST /v1/admin/apps/{id}/enable` | 404 | `Error` |
| `POST /v1/admin/apps/{id}/enable` | 500 | `Error` |
| `POST /v1/admin/apps/{id}/disable` | 200 | `App` |
| `POST /v1/admin/apps/{id}/disable` | 404 | `Error` |
| `GET /v1/admin/apps/{id}/logs` | 200 | an object with `app`, `lines` and `entries` |
| `GET /v1/admin/apps/{id}/logs` | 409 | an object with `error` |

## Sessions and transcripts

Agent sessions, the kill switch and the recorded conversations.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/sessions` | List sessions, newest first or sorted by last seen, user, status or attestation, optionally filtered by status or user | `adminBearer` |
| POST | `/v1/admin/sessions/{id}/revoke` | Revoke one session (the kill switch) | `adminBearer` |
| POST | `/v1/admin/sessions/revoke` | Revoke a named set of sessions (at most 1000) or every active session of one user, and count what was revoked | `adminBearer` |
| POST | `/v1/admin/signing-keys/rotate` | Stage a new session signing key | `adminBearer` |
| GET | `/v1/admin/signing-keys` | Every signing key with its purpose and status | `adminBearer` |
| POST | `/v1/admin/signing-keys/client-assertion/rotate` | Stage a new client assertion key, or create the first one | `adminBearer` |
| POST | `/v1/admin/signing-keys/client-assertion/{kid}/retire` | Retire one client assertion key at once | `adminBearer` |
| POST | `/v1/admin/signing-keys/client-assertion/{kid}/promote` | Make a staged client assertion key the signing key | `adminBearer` |
| GET | `/v1/admin/signing-keys/client-assertion/{kid}/certificate` | The certificate of one client assertion key | `adminBearer` |
| GET | `/v1/admin/sessions/{id}/transcript` | One session's recorded conversation, in order (recording is policy-opted-in; empty when the session was never recorded) | `adminBearer` |
| GET | `/v1/admin/transcripts` | List recorded conversations, one row per session, newest activity first, with turn count and a preview of the latest turn | `adminBearer` |
| GET | `/v1/admin/transcripts/search` | Search recorded turns by substring or by exact content hash, or list the newest recorded turns when neither is given | `adminBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/admin/sessions/revoke` | `sessions` | list of string |  |  |
| `POST /v1/admin/sessions/revoke` | `user` | string |  | user id or username; expands server-side to their active sessions |
| `POST /v1/admin/sessions/revoke` | `reason` | string |  |  |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/sessions` | 200 | a list of `Session` |
| `GET /v1/admin/sessions` | 400 | `Error` |
| `POST /v1/admin/sessions/{id}/revoke` | 200 | `Status` |
| `POST /v1/admin/sessions/{id}/revoke` | 404 | `Error` |
| `POST /v1/admin/sessions/{id}/revoke` | 500 | `Error` |
| `POST /v1/admin/sessions/revoke` | 200 | an object with `revoked` |
| `POST /v1/admin/sessions/revoke` | 400 | `Error` |
| `POST /v1/admin/sessions/revoke` | 500 | `Error` |
| `POST /v1/admin/signing-keys/rotate` | 200 | an object with `kid`, `status`, `active_in_seconds` and `previous_key_verifies_for_seconds` |
| `GET /v1/admin/signing-keys` | 200 | a list of object |
| `POST /v1/admin/signing-keys/client-assertion/rotate` | 200 | an object with `kid`, `status`, `previous_kid`, `active_in_seconds`, `previous_key_verifies_for_seconds` and `jwks_uri` |
| `POST /v1/admin/signing-keys/client-assertion/rotate` | 403 | `Error` |
| `POST /v1/admin/signing-keys/client-assertion/{kid}/retire` | 200 | an object with `kid`, `status`, `was`, `leaves_document_in_seconds` and `next_key_active_in_seconds` |
| `POST /v1/admin/signing-keys/client-assertion/{kid}/retire` | 403 | `Error` |
| `POST /v1/admin/signing-keys/client-assertion/{kid}/retire` | 404 | `Error` |
| `POST /v1/admin/signing-keys/client-assertion/{kid}/retire` | 409 | `Error` |
| `POST /v1/admin/signing-keys/client-assertion/{kid}/promote` | 200 | an object with `kid`, `status`, `was`, `every_replica_signs_in_seconds`, `previous_kid` and `previous_key_leaves_document_in_seconds` |
| `POST /v1/admin/signing-keys/client-assertion/{kid}/promote` | 403 | `Error` |
| `POST /v1/admin/signing-keys/client-assertion/{kid}/promote` | 404 | `Error` |
| `POST /v1/admin/signing-keys/client-assertion/{kid}/promote` | 409 | `Error` |
| `GET /v1/admin/signing-keys/client-assertion/{kid}/certificate` | 200 | a application/x-pem-file body |
| `GET /v1/admin/signing-keys/client-assertion/{kid}/certificate` | 403 | `Error` |
| `GET /v1/admin/signing-keys/client-assertion/{kid}/certificate` | 404 | `Error` |
| `GET /v1/admin/signing-keys/client-assertion/{kid}/certificate` | 409 | `Error` |
| `GET /v1/admin/signing-keys/client-assertion/{kid}/certificate` | 503 | `Error` |
| `GET /v1/admin/sessions/{id}/transcript` | 200 | an object with `session_id`, `username` and `turns` |
| `GET /v1/admin/transcripts` | 200 | a list of object |
| `GET /v1/admin/transcripts/search` | 200 | a list of `ConversationTurn` |
| `GET /v1/admin/transcripts/search` | 400 | `Error` |

## Approvals

Approval records, the decide routes, the notification channels and the enrollment of approver devices.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/approvals` | List approval records (mode:approve workflow) | `adminBearer` |
| GET | `/v1/admin/approvals/{id}` | Read one approval record | `adminBearer` |
| POST | `/v1/admin/approvals/{id}/approve` | Approve a pending request as a person who may decide it | `userBearer` |
| POST | `/v1/admin/approvals/{id}/deny` | Deny a pending request as a person who may decide it | `userBearer` |
| GET | `/v1/admin/approvals/channels` | Notification channel status, covering configuration, enrolled devices vs push routes, last delivery attempt | `adminBearer` |
| POST | `/v1/admin/approvals/channels/{name}/test` | Fire a synchronous test notification through one channel's real delivery path | `adminBearer` |
| POST | `/v1/approval/callbacks/slack` | Slack interactive (block_actions) approval callback, verified by X-Slack-Signature, not a bearer token | none |
| POST | `/v1/admin/approvers/enroll-token` | Refuse every caller, because an approver phone or browser enrolls only on the self route | `adminBearer` |
| GET | `/v1/admin/approvers` | List enrolled approver devices, the id source for the revoke route | `adminBearer` |
| DELETE | `/v1/admin/approvers/{id}` | Revoke (delete) an enrolled approver device, so its use=approver token then fails immediately (row-backed) | `adminBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/admin/approvals/{id}/approve` | `reason` | string |  | The decider's own words on either verdict, at most 500 bytes of plain text. |
| `POST /v1/admin/approvals/{id}/deny` | `reason` | string |  | The decider's own words on either verdict, at most 500 bytes of plain text. |
| `POST /v1/approval/callbacks/slack` | `form fields` | application/x-www-form-urlencoded | yes | A form with one field, payload, carrying the Slack block_actions interaction JSON that Slack signed. |
| `POST /v1/admin/approvers/enroll-token` | `user_id` | string |  |  |
| `POST /v1/admin/approvers/enroll-token` | `username` | string |  |  |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/approvals` | 200 | an object with `approvals` |
| `GET /v1/admin/approvals` | 400 | `Error` |
| `GET /v1/admin/approvals/{id}` | 200 | an object with `approval` |
| `GET /v1/admin/approvals/{id}` | 404 | `Error` |
| `POST /v1/admin/approvals/{id}/approve` | 200 | an object with `approval` |
| `POST /v1/admin/approvals/{id}/approve` | 401 | `Error` |
| `POST /v1/admin/approvals/{id}/approve` | 403 | `Error` |
| `POST /v1/admin/approvals/{id}/approve` | 404 | `Error` |
| `POST /v1/admin/approvals/{id}/approve` | 409 | an object with `error` |
| `POST /v1/admin/approvals/{id}/approve` | 410 | `Error` |
| `POST /v1/admin/approvals/{id}/deny` | 200 | an object with `approval` |
| `POST /v1/admin/approvals/{id}/deny` | 401 | `Error` |
| `POST /v1/admin/approvals/{id}/deny` | 403 | `Error` |
| `POST /v1/admin/approvals/{id}/deny` | 404 | `Error` |
| `POST /v1/admin/approvals/{id}/deny` | 409 | an object with `error` |
| `POST /v1/admin/approvals/{id}/deny` | 410 | `Error` |
| `GET /v1/admin/approvals/channels` | 200 | an object with `channels` |
| `POST /v1/admin/approvals/channels/{name}/test` | 200 | an object with `channel` and `targets` |
| `POST /v1/admin/approvals/channels/{name}/test` | 400 | `Error` |
| `POST /v1/admin/approvals/channels/{name}/test` | 404 | `Error` |
| `POST /v1/approval/callbacks/slack` | 200 | an empty body |
| `POST /v1/approval/callbacks/slack` | 401 | `Error` |
| `POST /v1/admin/approvers/enroll-token` | 401 | `Error` |
| `POST /v1/admin/approvers/enroll-token` | 403 | `Error` |
| `GET /v1/admin/approvers` | 200 | a list of object |
| `DELETE /v1/admin/approvers/{id}` | 200 | `Status` |
| `DELETE /v1/admin/approvers/{id}` | 404 | `Error` |

## The approver surface

Routes for the Straza approver app and the self-service page in a browser: enrollment, token refresh, pending records, decisions and push routes.

| Method | Path | Summary | Security |
|---|---|---|---|
| POST | `/v1/approver/enroll` | Enroll an approver device (no auth; the one-time enroll token is the credential) | none |
| POST | `/v1/approver/refresh/challenge` | Mint a challenge for a device-key-signed token refresh (no bearer; an expired token must not block its own refresh) | none |
| POST | `/v1/approver/refresh` | Exchange a device-key signature over a refresh challenge for a fresh 30-day token (no bearer) | none |
| GET | `/v1/approver/pending` | List pending approvals for this device's bound user | `approverBearer` |
| POST | `/v1/approver/decide` | Submit a hardware-signed, single-use approval decision | `approverBearer` |
| PUT | `/v1/approver/push` | Register (or dedupe) a push route for this approver device | `approverBearer` |
| DELETE | `/v1/approver/push` | Remove a push route for this approver device (idempotent) | `approverBearer` |
| GET | `/v1/approver/history` | Resolved records visible to the bound user (own OR decidable-eligible), newest first, keyset paginated | `approverBearer` |
| DELETE | `/v1/approver/enrollment` | Retire the CALLING device's own enrollment (self-unenroll; row-backed, effect identical to the admin revoke) | `approverBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/approver/enroll` | `enroll_token` | string | yes |  |
| `POST /v1/approver/enroll` | `device` | object | yes |  |
| `POST /v1/approver/refresh/challenge` | `approver_device_id` | string | yes | apd_ prefixed; the device that signs the challenge. |
| `POST /v1/approver/refresh` | `approver_device_id` | string | yes |  |
| `POST /v1/approver/refresh` | `challenge` | string | yes | The challenge from /v1/approver/refresh/challenge. |
| `POST /v1/approver/refresh` | `signature` | string | yes | base64 ECDSA-P256/SHA-256, ASN.1 DER (variable length), over the exact byte string "refresh" + "\n" + approver_device_id + "\n" + challenge. |
| `POST /v1/approver/decide` | `request_id` | string | yes |  |
| `POST /v1/approver/decide` | `verdict` | string | yes | One of `approve` or `deny`. |
| `POST /v1/approver/decide` | `challenge` | string | yes |  |
| `POST /v1/approver/decide` | `signature` | string | yes | base64 ECDSA-P256/SHA-256, ASN.1 DER (variable length). |
| `POST /v1/approver/decide` | `ts` | integer | yes | Client unix seconds; ±5m window. |
| `POST /v1/approver/decide` | `reason` | string |  | The decider's optional own words on either verdict, at most 500 bytes of plain text. |
| `PUT /v1/approver/push` | `kind` | string | yes | One of `fcm`, `apns`, `unifiedpush` or `webpush`. |
| `PUT /v1/approver/push` | `token_or_endpoint` | string | yes |  |
| `PUT /v1/approver/push` | `p256dh` | string |  | OPTIONAL Web Push subscription public key (RFC 8291 §3.2): unpadded base64url of the 65-octet uncompressed P-256 point, exactly PushSubscription.toJSON().keys.p256dh, or UnifiedPush connector 3.x PushEndpoint.pubKeySet. |
| `PUT /v1/approver/push` | `auth` | string |  | OPTIONAL Web Push subscription auth secret (RFC 8291 §3.2): unpadded base64url of exactly 16 octets. |
| `DELETE /v1/approver/push` | `kind` | string | yes | One of `fcm`, `apns`, `unifiedpush` or `webpush`. |
| `DELETE /v1/approver/push` | `token_or_endpoint` | string | yes |  |
| `DELETE /v1/approver/push` | `p256dh` | string |  | OPTIONAL Web Push subscription public key (RFC 8291 §3.2): unpadded base64url of the 65-octet uncompressed P-256 point, exactly PushSubscription.toJSON().keys.p256dh, or UnifiedPush connector 3.x PushEndpoint.pubKeySet. |
| `DELETE /v1/approver/push` | `auth` | string |  | OPTIONAL Web Push subscription auth secret (RFC 8291 §3.2): unpadded base64url of exactly 16 octets. |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `POST /v1/approver/enroll` | 429 | `ApproverThrottled` |
| `POST /v1/approver/enroll` | 201 | `ApproverEnrollResponse` |
| `POST /v1/approver/enroll` | 400 | `Error` |
| `POST /v1/approver/enroll` | 401 | `Error` |
| `POST /v1/approver/refresh/challenge` | 429 | `ApproverThrottled` |
| `POST /v1/approver/refresh/challenge` | 200 | `ApproverRefreshChallengeResponse` |
| `POST /v1/approver/refresh/challenge` | 400 | `Error` |
| `POST /v1/approver/refresh/challenge` | 404 | `Error` |
| `POST /v1/approver/refresh/challenge` | 503 | `ApproverError` |
| `POST /v1/approver/refresh` | 429 | `ApproverThrottled` |
| `POST /v1/approver/refresh` | 200 | `ApproverRefreshResponse` |
| `POST /v1/approver/refresh` | 400 | `Error` |
| `POST /v1/approver/refresh` | 401 | `ApproverError` |
| `POST /v1/approver/refresh` | 503 | `ApproverError` |
| `GET /v1/approver/pending` | 429 | `ApproverThrottled` |
| `GET /v1/approver/pending` | 200 | a list of `ApproverRow` |
| `GET /v1/approver/pending` | 401 | `ApproverError` |
| `GET /v1/approver/pending` | 503 | `ApproverError` |
| `POST /v1/approver/decide` | 429 | `ApproverThrottled` |
| `POST /v1/approver/decide` | 200 | an object with `state` |
| `POST /v1/approver/decide` | 400 | `Error` |
| `POST /v1/approver/decide` | 401 | `ApproverError` |
| `POST /v1/approver/decide` | 503 | `ApproverError` |
| `POST /v1/approver/decide` | 403 | `ApproverError` |
| `POST /v1/approver/decide` | 404 | `Error` |
| `POST /v1/approver/decide` | 409 | an object with `state` |
| `POST /v1/approver/decide` | 410 | `Error` |
| `PUT /v1/approver/push` | 429 | `ApproverThrottled` |
| `PUT /v1/approver/push` | 200 | `Status` |
| `PUT /v1/approver/push` | 400 | `Error` |
| `PUT /v1/approver/push` | 401 | `ApproverError` |
| `PUT /v1/approver/push` | 503 | `ApproverError` |
| `DELETE /v1/approver/push` | 429 | `ApproverThrottled` |
| `DELETE /v1/approver/push` | 200 | `Status` |
| `DELETE /v1/approver/push` | 401 | `ApproverError` |
| `DELETE /v1/approver/push` | 503 | `ApproverError` |
| `GET /v1/approver/history` | 429 | `ApproverThrottled` |
| `GET /v1/approver/history` | 200 | an object with `items` and `next_cursor` |
| `GET /v1/approver/history` | 400 | `ApproverError` |
| `GET /v1/approver/history` | 401 | `ApproverError` |
| `GET /v1/approver/history` | 503 | `ApproverError` |
| `DELETE /v1/approver/enrollment` | 429 | `ApproverThrottled` |
| `DELETE /v1/approver/enrollment` | 204 | an empty body |
| `DELETE /v1/approver/enrollment` | 401 | `ApproverError` |
| `DELETE /v1/approver/enrollment` | 503 | `ApproverError` |

## Audit, sinks and the change feed

The hash-chained audit ledger, sink delivery health and the cursored change feed for identity manager connectors.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/audit` | Fetch hash-chained audit records after a sequence number | `adminBearer` |
| GET | `/v1/admin/changes` | Cursored change feed over the events outbox (IGA liveSync; at-least-once, keep recon as the safety net) | `adminBearer` |
| GET | `/v1/admin/sinks` | List configured sinks with backlog, since-boot tallies and parked (dead-letter) counts | `adminBearer` |
| POST | `/v1/admin/sinks/{name}/replay` | Re-deliver a sink's parked (dead-letter) events, oldest first | `adminBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/admin/sinks/{name}/replay` | `limit` | integer |  | max records to replay in this call (default 1000) |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/audit` | 400 | an empty body |
| `GET /v1/admin/audit` | 200 | a list of object |
| `GET /v1/admin/changes` | 200 | an object with `changes`, `nextCursor`, `more` and `head` |
| `GET /v1/admin/changes` | 400 | `Error` |
| `GET /v1/admin/sinks` | 200 | a list of object |
| `POST /v1/admin/sinks/{name}/replay` | 200 | an object with `sink`, `replayed`, `remaining` and `stopped` |
| `POST /v1/admin/sinks/{name}/replay` | 404 | `Error` |
| `POST /v1/admin/sinks/{name}/replay` | 500 | `Error` |

## Admin API tokens

Long-lived admin API tokens for automation and identity manager connectors.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/api-tokens` | List admin API token metadata, newest first (never the tokens themselves) | `adminBearer` |
| POST | `/v1/admin/api-tokens` | Mint a long-lived admin API token (plaintext returned exactly once; scope is a list of area:verb pairs or full) | `adminBearer` |
| DELETE | `/v1/admin/api-tokens/{id}` | Revoke an admin API token | `adminBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/admin/api-tokens` | `name` | string | yes |  |
| `POST /v1/admin/api-tokens` | `scope` | string | yes | "full" or comma-separated area:verb scopes, e.g. |
| `POST /v1/admin/api-tokens` | `expires_in` | integer |  | Seconds until the token expires. |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/api-tokens` | 200 | a list of object |
| `POST /v1/admin/api-tokens` | 201 | an object with `id`, `name`, `scope` and `token` |
| `DELETE /v1/admin/api-tokens/{id}` | 200 | an object with `id` and `status` |
| `DELETE /v1/admin/api-tokens/{id}` | 404 | `Error` |

## Attestation hashes

The expected-measurement registry for managed installs.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/attestation-hashes` | List the expected-hash registry for managed installs | `adminBearer` |
| POST | `/v1/admin/attestation-hashes` | Register an expected measurement (allowed-set entry) for managed installs | `adminBearer` |
| DELETE | `/v1/admin/attestation-hashes/{id}` | Remove an expected measurement from the registry | `adminBearer` |

Request bodies in this section, one row per field.

| Operation | Field | Type | Required | Meaning |
|---|---|---|---|---|
| `POST /v1/admin/attestation-hashes` | `id` | string |  |  |
| `POST /v1/admin/attestation-hashes` | `artifact` | string | yes | The measurement key: self, config, or hooks followed by a dot and the harness name, such as hooks.claude-code. |
| `POST /v1/admin/attestation-hashes` | `harness` | string |  | Harness this row applies to; empty = all |
| `POST /v1/admin/attestation-hashes` | `platform` | string |  | GOOS/GOARCH this row applies to; empty = all |
| `POST /v1/admin/attestation-hashes` | `hash` | string | yes |  |
| `POST /v1/admin/attestation-hashes` | `note` | string |  |  |
| `POST /v1/admin/attestation-hashes` | `created_at` | string |  |  |
| `POST /v1/admin/attestation-hashes` | `current` | boolean |  | True when this row's hash is the wiring the answering server renders right now for that artifact and harness. |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/attestation-hashes` | 200 | a list of `AttestationHash` |
| `POST /v1/admin/attestation-hashes` | 201 | `AttestationHash` |
| `POST /v1/admin/attestation-hashes` | 400 | `Error` |
| `POST /v1/admin/attestation-hashes` | 409 | `Error` |
| `DELETE /v1/admin/attestation-hashes/{id}` | 200 | an empty body |
| `DELETE /v1/admin/attestation-hashes/{id}` | 404 | `Error` |

## Overview and configuration

Dashboard aggregates for the console and the redacted effective configuration.

| Method | Path | Summary | Security |
|---|---|---|---|
| GET | `/v1/admin/config` | Effective security-layer configuration, redacted (console read-only panel) | `adminBearer` |
| GET | `/v1/admin/overview` | Dashboard aggregates for the admin console (one call) | `adminBearer` |

Answers in this section, by status.

| Operation | Status | Answer |
|---|---|---|
| `GET /v1/admin/config` | 200 | an object with `profile`, `public_url`, `tls`, `store_driver`, `events`, `oidc`, `scim`, `governance`, `approval`, `admin`, `apps` and `capture` |
| `GET /v1/admin/overview` | 400 | `Error` |
| `GET /v1/admin/overview` | 200 | an object with `profile`, `snapshot_id`, `users`, `sessions`, `apps`, `policies`, `audit`, `denylist`, `push` and `decisions` |

## Objects

Every object the tables above name, in the order they first name it, with its fields. A row without a field carries the object's own meaning.

| Object | Field | Type | Meaning |
|---|---|---|---|
| `ReadyStatus` | `status` | string | One of `ok` or `degraded`. Required. |
| `ReadyStatus` | `components` | object | Per-component "ok" or the ping error string (store, bus) Required. |
| `VersionStatus` | | | version.Info flattened (version/commit/go/os/arch) plus profile and the optional approver block. |
| `VersionStatus` | `version` | string | Required. |
| `VersionStatus` | `commit` | string | Required. |
| `VersionStatus` | `go` | string | Required. |
| `VersionStatus` | `os` | string | Required. |
| `VersionStatus` | `arch` | string | Required. |
| `VersionStatus` | `profile` | string | One of `standalone` or `enterprise`. Required. |
| `VersionStatus` | `runtimes` | list of string | The MCP server runtimes this host can run: remote and command always, oci only when docker was found on PATH at boot. |
| `VersionStatus` | `approver` | `ApproverVersion` |  |
| `Error` | | | Error with actionable reason. |
| `Error` | `error` | string | Required. |
| `Error` | `correlation_id` | string | The correlation id of this answer, present on 5xx and recovered-panic answers. |
| `SnapshotKeys` | `keys` | list of object | Required. |
| `IdPDiscovery` | `issuer` | string | Required. |
| `IdPDiscovery` | `client_id` | string | Empty in the standalone profile (strazad is the issuer) Required. |
| `IdPDiscovery` | `nhi_issuer` | string | Where an AI agent or a service account authenticates with its own key, strazad's server.publicUrl on both profiles, whose built-in issuer serves the client_credentials grant. |
| `IdPDiscovery` | `loopback_port` | integer | The fixed port of the browser sign-in's loopback redirect, from oidc.loopbackPort, for an identity provider that matches the redirect's port exactly. |
| `IdPDiscovery` | `min_sign_in` | string | The lowest sign-in lane the server accepts for a person's machine key, from governance.minSignIn. One of `code` or `browser`. |
| `EnrollRequest` | `id_token` | string | The ID token of the person's sign-in at the identity provider. Required. |
| `EnrollRequest` | `client_kind` | string | The kind of client that enrols and holds the credential. One of `kit` or `human`. |
| `EnrollRequest` | `device` | object |  |
| `EnrollRequest` | `custody` | object | Where the device key is held, required on a key enrollment. |
| `EnrollRequest` | `machine_binding` | string | A value the key holder derives from the machine's identity, required on a key enrollment. |
| `EnrollRequest` | `counter` | integer | The key's check-in counter at enrollment, which must be 0. |
| `EnrollResponse` | `user_id` | string |  |
| `EnrollResponse` | `username` | string |  |
| `EnrollResponse` | `device_id` | string |  |
| `EnrollResponse` | `device_token` | string | No longer sent, because strazad issues no device token. |
| `EnrollResponse` | `device_token_expires_in` | integer | No longer sent, like device_token. |
| `EnrollResponse` | `key_thumbprint` | string | The RFC 7638 thumbprint of the enrolled key, present on a key enrollment only. |
| `EnrollResponse` | `sign_in_expires_in` | integer | Seconds until the person must sign in again to keep this key enrollment, present on a key enrollment only. |
| `ProofRefused` | | | The credential or its DPoP proof was refused. |
| `ProofRefused` | `error` | string |  |
| `ServiceUnavailable` | | | Straza could not reach its store or the issuer while checking the credential. |
| `CheckinRequest` | | | The check-in body: one credential (id_token, device_token or session_token), the device id, the harness, the attestation measurements and the client build. |
| `CheckinRequest` | `id_token` | string |  |
| `CheckinRequest` | `device_token` | string |  |
| `CheckinRequest` | `session_token` | string |  |
| `CheckinRequest` | `device_id` | string |  |
| `CheckinRequest` | `counter` | integer | The key lane's check-in counter, higher than the last one the server accepted for the device. |
| `CheckinRequest` | `harness` | object |  |
| `CheckinRequest` | `attestation` | object |  |
| `CheckinRequest` | `client` | object | The straza build making the check-in; older clients omit it and the server records it on the session unverified. |
| `CheckinResponse` | `session_id` | string |  |
| `CheckinResponse` | `session_token` | string |  |
| `CheckinResponse` | `expires_in` | integer |  |
| `CheckinResponse` | `attestation` | string | One of `managed`, `advisory` or `none`. |
| `CheckinResponse` | `user` | string |  |
| `CheckinResponse` | `roles` | list of string |  |
| `CheckinResponse` | `snapshot_id` | string |  |
| `CheckinResponse` | `knowledge_packs` | list of object |  |
| `CheckinResponse` | `user_type` | string | The identity typology of the session's user. One of `human`, `agent` or `service`. |
| `CheckinResponse` | `agency_mode` | string | One of `interactive`, `supervised` or `autonomous`. |
| `CheckinResponse` | `swarm_id` | string |  |
| `CheckinResponse` | `device_token` | string | No longer sent, because strazad issues no device token. |
| `CheckinResponse` | `device_token_expires_in` | integer | No longer sent, like device_token. |
| `CheckinResponse` | `admin_grants` | string | The session's admin-plane standing, which the console uses to hide inaccessible areas. |
| `CheckinResponse` | `admin_servers` | integer | How many servers name an admin role the session holds. |
| `CheckinResponse` | `git_upstreams` | list of string | The base URLs of the git hosts that MCP servers serve git for through Straza, sorted. |
| `CheckinResponse` | `start_text` | string | The governance paragraph the agent reads at session start. |
| `HarnessConfigDocument` | | | The signed managed harness config a client installs. |
| `HarnessConfigDocument` | `format` | integer | One of `1`. Required. |
| `HarnessConfigDocument` | `kind` | string | One of `harness-config`. Required. |
| `HarnessConfigDocument` | `harness` | string | Required. |
| `HarnessConfigDocument` | `platform` | string | GOOS the artifacts render for Required. |
| `HarnessConfigDocument` | `artifacts` | list of object | Required. |
| `CanonicalEvent` | | | The canonical hook event a client asks a decision on, with its kind, tool, app, command, argv and paths. |
| `CanonicalEvent` | `kind` | string | Required. |
| `CanonicalEvent` | `tool` | string |  |
| `CanonicalEvent` | `app` | string |  |
| `CanonicalEvent` | `toolName` | string | mcp.call: the upstream tool. |
| `CanonicalEvent` | `command` | string |  |
| `CanonicalEvent` | `argv` | list of string |  |
| `CanonicalEvent` | `paths` | list of string |  |
| `CanonicalEvent` | `workspace` | string |  |
| `Decision` | `effect` | string | One of `allow` or `deny`. |
| `Decision` | `ruleId` | string |  |
| `Decision` | `reason` | string |  |
| `Decision` | `obligations` | list of string | Always empty; the field stays for older clients. |
| `Decision` | `snapshotId` | string |  |
| `Decision` | `approvalId` | string | Set when a mode:approve escalation created or consumed an approval record, or when a person's standing denial of the same call answers the deny. |
| `GitResolveRequest` | | | The repo URL to resolve. |
| `GitResolveRequest` | `upstream` | string | The URL git was given, such as https://github.com/Strazahq/straza.git. Required. |
| `GitResolveResponse` | | | The one server that serves git for the repo. |
| `GitResolveResponse` | `srv` | string | The server's metadata.name. Required. |
| `GitResolveResponse` | `repo` | string | The repo's canonical owner/name from the server's object list. Required. |
| `GitResolveResponse` | `aud` | string | The server's canonical straza.git.url, the audience of its git grants. Required. |
| `GitRefusal` | | | Straza does not serve git for this repo URL through exactly one server. |
| `GitRefusal` | `error` | string | The sentence that says what failed and what to do next. Required. |
| `GitRefusal` | `code` | string | Why Straza cannot name one server for the repo. One of `not_listed` or `ambiguous`. Required. |
| `GitGrantRequest` | | | One git operation on one repo for Straza to decide. |
| `GitGrantRequest` | `upstream` | string | The URL git was given, as the resolve route takes it. Required. |
| `GitGrantRequest` | `op` | string | The git operation the grant opens. One of `fetch` or `push`. Required. |
| `GitGrantRequest` | `refs` | list of `GitRefUpdate` | The ref updates a push names, allowed with op push only. |
| `GitGrantRequest` | `waitSeconds` | integer | How long a hold may keep this request waiting, from 0 to approval.gatewayHoldSeconds. |
| `GitRefUpdate` | | | One ref update of a push, as the push's command section names it. |
| `GitRefUpdate` | `ref` | string | The full ref name, such as refs/heads/main. Required. |
| `GitRefUpdate` | `old` | string | The object id the ref holds now, in lower-case hex of 40 or 64 characters, all zeros for a ref the push creates. Required. |
| `GitRefUpdate` | `new` | string | The object id the push sets, in the same form, all zeros for a ref the push deletes. Required. |
| `GitGrantResponse` | | | An issued git grant and what it names. |
| `GitGrantResponse` | `grant` | string | The git grant, a compact JWS of type straza-grant+jwt signed with the session key set. Required. |
| `GitGrantResponse` | `aud` | string | The server's canonical straza.git.url, the grant's audience. Required. |
| `GitGrantResponse` | `repo` | string | The repo's canonical owner/name, which the resource server's path names. Required. |
| `GitGrantResponse` | `srv` | string | The server's metadata.name. Required. |
| `GitGrantResponse` | `exp` | string | When the grant expires, 120 seconds after it was issued. Required. |
| `GitGrantHeld` | | | The answer while a hold keeps a git grant waiting. |
| `GitGrantHeld` | `pending` | `GitGrantPending` | Required. |
| `ConnectStatus` | | | One user's connection on one caller-kind MCP server, an OAuth connection or a pasted token. |
| `ConnectStatus` | `app` | string |  |
| `ConnectStatus` | `kind` | string | The server's credential kind. One of `oauth` or `token`. |
| `ConnectStatus` | `provider` | string | oauth kind only |
| `ConnectStatus` | `agents` | string | What an agent with no row of its own runs on, from the app's manifest. One of `own`, `sponsor`, `shared` or `client_credentials`. |
| `ConnectStatus` | `connected` | boolean |  |
| `ConnectStatus` | `fingerprint` | string | First hex characters of a pasted token's SHA-256; absent on an OAuth connection |
| `ConnectStatus` | `expires_at` | string |  |
| `ConnectStatus` | `updated_at` | string | Last connect/rotation time |
| `ConnectStatus` | `set_by` | string | Username of whoever set the row when it was not the owner. |
| `ConnectStatus` | `allow_agents` | boolean | The owner's opt-in for their sponsored agents |
| `ConnectStatus` | `scopes` | list of string |  |
| `ApproverEnrollTokenResponse` | `enroll_token` | string | One-time secret; shown once. |
| `ApproverEnrollTokenResponse` | `expires_in` | integer | Seconds until the enroll token expires. |
| `ApproverEnrollTokenResponse` | `user` | object |  |
| `ApproverEnrollTokenResponse` | `servers` | list of string | Server-computed base-URL list, in precedence order: [server.approverTLS.publicUrl], else [server.approverPublicUrl], else [server.publicUrl] (trailing slash trimmed; empty when none is set). |
| `ApproverEnrollTokenResponse` | `tls_spki_pin` | string | The pin of the approver listener's TLS key, as sha256, a slash and the standard base64 digest of the SubjectPublicKeyInfo. |
| `ApproverEnrollTokenResponse` | `project` | `ProjectRef` |  |
| `ApproverEnrollTokenResponse` | `qr_payload` | string | The exact compact JSON string the enroll QR must encode, rendered verbatim and never rebuilt client-side. |
| `ApproverEnrollTokenResponse` | `qr` | object | The structured twin of qr_payload (same bytes, parsed). |
| `ServerRow` | | | One managed MCP server as the acting user sees it on the connections page. |
| `ServerRow` | `app` | string | The MCP server's name Required. |
| `ServerRow` | `runtime` | string | The server's runtime kind. One of `remote`, `command` or `oci`. Required. |
| `ServerRow` | `kind` | string | The server's credential kind. One of `none`, `static`, `oauth` or `token`. Required. |
| `ServerRow` | `provider` | string | The OAuth provider |
| `ServerRow` | `agents` | string | What an agent with no row of its own runs on, from the app's manifest. One of `own`, `sponsor`, `shared` or `client_credentials`. |
| `ServerRow` | `reached` | boolean | Whether one of the user's roles holds an access row on the server Required. |
| `ServerRow` | `connected` | boolean | True only for a caller kind with a row for the user Required. |
| `ServerRow` | `fingerprint` | string | First hex characters of a pasted token's SHA-256; absent on an OAuth connection or without a row |
| `ServerRow` | `expires_at` | string | When the row stops working |
| `ServerRow` | `updated_at` | string | When the row was last set |
| `ServerRow` | `set_by` | string | Username of whoever set the row when it was not the owner. |
| `ServerRow` | `allow_agents` | boolean | The owner's opt-in for their sponsored agents; present on caller kinds only |
| `ServerRow` | `scopes` | list of string | The OAuth scopes on the connection |
| `User` | `id` | string |  |
| `User` | `username` | string |  |
| `User` | `email` | string |  |
| `User` | `display` | string |  |
| `User` | `title` | string | SCIM core title (RFC 7643): job title / agent function; informational |
| `User` | `status` | string | One of `active` or `disabled`. |
| `User` | `origin` | string | One of `local` or `scim`. |
| `User` | `kind` | string | what the identity IS (origin says who created it); nhi = created via the agentic-SCIM extension. One of `human` or `nhi`. |
| `User` | `external_id` | string |  |
| `User` | `user_type` | string | The identity typology; absent means unclassified. One of `human`, `agent` or `service`. |
| `User` | `agency_mode` | string | One of `interactive`, `supervised` or `autonomous`. |
| `User` | `sponsor` | string | the accountable person behind an agent identity |
| `User` | `swarm_id` | string |  |
| `User` | `ephemeral` | boolean |  |
| `User` | `entra_agent_id` | string | The client id of the Entra agent identity an AI agent acts as at Entra, a lower-case GUID. |
| `User` | `sponsored_count` | integer | How many agents name this user as their sponsor. |
| `UserCreate` | `username` | string | Required. |
| `UserCreate` | `email` | string |  |
| `UserCreate` | `display` | string |  |
| `UserCreate` | `title` | string |  |
| `UserCreate` | `password` | string | A person's password for the built-in sign-in page. |
| `UserCreate` | `kind` | string | nhi provisions an agent identity, such as a headless AI agent. One of `human` or `nhi`. |
| `UserCreate` | `user_type` | string | The type of an nhi, an AI agent or a service account. One of `agent` or `service`. |
| `UserUpdate` | `email` | string |  |
| `UserUpdate` | `display` | string |  |
| `UserUpdate` | `title` | string |  |
| `UserUpdate` | `status` | string | One of `active` or `disabled`. |
| `UserUpdate` | `password` | string | A person's new password. |
| `UserUpdate` | `user_type` | string | set or clear (empty) the typology; standalone-admin lane, since enterprise masters this over SCIM. One of `human`, `agent`, `service` or ``. |
| `UserUpdate` | `agency_mode` | string | One of `interactive`, `supervised`, `autonomous` or ``. |
| `UserUpdate` | `sponsor` | string |  |
| `UserUpdate` | `swarm_id` | string |  |
| `UserUpdate` | `ephemeral` | boolean |  |
| `UserUpdate` | `entra_agent_id` | string | Sets the client id of the Entra agent identity the agent acts as at Entra, a GUID in any case, stored in lower case. |
| `Status` | | | Operation result |
| `Status` | `status` | string |  |
| `Device` | | | One enrolled client device of a user, with snake_case keys. |
| `Device` | `id` | string |  |
| `Device` | `user_id` | string |  |
| `Device` | `name` | string |  |
| `Device` | `fingerprint` | string |  |
| `Device` | `platform` | string |  |
| `Device` | `status` | string |  |
| `Device` | `client_kind` | string | The kind of client that enrolled the device. |
| `Device` | `enrolled_at` | string |  |
| `Device` | `custody` | object | Where the device's key is kept, as its key enrollment stated it, and absent on a device without a key. |
| `Role` | `id` | string |  |
| `Role` | `name` | string |  |
| `Role` | `description` | string |  |
| `Role` | `kind` | string | One of `business`, `application`, `approver` or `straza`. |
| `Role` | `assigned_count` | integer | Assignment rows holding this role, grouped server-side (validity windows included): the number mirrors the assignment list an admin sees and can revoke, not effective validity. |
| `Role` | `holder_count` | integer | Subjects holding the role at read time through any path, each subject counted once. |
| `Role` | `implies` | list of string | Names of the roles this role composes directly, sorted; absent when none. |
| `Role` | `areas` | list of string | A Straza role's console scopes from admin.roleAreas as area:verb, sorted, or the one word full for straza-admin. |
| `Role` | `decider_in` | list of string | For an approver role, the names of the active policy sets naming it in approve.roles, in store order without repeats. |
| `Role` | `server` | string | The name of the server that owns the role, absent on a global role. |
| `Role` | `tools` | list of string | The tool list of a server-owned role, read off its one access row on its server. |
| `RoleCreate` | `name` | string | Required. |
| `RoleCreate` | `description` | string |  |
| `RoleCreate` | `kind` | string | One of `business`, `application`, `approver` or `straza`. |
| `RoleCreate` | `server` | string | The name of the server that owns the role. |
| `RoleCreate` | `tools` | list of string | The tool names a server-owned role reaches on its server, required with server. |
| `RoleCreate` | `covers` | `Covers` | Which objects of the server's pinned type a server-owned role covers. |
| `Covers` | | | A role's covers line says which objects of a server's pinned type, such as repo, its access row covers. |
| `Covers` | `every` | boolean | Covers every object of the type, the ones the server lists later included. One of `true`. |
| `Covers` | `objects` | list of object | The objects covered, each named once, sorted by value in an answer. |
| `DirectConflict` | | | The change did not land, and nothing was changed. |
| `DirectConflict` | `error` | string | Required. |
| `DirectConflict` | `correlation_id` | string |  |
| `DirectBusy` | | | The database turned the change away three times while other changes were written, and nothing was changed. |
| `DirectBusy` | `error` | string | Required. |
| `DirectBusy` | `correlation_id` | string |  |
| `RoleUpdate` | | | PATCH semantics: absent = keep, present = set. |
| `RoleUpdate` | `description` | string |  |
| `RoleUpdate` | `kind` | string | One of `business`, `application`, `approver` or `straza`. |
| `RoleDeleted` | | | The role is deleted. |
| `RoleDeleted` | `status` | string |  |
| `RoleDeleted` | `sets_off` | list of string |  |
| `Assignment` | `id` | string |  |
| `Assignment` | `subject_kind` | string | One of `user`. Required. |
| `Assignment` | `subject_id` | string | Required. |
| `Assignment` | `role_id` | string | Required. |
| `Assignment` | `valid_from` | string |  |
| `Assignment` | `valid_to` | string |  |
| `Assignment` | `origin` | string | The lane that wrote the row, scim for an identity manager group membership and admin for the admin API. One of `scim` or `admin`. |
| `Pack` | `id` | string |  |
| `Pack` | `name` | string | Required. |
| `Pack` | `version` | string |  |
| `Pack` | `content` | string |  |
| `Pack` | `bindings` | list of object | Which roles receive this knowledge pack; empty means bound to nothing, so no session ever sees it. |
| `PackBinding` | | | The edge that binds one knowledge pack to one role, as the bind answer returns it. |
| `PackBinding` | `pack_id` | string | The id of the bound pack. Required. |
| `PackBinding` | `role_id` | string | The id of the role that receives the knowledge pack; also the binding id the unbind DELETE consumes. Required. |
| `PolicySet` | `id` | string |  |
| `PolicySet` | `name` | string |  |
| `PolicySet` | `priority` | integer |  |
| `PolicySet` | `status` | string | One of `draft` or `active`. |
| `PolicySet` | `yaml` | string | The stored policy set source, or the text of the set's open saved edit. |
| `PolicySet` | `updated_at` | string |  |
| `PolicySet` | `drift` | boolean | True while the set has an open saved edit, whose priority, summary and updated_at the row then carries. |
| `PolicySet` | `summary` | object | Server-computed decomposition of the stored set, from the same parse validate uses, so clients can render a set's shape without re-parsing the YAML. |
| `DraftPage` | `items` | list of `DraftSummary` | Required. |
| `DraftPage` | `next_cursor` | string | Empty on the last page. Required. |
| `DraftsUnavailable` | | | Straza could not read what the route needs, live state above all, so nothing was saved or published. |
| `DraftsUnavailable` | `error` | string | Required. |
| `DraftsUnavailable` | `correlation_id` | string | The correlation id of the answer, as the server log records it. |
| `DraftBody` | `documents` | list of string | YAML streams of App, Role, PolicySet and Removal documents. |
| `DraftBody` | `items` | list of `DraftBodyItem` |  |
| `DraftBody` | `note` | string | At most 2,000 bytes, without invisible direction or zero-width characters. |
| `DraftBody` | `working` | boolean | Add to the caller's working draft. |
| `DraftBody` | `revision` | integer | Accepted and ignored. |
| `DraftBodyItem` | | | One object of a request's items form. |
| `DraftBodyItem` | `kind` | string | One of `App`, `Role` or `PolicySet`. Required. |
| `DraftBodyItem` | `name` | string | Required. |
| `DraftBodyItem` | `op` | string | put writes doc, off stores a PolicySet turned off with doc as its text, and remove deletes. One of `put`, `off` or `remove`. Required. |
| `DraftBodyItem` | `doc` | string | The document: the app.yaml of an App, a Role document, the text of a PolicySet. |
| `DraftBodyItem` | `base` | string | Accepted and ignored. |
| `DraftBodyItem` | `existed` | boolean | Accepted and ignored. |
| `DraftBodyItem` | `withheld` | string | Accepted and ignored. |
| `DraftAnswer` | `draft` | `Draft` | Required. |
| `DraftAnswer` | `verdict` | `DraftVerdict` | Required. |
| `DraftTooLarge` | | | The body holds more than server.maxBodyBytes, the most strazad reads in one request, so it was not read. |
| `DraftTooLarge` | `error` | string | Required. |
| `DraftRefused` | | | A refusal with its detail. |
| `DraftRefused` | `error` | string | Required. |
| `DraftRefused` | `findings` | list of `DraftFinding` |  |
| `DraftRefused` | `verdict` | `DraftVerdict` |  |
| `DraftRefused` | `code` | string | second_person on a publish that admin.secondPerson refused to this caller. One of `second_person`. |
| `DraftCheckAnswer` | `items` | list of `DraftItem` | Required. |
| `DraftCheckAnswer` | `verdict` | `DraftVerdict` | Required. |
| `DraftDetail` | `draft` | `Draft` | Required. |
| `DraftDetail` | `verdict` | `DraftVerdict` | Required. |
| `DraftDetail` | `revisions` | list of `DraftRevision` | Required. |
| `DraftDetail` | `live` | object | The live state of each item and implied object by Kind/Name, env values and address secrets masked. Required. |
| `DraftDetail` | `contacted` | object | The tools a Contact read for each App item's current document, by Kind/Name. |
| `DraftDetail` | `changes` | list of `DraftChange` | The change record of a published draft. |
| `DraftDetail` | `checks` | object | The counts of the stored check of a published, discarded or expired draft. |
| `DraftDetail` | `may_publish` | boolean | Whether the caller may publish it now, by who the caller is and the standing each item needs. Required. |
| `DraftDetail` | `publish_refusal` | string | Why the caller may not publish an open draft. |
| `DraftUpdate` | `revision` | integer | Required. |
| `DraftUpdate` | `documents` | list of string |  |
| `DraftUpdate` | `items` | list of `DraftBodyItem` |  |
| `DraftUpdate` | `note` | string |  |
| `DraftUpdate` | `working` | boolean | Accepted and ignored. |
| `DraftDiscard` | `revision` | integer |  |
| `DraftDiscard` | `reason` | string | At most 500 bytes of plain text. |
| `DraftRevert` | `note` | string |  |
| `DraftRebase` | `revision` | integer | Required. |
| `DraftRebase` | `picks` | object | Keyed by Kind/Name, a space and the field. |
| `DraftConflicts` | `error` | string | Required. |
| `DraftConflicts` | `conflicts` | list of object |  |
| `DraftContact` | `object` | string | The App item of the draft to contact, as Kind/Name, such as App/github. Required. |
| `DraftContacted` | `object` | string | Required. |
| `DraftContacted` | `host` | string | The host in its ASCII form. Required. |
| `DraftContacted` | `contacted_at` | string | Required. |
| `DraftContacted` | `server` | object | Required. |
| `DraftContacted` | `tools` | list of object | Required. |
| `DraftPublish` | `revision` | integer | Required. |
| `DraftPublish` | `risk_digest` | string | The verdict's risk_digest as the publisher read it, 64 hex characters, or empty. Required. |
| `DraftPublish` | `ticked` | list of string | The key of every risk confirmed, tick and typed, as each finding carries it. |
| `DraftPublish` | `typed` | object | The text typed for each typed risk, by key. |
| `DraftPublished` | `draft` | `Draft` | Required. |
| `DraftPublished` | `snapshot` | string | The policy snapshot the publish left active. Required. |
| `DraftPublished` | `servers` | list of object | The servers the publish created, changed or removed, as this replica runs them after the apply. Required. |
| `DraftPublished` | `next` | list of string | The fix of every readiness warning the verdict held, each once. Required. |
| `App` | `id` | string |  |
| `App` | `name` | string |  |
| `App` | `version` | string |  |
| `App` | `runtime` | string | One of `command`, `remote` or `oci`. |
| `App` | `status` | string | One of `pending`, `starting`, `running`, `degraded`, `stopped` or `failed`. |
| `App` | `detail` | string | The health reason. |
| `App` | `source` | string | One of `api`, `gitops` or `registry`. |
| `App` | `tools` | list of string |  |
| `App` | `last_probe_at` | string | Last completed health evaluation (absent until first probe) |
| `App` | `last_healthy_at` | string | Last probe that settled the server running (absent while never healthy) |
| `App` | `status_since` | string | When the status word last changed; a new detail under the same word keeps it. |
| `App` | `paused` | boolean | True when an admin disabled this MCP server and GitOps does not resurrect it; absent or false otherwise. |
| `App` | `reached_by` | list of string | The roles holding an access row on this server, sorted; an empty array when none. |
| `App` | `manifest` | object | The installed manifest as a JSON object in the app.yaml shape (apiVersion, kind, metadata, server, straza), masked as every route answers a server's document. |
| `App` | `url` | string | The remote runtime's address as manifest.straza.runtime.remote.url reads it, masked the same way. |
| `App` | `file` | string | The full path of the watched apps directory file that names this server, absent when no present file does. |
| `App` | `file_differs` | boolean | True when that file's manifest differs from the live one, or does not read. |
| `App` | `offered` | list of string | Every tool the server itself lists, sorted, before the manifest's exposure list. |
| `App` | `admin_role` | string | The Straza role that administers this server. |
| `App` | `admin_role_id` | string | The id of admin_role. |
| `App` | `may_change` | boolean | Whether the caller may change this server. |
| `App` | `may_cover_every` | boolean | Whether the caller may make a role this server owns cover every object of the server's pinned type, the objects the server lists later included. |
| `ToolBinding` | `id` | string |  |
| `ToolBinding` | `app` | string |  |
| `ToolBinding` | `role` | string |  |
| `ToolBinding` | `tools` | list of string |  |
| `ToolBinding` | `covers` | `Covers` | Which objects of the server's pinned type the row covers, absent on a server that pins no type. |
| `Tool` | | | One exposed MCP tool from the live catalog. |
| `Tool` | `id` | string |  |
| `Tool` | `app` | string |  |
| `Tool` | `app_id` | string |  |
| `Tool` | `name` | string |  |
| `Tool` | `description` | string | Upstream tool description (absent when the server publishes none) |
| `AppSecret` | | | One stored static secret of an MCP server, never its value. |
| `AppSecret` | `id` | string |  |
| `AppSecret` | `app` | string |  |
| `AppSecret` | `scope` | string | One of `app` or `role`. |
| `AppSecret` | `role` | string |  |
| `AppSecret` | `kind` | string | One of `static`. |
| `AppSecret` | `fingerprint` | string | The first four hex characters of the SHA-256 of the value |
| `AppSecret` | `set_at` | string | When the value was last set (listing only) |
| `ObjectList` | | | One page of a server's object list with the state of its listing. |
| `ObjectList` | `app` | string | Required. |
| `ObjectList` | `type` | string | The pinned object type; empty when the server pins none Required. |
| `ObjectList` | `plural` | string |  |
| `ObjectList` | `attributes` | list of `ObjectAttribute` |  |
| `ObjectList` | `pinned` | any | The published straza.objects block, or null |
| `ObjectList` | `declared` | any | The block the server's live tool marks declare, or null when its tools carry none |
| `ObjectList` | `declaredFaults` | list of string | One sentence per rule the marks break; the declared block cannot be pinned while any is present |
| `ObjectList` | `drift` | boolean | True when declared is not null and differs from pinned |
| `ObjectList` | `listing` | any |  |
| `ObjectList` | `objects` | list of `ListedObject` | Required. |
| `ObjectList` | `total` | integer | Entries that match q, across every page Required. |
| `ObjectList` | `next` | string | The after value of the next page; absent on the last page |
| `ListingCredential` | | | The stored listing credential of a server, never its value. |
| `ListingCredential` | `app` | string | Required. |
| `ListingCredential` | `fingerprint` | string | The first four hex characters of the SHA-256 of the value Required. |
| `ListingCredential` | `setAt` | string | Required. |
| `Session` | `id` | string |  |
| `Session` | `user_id` | string |  |
| `Session` | `username` | string | Resolved owner username (empty if the user row is gone) |
| `Session` | `harness` | string |  |
| `Session` | `client_version` | string | The straza build the client named at check-in; absent for a client older than the field or a web login |
| `Session` | `client_commit` | string | The git commit of the straza build named at check-in, at most 64 bytes, absent for older clients and sessions and for a web login. |
| `Session` | `attestation` | string |  |
| `Session` | `status` | string | active \| revoked \| closed (janitor closes sessions idle past token expiry) |
| `Session` | `started_at` | string |  |
| `Session` | `last_seen` | string |  |
| `Session` | `wiring_status` | string | The session's managed-wiring hash classified against the published harness-config render and the expected-hash registry. One of `current`, `allowed`, `mismatch` or `unmeasured`. |
| `Session` | `wiring_hash` | string | The hooks measurement the session checked in with, as hooks, a dot, the harness name, then sha256, a colon and the hex digest. |
| `ConversationTurn` | | | One recorded prompt or reply from a governed session. |
| `ConversationTurn` | `at` | string |  |
| `ConversationTurn` | `kind` | string | One of `prompt` or `reply`. |
| `ConversationTurn` | `mode` | string | One of `verbatim` or `redact`. |
| `ConversationTurn` | `content` | string |  |
| `ConversationTurn` | `truncated` | boolean |  |
| `ConversationTurn` | `content_hash` | string |  |
| `ConversationTurn` | `agent_type` | string | The delegate class that produced this turn, for a reply recorded when a subagent stopped. |
| `ConversationTurn` | `session_id` | string |  |
| `ConversationTurn` | `user_id` | string |  |
| `ConversationTurn` | `username` | string |  |
| `ApprovalDecideBody` | | | Optional body for the console's decide lane. |
| `ApprovalDecideBody` | `reason` | string | The decider's own words on either verdict, at most 500 bytes of plain text. |
| `ApproverEnrollTokenRequest` | | | The user an older client names, by id or username. |
| `ApproverEnrollTokenRequest` | `user_id` | string |  |
| `ApproverEnrollTokenRequest` | `username` | string |  |
| `ApproverEnrollRequest` | `enroll_token` | string | Required. |
| `ApproverEnrollRequest` | `device` | object | Required. |
| `ApproverThrottled` | | | Per-IP rate limit on the DEDICATED approver listener (server. |
| `ApproverThrottled` | `error` | string |  |
| `ApproverEnrollResponse` | `approver_device_id` | string | apd_ prefixed. |
| `ApproverEnrollResponse` | `device_token` | string | use=approver, ~30 day TTL; opens only /v1/approver/*. |
| `ApproverEnrollResponse` | `expires_in` | integer |  |
| `ApproverEnrollResponse` | `project` | `ProjectRef` |  |
| `ApproverEnrollResponse` | `fcm` | `FCMAppConfig` |  |
| `ApproverEnrollResponse` | `webpush` | `WebPushAdvert` |  |
| `ApproverRefreshChallengeRequest` | `approver_device_id` | string | apd_ prefixed; the device that signs the challenge. Required. |
| `ApproverRefreshChallengeResponse` | `challenge` | string | base64url single-use nonce, ≤5m; sign it to obtain a new token. |
| `ApproverRefreshChallengeResponse` | `expires_in` | integer | Seconds until the challenge expires. |
| `ApproverError` | | | Approver-surface error envelope. |
| `ApproverError` | `error` | string | Required. |
| `ApproverError` | `code` | string | One of `missing_token`, `token_expired`, `token_invalid`, `device_revoked`, `user_inactive`, `challenge_rejected`, `not_authorized`, `invalid_cursor` or `service_unavailable`. |
| `ApproverError` | `correlation_id` | string | The correlation id of this answer, present on 5xx and recovered-panic answers. |
| `ApproverRefreshRequest` | `approver_device_id` | string | Required. |
| `ApproverRefreshRequest` | `challenge` | string | The challenge from /v1/approver/refresh/challenge. Required. |
| `ApproverRefreshRequest` | `signature` | string | base64 ECDSA-P256/SHA-256, ASN.1 DER (variable length), over the exact byte string "refresh" + "\n" + approver_device_id + "\n" + challenge. Required. |
| `ApproverRefreshResponse` | `device_token` | string | A fresh use=approver token, same 30-day TTL and scope as enroll's. |
| `ApproverRefreshResponse` | `expires_in` | integer | Seconds until the new device token expires (~30 days). |
| `ApproverRow` | | | One pending/history record for the Straza approver app. |
| `ApproverRow` | `id` | string |  |
| `ApproverRow` | `created_at` | string |  |
| `ApproverRow` | `expires_at` | string |  |
| `ApproverRow` | `requester` | object | The subject of the request, the identity whose authority is on the line. |
| `ApproverRow` | `origin` | object | Who actually raised the request. |
| `ApproverRow` | `rule_id` | string |  |
| `ApproverRow` | `set_name` | string |  |
| `ApproverRow` | `summary` | object |  |
| `ApproverRow` | `justification` | string | Agent's stated reason, UNVERIFIED. |
| `ApproverRow` | `challenge` | string | decidable rows only; fresh per fetch, single-use, ≤5m. |
| `ApproverRow` | `state` | string | mine/history rows. One of `pending`, `approved`, `denied` or `expired`. |
| `ApproverRow` | `decided_by` | string |  |
| `ApproverRow` | `decided_at` | any |  |
| `ApproverRow` | `decided_via` | object | How the decision was made: the surface the decider used and, on the signed lane, the enrolled device whose key signed it. |
| `ApproverRow` | `decided_reason` | string | The decider's own words on either verdict, optional, at most 500 bytes. |
| `ApproverRow` | `mode` | string | Present, as confirm, only on a record the requester alone decides: the row is in your queue because you requested it. One of `confirm`. |
| `ApproverRow` | `session_id` | string | The agent session the requested call would run in: the record's own session reference. |
| `ApproverRow` | `harness` | string | The harness that session checked in as (e.g. |
| `ApproverRow` | `approver_roles` | list of string | The roles allowed to decide this record, the winning rule's approve.roles persisted at request time. |
| `ApproverRow` | `approver_users` | list of string | The usernames allowed to decide this record, resolved from the rule's approve.deciders at request time, today the requester's sponsor. |
| `ApproverRow` | `class` | string | The approve class of the record, hold or ticket. One of `hold` or `ticket`. |
| `ApproverRow` | `grant_expires_at` | string | The last moment a later call can use the approval, for a ticket and, since revision 23, for a retry of a hold. |
| `ApproverRow` | `consumed_at` | string | When a call used the approval. |
| `ApproverRow` | `consumed_by` | string | The session that used the approval. |
| `ApproverRow` | `args_preview` | string | Redacted, display-safe, 2 KiB-capped preview of the concrete call arguments the fingerprint binds. |
| `ApproverRow` | `args_truncated` | boolean | True when args_preview was head+tail elided past the 2 KiB cap. |
| `ApproverRow` | `args_bytes` | integer | The byte length of the redacted preview before truncation, the size a person could have seen at full length. |
| `ApproverRow` | `argv_hash_prefix` | string | First 12 hex of the argv_hash digest (no 'sha256:' prefix); the visible non-binding tag beside the honesty line. |
| `ApproverRow` | `binding_scope` | string | What the record's fingerprint covers. One of `call` or `tool_identity`. |
| `ApproverRow` | `lane` | string | The lane that raised the request, the hook on the agent's machine or the MCP gateway. One of `hook` or `gateway`. |
| `ApproverDecideRequest` | `request_id` | string | Required. |
| `ApproverDecideRequest` | `verdict` | string | One of `approve` or `deny`. Required. |
| `ApproverDecideRequest` | `challenge` | string | Required. |
| `ApproverDecideRequest` | `signature` | string | base64 ECDSA-P256/SHA-256, ASN.1 DER (variable length). Required. |
| `ApproverDecideRequest` | `ts` | integer | Client unix seconds; ±5m window. Required. |
| `ApproverDecideRequest` | `reason` | string | The decider's optional own words on either verdict, at most 500 bytes of plain text. |
| `ApproverPushRequest` | `kind` | string | One of `fcm`, `apns`, `unifiedpush` or `webpush`. Required. |
| `ApproverPushRequest` | `token_or_endpoint` | string | Required. |
| `ApproverPushRequest` | `p256dh` | string | OPTIONAL Web Push subscription public key (RFC 8291 §3.2): unpadded base64url of the 65-octet uncompressed P-256 point, exactly PushSubscription.toJSON().keys.p256dh, or UnifiedPush connector 3.x PushEndpoint.pubKeySet. |
| `ApproverPushRequest` | `auth` | string | OPTIONAL Web Push subscription auth secret (RFC 8291 §3.2): unpadded base64url of exactly 16 octets. |
| `AttestationHash` | | | One expected-measurement row in the managed-install registry. |
| `AttestationHash` | `id` | string |  |
| `AttestationHash` | `artifact` | string | The measurement key: self, config, or hooks followed by a dot and the harness name, such as hooks.claude-code. Required. |
| `AttestationHash` | `harness` | string | Harness this row applies to; empty = all |
| `AttestationHash` | `platform` | string | GOOS/GOARCH this row applies to; empty = all |
| `AttestationHash` | `hash` | string | Required. |
| `AttestationHash` | `note` | string |  |
| `AttestationHash` | `created_at` | string |  |
| `AttestationHash` | `current` | boolean | True when this row's hash is the wiring the answering server renders right now for that artifact and harness. |
| `ApproverVersion` | | | The approver listener's public address and TLS pin, present only when strazad itself terminates approver TLS. |
| `ApproverVersion` | `public_url` | string | Required. |
| `ApproverVersion` | `tls_spki_pin` | string | Required. |
| `ApproverVersion` | `cert_not_after` | string | RFC 3339; omitted when unknown |
| `ApproverVersion` | `auto_minted` | boolean | Required. |
| `ApproverVersion` | `cert_file` | string |  |
| `GitGrantPending` | | | The approval request that holds a git grant. |
| `GitGrantPending` | `ref` | string | The approval request id. Required. |
| `GitGrantPending` | `expiresAt` | string | When the approval request expires if nobody decides it. Required. |
| `ProjectRef` | | | This deployment's identity for the Straza approver app across backends. |
| `ProjectRef` | `id` | string | prj_ prefixed, stable per deployment. |
| `ProjectRef` | `name` | string | Display label, <=64 chars. |
| `DraftSummary` | `id` | string | Required. |
| `DraftSummary` | `title` | string | Required. |
| `DraftSummary` | `state` | string | One of `open`, `published`, `discarded` or `expired`. Required. |
| `DraftSummary` | `door` | string | One of `console`, `strazactl`, `straza-app`, `apps-directory` or `api`. Required. |
| `DraftSummary` | `source` | string |  |
| `DraftSummary` | `revision` | integer | Required. |
| `DraftSummary` | `proposer` | `DraftPrincipal` | Required. |
| `DraftSummary` | `items` | list of object | Required. |
| `DraftSummary` | `checks` | object | The counts the server stored with its last check of an open draft, absent on the others and before the first check. |
| `DraftSummary` | `working` | boolean |  |
| `DraftSummary` | `policy_edit` | string |  |
| `DraftSummary` | `created_at` | string | Required. |
| `DraftSummary` | `updated_at` | string | Required. |
| `DraftSummary` | `decided_at` | string |  |
| `DraftSummary` | `decided_by` | `DraftPrincipal` |  |
| `Draft` | | | A set of items that publish together or not at all. |
| `Draft` | `id` | string | The draft's number as a decimal string. Required. |
| `Draft` | `revision` | integer | Required. |
| `Draft` | `state` | string | One of `open`, `published`, `discarded` or `expired`. Required. |
| `Draft` | `door` | string | One of `console`, `strazactl`, `straza-app`, `apps-directory` or `api`. Required. |
| `Draft` | `source` | string | The apps directory file that proposed it. |
| `Draft` | `note` | string | The proposer's own words, at most 2,000 bytes, never a check. |
| `Draft` | `authors` | list of `DraftPrincipal` | Required. |
| `Draft` | `items` | list of `DraftItem` | Required. |
| `Draft` | `reverts` | string | The published draft this one undoes. |
| `Draft` | `title` | string | Computed from the items, never from the note. Required. |
| `Draft` | `working` | boolean |  |
| `Draft` | `policy_edit` | string | The policy set whose saved edit this draft holds. |
| `Draft` | `refusal` | string | Why an apps directory file became no items. |
| `Draft` | `created_at` | string | Required. |
| `Draft` | `updated_at` | string | Required. |
| `Draft` | `expires_at` | string |  |
| `Draft` | `decided_at` | string |  |
| `Draft` | `decided_by` | `DraftPrincipal` |  |
| `Draft` | `decided_reason` | string |  |
| `Draft` | `snapshot` | string | The policy snapshot the publish left active. |
| `DraftVerdict` | | | The server's reading of one revision against live state. |
| `DraftVerdict` | `draft` | string | Empty on POST /v1/admin/drafts/check, which stores nothing. Required. |
| `DraftVerdict` | `revision` | integer | 0 on POST /v1/admin/drafts/check. Required. |
| `DraftVerdict` | `snapshot` | string | The active policy snapshot it was checked against, empty when checked_at is. Required. |
| `DraftVerdict` | `checked_at` | any | When the check ran. Required. |
| `DraftVerdict` | `refused` | list of `DraftFinding` | Required. |
| `DraftVerdict` | `risks` | list of `DraftFinding` | Required. |
| `DraftVerdict` | `warnings` | list of `DraftFinding` | Required. |
| `DraftVerdict` | `unchecked` | list of `DraftFinding` | Required. |
| `DraftVerdict` | `passed` | list of `DraftFinding` | Required. |
| `DraftVerdict` | `info` | list of `DraftFinding` | Required. |
| `DraftVerdict` | `gains` | list of `DraftGain` | Required. |
| `DraftVerdict` | `objects` | list of `DraftCoverage` | What each role the draft touches covers on a server that pins an object type, now and after publishing. |
| `DraftVerdict` | `needs` | list of `DraftNeed` | Required. |
| `DraftVerdict` | `risk_digest` | string | The hex sha256 over the keys of every risk, which a publish carries back. Required. |
| `DraftFinding` | | | One line of a verdict. |
| `DraftFinding` | `code` | string | A dotted code such as policy.pool or access.ungated. Required. |
| `DraftFinding` | `class` | string | One of `refused`, `risk`, `warning`, `unchecked`, `passed` or `info`. Required. |
| `DraftFinding` | `ack` | string | On a risk: typed when republishing the old state cannot undo the effect. One of `tick` or `typed`. |
| `DraftFinding` | `object` | string | Kind/Name of the object the line is about. |
| `DraftFinding` | `sentence` | string | Required. |
| `DraftFinding` | `fix` | string |  |
| `DraftFinding` | `before` | string |  |
| `DraftFinding` | `after` | string |  |
| `DraftFinding` | `typed` | string | The text a publisher types to confirm a typed risk. |
| `DraftFinding` | `group` | string | On a risk only: the risks a client lets the publisher confirm together, once for the whole group, which is the risk's code. |
| `DraftFinding` | `key` | string | The finding's key from before any cut for its reader, which a publish echoes in ticked and typed. Required. |
| `DraftFinding` | `document` | integer | The number of the sent document a reading refusal names, counted from 1 across every text sent. |
| `DraftItem` | | | One object a draft creates, changes, turns off or removes. |
| `DraftItem` | `kind` | string | One of `App`, `Role` or `PolicySet`. Required. |
| `DraftItem` | `name` | string | Required. |
| `DraftItem` | `op` | string | put writes doc, off stores a PolicySet turned off with doc as its text, and remove deletes. One of `put`, `off` or `remove`. Required. |
| `DraftItem` | `doc` | string | The canonical document: the app.yaml of an App, the export form of a Role, the text of a PolicySet. |
| `DraftItem` | `base` | string | The object's content fingerprint at the draft's last check, answered only to a caller who may read the object. |
| `DraftItem` | `withheld` | string | Why doc and base are left out: the caller reaches the draft only as an author, and the object is outside its read standing. |
| `DraftItem` | `existed` | boolean | Whether the object existed at the draft's last check. Required. |
| `DraftRevision` | `revision` | integer |  |
| `DraftRevision` | `author` | `DraftPrincipal` |  |
| `DraftRevision` | `door` | string |  |
| `DraftRevision` | `digest` | string |  |
| `DraftRevision` | `mechanical` | boolean | A Check again that took live values with no pick, which makes no author under admin.secondPerson. |
| `DraftRevision` | `created_at` | string |  |
| `DraftChange` | | | The published before and after of one object, the change record. |
| `DraftChange` | `kind` | string | One of `App`, `Role` or `PolicySet`. |
| `DraftChange` | `name` | string |  |
| `DraftChange` | `implied` | boolean | Changed by another item, such as a role that lost its access row with its server. |
| `DraftChange` | `before_op` | string | One of `put`, `off` or `remove`. |
| `DraftChange` | `before_doc` | string |  |
| `DraftChange` | `before_fp` | string |  |
| `DraftChange` | `after_op` | string | One of `put`, `off` or `remove`. |
| `DraftChange` | `after_doc` | string |  |
| `DraftChange` | `after_fp` | string |  |
| `ObjectAttribute` | | | One attribute a listing keeps, and who may set its value in the source system. |
| `ObjectAttribute` | `name` | string | Required. |
| `ObjectAttribute` | `setBy` | string | One of `org` or `object`. |
| `ListedObject` | | | One entry of the object list. |
| `ListedObject` | `value` | string | Required. |
| `ListedObject` | `id` | string | Required. |
| `ListedObject` | `title` | string |  |
| `ListedObject` | `attributes` | object |  |
| `ListedObject` | `new` | boolean | Joined at the current version, which is above 1 Required. |
| `ListedObject` | `coveredBy` | list of string | The roles that cover the entry, sorted; empty when no role does Required. |
| `ListedObject` | `drafts` | list of object | The open drafts the caller may read that would add or drop a role covering the entry. |
| `FCMAppConfig` | | | The deployment's public Firebase app config for the bring-your-own Firebase push lane. |
| `FCMAppConfig` | `project_id` | string | project_info.project_id. Required. |
| `FCMAppConfig` | `app_id` | string | client[].client_info.mobilesdk_app_id (1:NNN:android:HEX, NOT the package name). Required. |
| `FCMAppConfig` | `api_key` | string | client[].api_key[0].current_key. Required. |
| `FCMAppConfig` | `sender_id` | string | project_info.project_number. Required. |
| `WebPushAdvert` | | | The deployment's WebPush advert, the same object on the enroll 201 and in the enroll QR, so the two surfaces cannot diverge. |
| `WebPushAdvert` | `vapid_public_key` | string | The deployment's VAPID public key (RFC 8292): unpadded base64url of the 65-octet uncompressed P-256 point. |
| `DraftPrincipal` | | | Who wrote a revision of a draft or decided it, as the server authenticated them. |
| `DraftPrincipal` | `user_id` | string | Required. |
| `DraftPrincipal` | `username` | string | Required. |
| `DraftPrincipal` | `agent` | boolean | True for a user who is not a person. Required. |
| `DraftPrincipal` | `via` | string | One of `login`, `session`, `api-token`, `file` or `upgrade`. Required. |
| `DraftPrincipal` | `client` | string | The session's client, such as console, strazactl or claude-code, else id-token, api-token, or strazad for the apps directory and the upgrade. Required. |
| `DraftPrincipal` | `sponsor_id` | string |  |
| `DraftPrincipal` | `sponsor` | string | The sponsor of an agent author, as its session resolved it. |
| `DraftGain` | | | One row of who gains what, a role and a tool, today and after publishing. |
| `DraftGain` | `role` | string | Required. |
| `DraftGain` | `server` | string | Required. |
| `DraftGain` | `tool` | string | * when the server's tools are unknown. Required. |
| `DraftGain` | `holders` | list of string | Usernames, sent only to root and to a caller holding identity:read. |
| `DraftGain` | `holders_count` | integer | How many users hold the role, directly or through another role. Required. |
| `DraftGain` | `before` | string | One of `runs`, `needs-approval`, `denied`, `not-reachable` or `unknown`. Required. |
| `DraftGain` | `after` | string | One of `runs`, `needs-approval`, `denied`, `not-reachable` or `unknown`. Required. |
| `DraftGain` | `before_words` | string |  |
| `DraftGain` | `after_words` | string |  |
| `DraftCoverage` | | | What one role reaches on one server that pins an object type, today and after publishing, for every role the draft touches there. |
| `DraftCoverage` | `role` | string | Required. |
| `DraftCoverage` | `server` | string | Required. |
| `DraftCoverage` | `type` | string | Required. |
| `DraftCoverage` | `plural` | string | Required. |
| `DraftCoverage` | `holders` | list of string | Usernames, sent only to root and to a caller holding identity:read. |
| `DraftCoverage` | `holders_count` | integer | How many users hold the role, directly or through another role. Required. |
| `DraftCoverage` | `every_before` | boolean | Required. |
| `DraftCoverage` | `every_after` | boolean | Required. |
| `DraftCoverage` | `before` | list of `DraftObjectName` | Required. |
| `DraftCoverage` | `after` | list of `DraftObjectName` | Required. |
| `DraftNeed` | `object` | string | Required. |
| `DraftNeed` | `standing` | string | The standing that object needs from its publisher, in words. Required. |
| `DraftObjectName` | | | One object of a server, the id Straza resolved and the value a role file writes for it. |
| `DraftObjectName` | `id` | string | Required. |
| `DraftObjectName` | `value` | string | Required. |



