STRAZAdocs

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.

On this page

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.140.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, 131 operations on 108 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. 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 serves the full device flow in the standalone profile and only the client credentials grant with its discovery document in the enterprise profile, so an AI agent can authenticate at Straza itself.

Authentication

The document declares 4 security schemes. adminBearer is 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 strazactl, the console and the self-service page pass. 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”, and 93 of the 131 operations declare it. 6 of the 131 operations declare approverBearer, 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”. sessionBearer is 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”, and 11 of the 131 operations declare it. 6 of the 131 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”. 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/connect, /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. 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 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.

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
GET /v1/snapshot Fetch the active signed policy snapshot (CBOR; ETag = snapshot id) sessionBearer
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

Request bodies in this section, one row per field.

Operation Field Type Required Meaning
POST /v1/enroll id_token string yes
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/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 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 401 Error
POST /v1/enroll 403 Error
POST /v1/enroll 503 ServiceUnavailable
POST /v1/checkin 200 CheckinResponse
POST /v1/checkin 400 Error
POST /v1/checkin 401 Error
POST /v1/checkin 403 Error
POST /v1/checkin 503 ServiceUnavailable
GET /v1/push 200 a text/event-stream body
GET /v1/push 401 Error
GET /v1/push 503 Error
GET /v1/snapshot 200 a application/cbor body
GET /v1/snapshot 304 an empty body
GET /v1/snapshot 401 Error
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 Error

Decisions and audit ingest

The server decision endpoint 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
POST /v1/audit/batch Ingest a batch of client-spooled audit events (straza drain) sessionBearer

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/audit/batch events list of object

Answers in this section, by status.

Operation Status Answer
POST /v1/decide 200 Decision
POST /v1/decide 400 Error
POST /v1/decide 401 Error
POST /v1/audit/batch 200 an object with accepted and refused
POST /v1/audit/batch 400 Error
POST /v1/audit/batch 401 Error
POST /v1/audit/batch 429 an object with error
POST /v1/audit/batch 503 an object with error

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 sessionBearer
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
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 sessionBearer
PATCH /v1/connect/{app} Allow or forbid the owner’s sponsored agents to run on this connection sessionBearer
DELETE /v1/connect/{app} Remove the acting user’s connection on one MCP server, OAuth or pasted token sessionBearer
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

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)
PATCH /v1/connect/{app} allow_agents boolean yes
PATCH /v1/connect/{app} user string Act for this user
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 Error
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 Error
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 Error
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 Error
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 Error
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 Error
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 its device token stops minting 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
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
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
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} 404 Error
DELETE /v1/admin/users/{id} 200 Status
DELETE /v1/admin/users/{id} 404 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}/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
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
DELETE /v1/admin/users/{id}/nhi-key 200 Status
DELETE /v1/admin/users/{id}/nhi-key 404 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.
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/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).
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/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, 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 and the acknowledgments of 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/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.
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
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 acknowledged, 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/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}/secrets role string Optional; absent stores the server’s own secret.
POST /v1/admin/apps/{id}/secrets 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/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
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/revoke 200 an object with revoked
POST /v1/admin/sessions/revoke 400 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
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 Mint a one-time approver enroll token (rendered as a QR) for a user 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 200 ApproverEnrollTokenResponse
POST /v1/admin/approvers/enroll-token 400 Error
POST /v1/admin/approvers/enroll-token 404 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.

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.
EnrollRequest id_token string Required.
EnrollRequest client_kind string The kind of client that enrols and holds the credential. One of kit or human.
EnrollRequest device object
EnrollResponse user_id string
EnrollResponse username string
EnrollResponse device_id string
EnrollResponse device_token string The long-lived enroll credential, bound to the user and device and usable only at /v1/checkin.
EnrollResponse device_token_expires_in integer
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 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 A renewed use=device credential, present only on the device-token lane when the presented credential is past half its lifetime.
CheckinResponse device_token_expires_in integer Seconds until the renewed device credential expires.
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.
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
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.
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 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
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
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
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
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.
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.
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.
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
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 acknowledged, 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.
ToolBinding id string
ToolBinding app string
ToolBinding role string
ToolBinding tools list of string
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)
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 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 and strazactl decide lanes.
ApprovalDecideBody reason string The decider’s own words on either verdict, at most 500 bytes of plain text.
ApproverEnrollTokenRequest Identify the user to mint an approver enroll token for (one of the two).
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.
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
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 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 acknowledge a typed risk.
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
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
DraftNeed object string Required.
DraftNeed standing string The standing that object needs from its publisher, in words. Required.

Search documentation

Search page titles, commands, and article text.

↑ ↓ Choose resultEnter OpenEsc Close