REST API

This document covers every HTTP endpoint exposed by the Yuzu server. Endpoints are grouped by functional area.

API Versioning

The Yuzu REST API uses path-based versioning. Understanding the distinction between versioned and legacy endpoints is important for building stable integrations.

Formal policy: the binding cross-surface versioning & deprecation policy — covering REST and MCP tools, the additive-vs-breaking test, the deprecation cycle (announcement channels + minimum window), and MCP tool naming on breaking changes — is docs/api-versioning-policy.md. This section is the REST summary.

Versioned API (/api/v1/)

All endpoints under the /api/v1/ prefix are the stable, versioned API. These endpoints:

• Use the standard JSON envelope (data, error, meta, pagination fields)
• Return "api_version": "v1" in the meta object of every response
• Follow consistent error handling with structured error objects
• Are the recommended integration target for all new automation and tooling
• Will maintain backward compatibility within the v1 version; breaking changes will increment to v2

Legacy API (/api/ without version prefix)

Endpoints under /api/ without the v1 prefix are legacy endpoints that predate the versioned API. These endpoints:

• Remain available for backward compatibility
• Do not use the standard v1 JSON envelope
• May return inconsistent error formats
• Are deprecated and will be removed per the deprecation cycle in docs/api-versioning-policy.md (a feature release, after the announced window)
• Should be migrated to their v1 equivalents where available

Migration Guidance

When writing new integrations, always use /api/v1/ endpoints. If you have existing scripts using legacy endpoints, plan to migrate them to v1 equivalents. The Legacy API Endpoints section below documents each legacy endpoint and notes where a v1 replacement exists.

Response Headers

Every API response (versioned and legacy) carries the standard Yuzu HTTP security response headers: Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, and Strict-Transport-Security (HTTPS only). These headers add roughly 700–900 bytes per response — JSON consumers should expect this overhead. See HTTP Security Response Headers for details, the full header list, and how to extend the CSP via --csp-extra-sources for browser dashboards that integrate with the Yuzu API.

Sec-Audit-Failed and the behavioural-PII audit posture

Routes that serve per-person behavioural / compliance PII (the dex.device.view, dex.device.app_perf.view, guardian.device.view, and dex.signal.view verbs) audit the access before serving. If that audit row cannot durably persist (audit DB locked/full, or an allocation failure), the gap is surfaced — never silently swallowed — but the posture differs by surface, by design:

• REST JSON endpoints fail closed: they return 503 + Sec-Audit-Failed: true and serve no data, so a machine integration (CMDB / ServiceNow / agentic worker) never records evidence-less PII as audited. Distinguish this transient, retryable 503 from a non-transient misconfiguration 503 by the presence of the Sec-Audit-Failed header.
• Dashboard HTMX fragments set-and-proceed: they set Sec-Audit-Failed: true but still render, so a transient audit hiccup never blanks a human operator’s lens.
• MCP tools set-and-proceed with an audit_persisted: false field in the result (absent on success) — JSON-RPC has no response-header channel.

This is intentional cross-surface behaviour: during an audit-store blip a browsing operator sees data while a wired REST integration receives 503. Alert on Sec-Audit-Failed: true (or audit_persisted: false) from any surface as a SOC 2 CC7.2 evidence-gap signal. (Mutating routes such as token/session revoke use the related audit_emitted body field — see those endpoints.)

A separate, narrower shape applies to ordinary mutation routes that audit a change after it already durably committed (not the behavioural-PII read routes above): POST /api/v1/software-packages, POST /api/v1/software-deployments, and its .../start, .../rollback, .../cancel actions. These always set-and-proceed — the mutation cannot be un-committed, so the response stays 2xx and only Sec-Audit-Failed: true signals a dropped audit row, with no audit_emitted/audit_persisted body field. The Integrations writes share the shape for their OUTCOME row: POST/DELETE /api/webhooks, POST/DELETE /api/v1/offload-targets, POST /api/directory/sync and PUT /api/directory/group-mappings write a result=attempted row first (a failure there is a 503 and nothing changes), and if the later outcome row cannot be stored they keep their 2xx and set Sec-Audit-Failed: true, which means the change WAS made and only the attempted row stands — do not retry the create. PUT and DELETE /api/v1/dex/score-policy share the shape too: a 200 that carries the header means the outcome row is missing and only the attempted row stands: for a PUT, or a DELETE that removed a policy, the change was applied and a retry with the old If-Match answers 409, while a DELETE of a policy that was never written changed nothing and may be repeated. Treat the header the same way as the behavioural-PII surfaces: a CC7.2 evidence-gap signal, not an error.

Table of Contents

• API Versioning
• Authentication
• JSON Envelope
• Pre-Auth Request Body Caps
• Numeric Query Parameters
• REST API v1 Endpoints
  • Current User
  • Devices
  • Hardware
  • Management Groups
  • API Tokens
  • Engine Principals
  • Sessions
  • Quarantine
  • Internal CA
  • KEK Rotation
  • Engine Principals
  • RBAC
  • Tags
  • Definitions
  • Product Packs
  • Response Templates
  • Audit Log
  • Access Reviews
  • Policy Fragments
  • Policies
  • Compliance
  • Runtime Configuration
  • Settings
  • Custom Properties
  • Webhooks
  • Offload Targets
  • Directory Sync
  • Enrollment
  • Network Discovery
  • Workflows
  • Workflows, Executions & Schedules — v1 read twins (#4030)
  • Command/Instruction Responses — v1 read twins (#2146 A2-R2)
  • OpenAPI Spec
  • Discovery (A2)
  • Inventory
  • Crypto
  • Result Sets
  • Forensics
  • Software Licensing (SLE)
  • Execution Statistics
  • Live-Query Bundles
  • Device Tokens
  • Pre-flight & Deploy
  • Software Deployment
  • License Management
  • Topology
  • Fleet Statistics
  • Plugin Configuration
  • File Retrieval
  • Uploads
  • Guaranteed State
• Legacy API Endpoints
  • Commands
  • Agents
  • Help
  • Instructions
  • Instruction Sets
  • Executions
  • Schedules
  • Approvals
  • Audit (Legacy)
  • Scope Engine
  • Data Export
  • Responses
  • Tags (Legacy)
  • Analytics and NVD
  • SSE Event Stream — includes GET /events, GET /sse/executions/{id}, and the agentic GET /api/v1/events
  • Dashboard Echo
• MCP (Model Context Protocol)
• Authentication Endpoints
• SCIM v2 Provisioning
• Health
• Metrics

Authentication

Every request must be authenticated using one of three methods:

Unauthenticated browser requests are redirected to /home (the sign-in landing page; /login forwards there). Unauthenticated API requests receive a 401 Unauthorized response.

API tokens are created via POST /api/v1/tokens and can be scoped to the creating user’s permissions. The raw token value is returned exactly once at creation time.

State-changing examples (POST, PUT, DELETE) that authenticate with a session cookie send a same-site Origin header (the scheme, host and port of the server you are calling); API-token requests do not need it.

Cookie-session writes. Every request other than GET, HEAD or OPTIONS that is authorised by the yuzu_session cookie must carry an Origin or Referer header naming this site (or an entry from --csrf-trusted-origin). Otherwise it is refused 403 cross-site request refused (the standard error envelope, with a remediation and no permission field) and audited as csrf.denied. One check, applied centrally, decides this after authentication and before step-up evaluation, challenge emission and route-handler effects, and before the request body is read. A request that presents a valid session cookie is treated as a cookie-session request even if it also carries a token; a request authenticated only by an API, MCP or engine token is not subject to this check, except on the routes that keep a copy of their own that is not token-exempt. Browsers send these headers on every write (the dashboard needs no change); a script that reuses a login cookie sends -H "Origin: https://yuzu.example.com" or uses an API token. Behind a reverse proxy, declare the public origin with its scheme (--csrf-trusted-origin https://yuzu.example.com; required if the proxy rewrites Host, and a plain-http:// origin for that host is then refused) and do not configure the proxy to inject or rewrite Origin or Referer. A server that terminates TLS itself requires an https:// Origin or Referer. The audit row’s result is denied, its target_id is the sanitised request method and path (the request path is truncated at 200 bytes) and its detail is fixed text plus reason=<token>; each refusal increments yuzu_server_csrf_denied_total{path_class,reason} (see Metrics). Cross-site checks described per route elsewhere in this reference are defence in depth: for a cookie-session caller the central check answers first and writes the csrf.denied row, so the per-route target_id values documented below are written only by a copy that is actually reached, which in practice means a token caller of a route whose copy is not token-exempt. Cookie-session requests that dispatch work, persist state or force a refresh of server state (the guarded reads) are held to the same rule whichever method they use, and the exact path, never a query flag, selects the gate. For them a Sec-Fetch-Site header that is present decides alone: exactly one header with value same-origin or none is admitted, any other value or a repeated header is refused with origin_mismatch, and Origin and Referer are not consulted. Only a request without Sec-Fetch-Site falls back to the Origin or Referer rule. So a script that reuses a login cookie for such a request either sends no Sec-Fetch-Site and a same-site Origin or Referer, or sends Sec-Fetch-Site once with value same-origin or none; or it uses an API token. Token callers are not gated. The audit row’s detail text for such a refusal is the fixed write wording (see CSRF protection).

Reserved headers — do not send. Five header names are reserved for future server-verifiable delegation and are rejected on every endpoint (sole exception: the four unauthenticated health-probe paths, which ignore them — see docs/auth-architecture.md) with 403 + the standard error envelope (ADR-1005): On-Behalf-Of, X-On-Behalf-Of, X-Yuzu-On-Behalf-Of, X-Yuzu-Delegated-Operator, X-Yuzu-Delegation-Artifact (case-insensitive). A client must never assert that it acts on another principal’s behalf via a header; see docs/auth-architecture.md (“On-behalf-of assertions rejected”) for rationale and the evolution path.

JSON Envelope

All REST API v1 responses use a standard JSON envelope.

Success (single object):

{
  "data": { ... },
  "meta": { "api_version": "v1" }
}

Success (list):

{
  "data": [ ... ],
  "pagination": {
    "total": 42,
    "start": 0,
    "page_size": 50
  },
  "meta": { "api_version": "v1" }
}

Error (A4 envelope):

{
  "error": {
    "code": 403,
    "message": "human-readable message",
    "correlation_id": "req-18f2a1c3d-2a",
    "retry_after_ms": null,
    "permission": "GuaranteedState:Read"
  },
  "meta": { "api_version": "v1" }
}

HTTP status codes follow standard conventions: 200 for success, 201 for resource creation, 400 for bad requests, 401 for unauthenticated, 403 for forbidden, 404 for not found, 503 for service unavailable. Every /api/v1/* error response uses the structured A4 error envelope (per docs/agentic-first-principle.md §A4), with the code field matching the HTTP status. The envelope’s fields:

Service-scoped API tokens and 503. A service-scoped API token is checked against the ITServiceOwner role’s permissions (its authority ceiling). On a route that can succeed on a retry, meaning one gated through the fleet-read gate or the scoped-permission gate, a token whose ceiling cannot be read (the permission store is degraded) receives 503 with retry_after_ms 5000 and no permission field: an outage is not a missing grant, and the request is still refused. On a route behind the plain permission gate a service-scoped token is refused by the default-deny allow-list whatever the ceiling read returns, so no retry hint is given there. A definitive deny, such as the role not holding the permission, is 403 on every gate.

The R2 A4 completion (2026-07) routed the RBAC/tier denial gates (require_admin, require_permission, and the service-scope denials in the auth layer) and the ~156 legacy error_json sites in rest_api_v1.cpp through this one envelope. The #1552 sweep PR-1 (2026-09) converted 8 more route files — auth_routes.cpp (including its MFA-flow branches), workflow_routes.cpp, webhook_routes.cpp, settings_routes.cpp, file_retrieval_routes.cpp, viz_routes.cpp, offload_routes.cpp, and sle_routes.cpp (audited, already compliant via its own local builder) — so it does not yet cover literally every path, but the remaining gap is now precisely enumerated rather than open-ended: 7 more route files (compliance_routes.cpp, discovery_routes.cpp, command_routes.cpp, dashboard_api_routes.cpp, notification_routes.cpp, schedule_routes.cpp, nvd_routes.cpp, tracked as #1552’s PR-2), roughly 86 hand-rolled sites still inline in server.cpp itself (not yet decomposed into a *_routes.cpp file), and the pre-routing chokepoint’s own “no session” 401 (server.cpp, {"error":{"code","message"},"meta"} with no correlation_id — every unauthenticated /api/v1/* request hits this before any route’s own A4 gate runs; tracked as #2003). Automation crossing surfaces should treat the enrichment fields as present-when-available until all three close.

Per-principal quota cap (PR 4.4, ADR-1005 class engine principals). REST traffic from an engine principal session (stored principal_kind engine or an engine_token authentication source, username engine:<slug>) is subject to a per-principal cap enforced at the server’s single pre-routing chokepoint — before the request reaches any route handler. Two independent dimensions are checked: an in-flight concurrency cap and a per-principal token-bucket rate cap (see docs/user-manual/engine-principals.md for the operator-facing tuning guide). Exhausting either dimension returns 429 with the standard A4 envelope plus an HTTP Retry-After header (whole seconds, rounded up from retry_after_ms):

{
  "error": {
    "code": 429,
    "message": "per-principal rate limit exceeded",
    "correlation_id": "req-18f2a1c3d-2a",
    "retry_after_ms": 150,
    "remediation": "retry after retry_after_ms; reduce request rate"
  },
  "meta": { "api_version": "v1" }
}

retry_after_ms is honest per dimension: a rate rejection carries the token bucket’s actual refill time, a concurrency rejection carries a fixed short backoff (250ms) since there is no natural “when will a slot free up” estimate. Streaming/SSE endpoints (GET /api/v1/events, GET /events, GET /sse/executions/{id}) take a concurrency slot held for the stream’s lifetime (released when the stream ends), plus the rate debit — the same two caps as any other engine request (UP-1; an earlier revision of this primitive released the slot early at routing hand-off and treated streaming as rate-only, which left an engine principal able to open an unbounded number of concurrent streams — that gap is closed). This gate applies only to engine-principal sessions; human, device-agent, and anonymous traffic is unaffected. It is enforced per server process — a multi-replica deployment’s effective ceiling is configured_cap x replica_count, not the configured cap alone (each replica enforces independently; not a fleet-wide cap). A quota rejection is metric-only (yuzu_server_principal_quota_exhausted_total{side,limit}, see docs/user-manual/metrics.md) — it does not write an audit row (see docs/user-manual/audit-log.md); every admitted request also increments the companion yuzu_server_principal_quota_admits_total{side} counter.

⚠ Breaking wire-shape change (upgrade note). Many of those legacy /api/v1 errors were previously emitted as {"error":"<string>"} (the single-arg error_json) or the older nested {"error":{"code","message"}}. They are now uniformly the nested A4 object above. A client that read error as a string (String(body.error), body.error.startsWith(...)) will break — error is always an object on these paths now. Migrate to body.error.code / body.error.message. See docs/user-manual/upgrading.md.

Numeric Query Parameters (#4644)

A numeric query parameter must be one complete base-10 integer, on the routes that read it this way, or the route answers 400 with the A4 message invalid numeric query parameter (the message names the parameter on several routes, for example window, the software inventory limit, the event stream’s since and the delivery-list limit; the wording otherwise varies by route family). They were read leniently, stopping at the first non-digit, so ?limit=100abc was read as 100, ?since=1e9 as 1 and ?since=junk was swallowed into the default (“from the beginning”): a malformed filter silently answered a different question than the one asked. Rejected now: trailing characters, hex and exponent forms, decimals, whitespace, a leading + and a value too large for its type (an empty value and an overflow were already refused on most of these routes). Zero padding (007) is accepted. Omitting a parameter still means its default, and each route’s existing clamping and sentinel values (for example limit clamped to a ceiling) are unchanged. The epoch bounds since/until (and from/to on the auth-sample export) are presence-tracked: omitting one leaves that side unbounded, since=0 is accepted as a harmless literal bound that matches exactly what omitting it matches, and until=0 (or to=0), like any negative bound, is 400: 0 is not an “unbounded” sentinel on the upper side, so a computed window that collapsed to 0 fails instead of silently returning everything.

Routes that parse strictly (the response routes are listed in Command/Instruction Responses and Responses below):

On the query-parameter routes in the table above, a parameter that is present but empty (?limit=) is malformed, not absent (GET /api/v1/audit limit included). Two exceptions. The software list and catalogue routes (GET /api/v1/inventory/software and /software/catalogue, and the three software fragments) share one parser in which an EMPTY limit= means the default; a non-empty malformed or overflowing limit is still refused (400 on the REST routes, a 200 inv-caveat note on the fragments). And the auth-sample export: a present but empty from or to on GET /api/v1/audit/auth-sample is accepted as unbounded on that side. The admin forms are different: an EMPTY form field means that field’s default.

Not covered by this change, and still lenient (the list is not exhaustive): the n retry-attempt counter on the live-snapshot poll fragments (the deployment, device, hardware, DEX, pre-flight and Echo process-tree polls), which is clamped to a fixed range per poll (1 to 100000 on the deployment and pre-flight polls, at most 50 on the others); and values that are parsed from stored rows, agent output or server configuration rather than from a request. Numeric path segments matched by a (\d+) pattern (/api/notifications/{id}/read, /dismiss and the webhook routes) answer 404 for an id that does not fit a signed 64-bit integer (the auto-approve rule index answers 200 with an audited denied row and changes nothing); they used to throw and answer 500.

Pre-Auth Request Body Caps (#2407)

Every request is checked against a per-route body-size cap before authentication runs and before the body is read. A single pre-routing chokepoint (server.cpp) resolves the caller’s (method, path) against the policy table in body_cap_policy.hpp and rejects an oversized or unmeasurable body without buffering it. The four health-probe paths (/livez, /readyz, /health, /api/health) are NOT exempt from this gate. The cap is a single lambda, enforce_pre_auth_body_cap in server.cpp’s pre-routing handler, invoked from exactly two sites: once INSIDE the probe branch, before its early return, and once after the on-behalf-of guard and the rate limiter for every other route. One definition, two call sites; the probes cannot drift out of coverage without deleting a call. The plain-HTTP redirect listener (#5906) also serves these four paths, but it admits no body at all: a probe declaring Content-Length or Transfer-Encoding is redirected before any read (is_plaintext_probe_request, health_routes.hpp), so no second cap table exists. tests/unit/server/test_body_cap_policy.cpp’s “POST /health … is rejected (D3)” case exercises that DECISION on a real socket, but against a test server that reproduces the gate rather than invoking the production one, so it does not pin the wiring itself. The probe-branch call is pinned separately by the source-text wiring case in tests/unit/server/test_health_routes.cpp, which fails if that call is deleted or moved out of the probe branch. The non-probe call site (after the on-behalf-of guard and the rate limiter) is not pinned: deleting it would leave the suite green, so treat that call as verified by review, not by test, until that gap is closed. Before this fix the probes’ early-return sat above the cap entirely, making them the server’s last unauthenticated 100 MiB buffer; closing that was the point. The probes remain exempt from the on-behalf-of guard that runs further below (a header-stamping proxy or orchestrator must not be able to crash-loop the server by tripping it on its own liveness check). That exemption is unchanged; only the body cap now also reaches them. /livez and /readyz are also exempt from the rate limiter. /health and /api/health requests that carry a credential header are rate limited per source address in a bucket of their own, checked before the body cap; requests with no credential header are not charged (see the /health section below). Three status codes:

All three responses use the standard A4 error envelope with a remediation hint (no permission field — the request is rejected before any principal is resolved) — except the scim class, which publishes SCIM’s own RFC 7644 §3.12 error shape (schemas/status/detail) on application/scim+json instead of the generic envelope (scim::error(), scim_json.hpp:192; wired into all three status codes above in server.cpp’s pre-routing handler). This gate is separate from, and runs before, any route-local body check a handler may also carry (e.g. the SCIM/response-template 64 KiB checks below) — those still exist for defense-in-depth if a future edit widens this table’s entry, but on the current table this pre-routing gate rejects first. This is not purely a timing change for every affected class. For most (response templates, CA import), an earlier rejection at the same byte count is the entire effect. SCIM is no longer an exception to that either (fixed as part of this change, D7): the pre-routing rejection’s SCIM shape matches the wording of the handler’s own (now-superseded, and unreachable — the pre-routing cap and the handler check the identical 64 KiB threshold, so the pre-routing gate always wins first) 413 check exactly, and extends the same shape to the 411/415 cases the handler-level check never covered.

Post-Read Backstop (#2407)

The pre-routing gate above is what stops an oversized body from being buffered at all — but it can only act on a declared size. Its structural limit, recorded in body_cap_policy.hpp’s KNOWN LIMITATION paragraph: on the 28 of 32 classes (distinct path_class labels, the catch-all default included) below that don’t set requires_measurable, a genuine chunked (or otherwise undeclared) body is not size-checked by the pre-routing gate at all — it is admitted, up to httplib’s own 100 MiB backstop, without that table’s cap being consulted.

A second stage, wired at httplib’s Server::set_pre_request_handler in server.cpp, closes that gap from the other side. It runs inside httplib’s dispatch_request — after read_content has consumed the body off the socket into req.body, and after the route has matched, but before the route’s own handler runs. At that point the body’s actual size is known, so this stage resolves the SAME kBodyCapTable/resolve_body_cap the pre-routing gate uses (no forked table) and, if the now-fully-read body is over the class’s cap, refuses with the same 413 A4/SCIM envelope shape and the same 1-in-100 per-reason log throttle as the pre-routing gate (tagged [#2407 post-read] in the journal rather than [#2407]). The rejection reason is a new value, over_cap_post_read, on yuzu_body_cap_rejected_total{path_class,reason} — pre-seeded at 0 for every class, unconditionally, unlike unmeasurable; see docs/user-manual/metrics.md’s yuzu_body_cap_rejected_total row for the full description.

What an operator observes. A chunked (or otherwise undeclared) body that exceeds its route class’s cap is now refused — where it previously reached the route handler uncapped, bounded only by httplib’s 100 MiB backstop. That is the change: the 28-of-32-class gap the pre-routing gate leaves open is now closed for a body that turns out, once read, to be over cap.

The two stages are mutually exclusive per request, not stacked. httplib’s routing() returns as soon as the pre-routing handler answers Handled, so it never calls dispatch_request for a request that gate already refused — a measurable over-cap body (a declared Content-Length above the cap) is still rejected by the pre-routing gate, before anything is buffered, exactly as before this stage existed. Do not describe this as “the cap now runs twice” — in practice over_cap_post_read fires almost exclusively for the chunked/unmeasurable case the pre-routing gate deliberately admits.

Limitations — read before relying on this as complete coverage:

• Multipart is not covered. httplib only appends to req.body on the non-multipart branch of read_content (httplib.h:11002 swaps the receiver for the multipart parser once it detects a multipart body) — so req.body.size() reads 0 for ANY multipart request, regardless of the real bytes read off the wire. No multipart class is covered — stated as a rule rather than a list, because an earlier draft of this text enumerated a single class and was wrong: /api/settings/updates/upload (ota_upload) and /api/settings/cert-upload (no table entry, so the 4 MiB default) are multipart too. Their chunked-body gap is not closed by this stage. This is not a regression introduced here — it is exactly as exposed as it was before this stage existed — but do not read the post-read stage as having closed coverage for every class.
• The stage only runs when a route matched. set_pre_request_handler is invoked from httplib’s dispatch_request, which only runs once routing has matched a route — a request to a path that 404s never reaches this handler at all. It is a backstop behind the pre-routing gate for matched routes, not a second universal pre-auth gate.

Why not one global cap? httplib’s own Server::set_payload_max_length is a single server-wide knob shared by every route on the same listener, including the ~70 MiB live-query bundle route and the OTA agent-binary upload — a single small value would break those outright, and a single large value (httplib’s 100 MiB default) leaves every small JSON/form route able to buffer up to 100 MiB from an unauthenticated caller. The table below exists so each route class gets a cap sized to what it actually needs.

Per-class caps

Derived directly from server/core/src/body_cap_policy.hpp’s kBodyCapTable (longest matching {method, path prefix} wins; do not hand-copy these numbers elsewhere — that header is the source of truth):

† = a reasoned margin over a real, cited handler-level check — the pre-routing gate sees the RAW body while the handler checks a DECODED/PARSED value (form-decoded, JSON-unescaped, or multipart-extracted), so the two numbers are never expected to match exactly. Reasoned headroom, not a measured worst case; getting the margin wrong rejects legitimate traffic (the echo_dashboard_sql/echo_result_set_sql history above is a shipped example). ‡ = a generous, explicit, judgment-call bound because no aggregate size contract exists for that class yet, reasoned against that class’s OWN realistic scale rather than copy-pasted from a sibling — not a fixed multiple below httplib’s 100 MiB backstop: it ranges from ~12.5× for the 8 MiB nvd_match entry (just over one order of magnitude) down to 6.25× for the five 16 MiB entries (under one order of magnitude) — none of the ‡ entries reach two orders of magnitude. Do not read either footnote as license to invent a number for a different route — see the header block of body_cap_policy.hpp.

Counting by table ROW (one BodyCapEntry struct in kBodyCapTable = one row): 8 rows carry † (plugin_config, ca_import_chain_dashboard, plugin_trust_bundle, echo_dashboard_sql, echo_result_set_sql, and all three instruction_yaml rows) and 6 rows carry ‡ (nvd_match, both guardian_rule_authoring rows, workflow_yaml, product_pack_yaml, instruction_import) — 14 rows total, out of 36 rows in the table overall (A2 added rbac_role_assignment, A1 rbac_enforcement, the policy-generation raise guardian_policy_generation, #5342 users, and then crypto, config and dex_score_policy, all unmarked — an exact reasoned-from-real-shape bound, not a measured mirror or a judgment call against an arbitrary-content class). Counting by CLASS (path_class; several classes span multiple rows) that collapses to 6 † classes and 5 ‡ classes — 11 classes total, out of 32 classes overall (the catch-all default included). Every other row/class mirrors a cited, decoded-equals-raw byte count exactly (this now includes upload_session, added alongside plugin_config in this table — an exact protocol-constant mirror, not a reasoned margin, so it carries neither footnote). A third, unmarked category (ota_upload, json_to_csv_export) is pinned at httplib’s own 100 MiB backstop as an explicit, reviewed decision rather than squeezed or given a judgment-call number — neither is “reasoned” in the † /‡ sense, since there is no smaller number to reason toward.

Raising a cap. Edit the table in body_cap_policy.hpp (with review) and update this table to match — never reach for Server::set_payload_max_length, which is global across every route on the listener (see “Why not one global cap?” above). See also docs/user-manual/server-admin.md’s upgrade note for this change and docs/user-manual/metrics.md’s yuzu_body_cap_rejected_total row for observing rejections.

REST API v1 Endpoints

All endpoints are under the /api/v1/ prefix.

Current User

GET /api/v1/me

Returns the authenticated caller’s identity, legacy role and session context (not an authority summary: see role below). The MCP twin is get_me.

Permission: Authenticated session (no specific RBAC permission required). The route is session-only self-description and writes no audit row. A service-scoped token may call it and describe itself; the MCP twin get_me refuses service-scoped tokens (a documented asymmetry, tracked in #6432).

Response:

{
  "data": {
    "username": "alice",
    "display_name": "Alice",
    "role": "user",
    "principal_kind": "human",
    "auth_source": "local",
    "mcp_tier": "",
    "scope_service": "",
    "rbac_enabled": false,
    "rbac_role": "Viewer",
    "rbac_roles": [],
    "rbac_roles_resolved": true,
    "effective_role": "user",
    "elevated": false,
    "can_access_settings": false
  },
  "meta": { "api_version": "v1" }
}

While a just-in-time elevation is active, effective_role is admin, elevated is true, elevated_until (ISO-8601 UTC) is added and can_access_settings is true for a local session.

Keys appear in the order shown; do not depend on it. The response is sent with Cache-Control: no-store, private. During a rolling upgrade an older replica omits the newer keys (principal_kind, auth_source, mcp_tier, scope_service, rbac_roles, rbac_roles_resolved and the session fields); clients should treat a missing can_access_settings as false. GET /api/me returns the same keys without the data envelope.

Devices

The fleet device list and single-device identity read (#4033, #2146 API-parity Batch A) — the REST twins of the /devices dashboard’s list_agents/get_agent_details-shaped MCP tools. Both routes are gated via AuthRoutes::require_fleet_read (the admit-then-filter chokepoint), not a bare permission check — a management-group-confined operator and a correctly-confined service-scoped token both see a real, filtered subset of the fleet rather than either the whole fleet or an outright denial. Neither route is audited on a successful read: device identity (hostname/OS/arch/version) is machine metadata, not behavioural PII — matching the /fragments/devices/list, /fragments/device/page, and /fragments/device/info dashboard fragments’ own unaudited posture.

GET /api/v1/devices

List every device visible to the caller.

Permission: Infrastructure:Read, via require_fleet_read.

Response:

{
  "data": {
    "devices": [
      {
        "agent_id": "a1b2c3d4e5f6",
        "hostname": "web-01",
        "os": "linux",
        "arch": "x86_64",
        "agent_version": "0.13.1"
      }
    ],
    "count": 1,
    "devices_omitted": 0
  },
  "pagination": { "total": 1, "start": 0, "page_size": 50 },
  "meta": { "api_version": "v1" }
}

devices_omitted counts agents dropped by the caller’s management-group/service-scope confinement (0 when unfiltered or nothing was dropped) — the same “out of my scope” vs. “not present” signal GET /api/v1/inventory/software’s devices_omitted field used to carry (on that route it now counts only devices hidden by the post-filter and is 0 under SQL push-down — see its section).

GET /api/v1/devices/{id}

Fetch one device’s identity.

Permission: Infrastructure:Read, via require_fleet_read.

Response:

{
  "data": {
    "agent_id": "a1b2c3d4e5f6",
    "hostname": "web-01",
    "os": "linux",
    "arch": "x86_64",
    "agent_version": "0.13.1",
    "tags": [
      { "key": "environment", "value": "production", "source": "server" }
    ]
  },
  "meta": { "api_version": "v1" }
}

tags is always present ([] when the device has no tags, or in the never-hit-in-production case of an unwired TagStore). A device outside the caller’s fleet-read scope returns the SAME 404 as a genuinely nonexistent agent_id — an out-of-scope match is never distinguishable from “does not exist” in the response body (matches the pre-existing MCP get_agent_details tool’s existence-oracle closure exactly).

Hardware

The Hardware CI list and single-device CI record: the two read routes of the OpenAPI tag Hardware, followed by short entries for the on-demand syncs POST /api/v1/hardware/{id}/sync (one device) and POST /api/v1/hardware/sync (a scope or the fleet). Both read routes are audited on a served read, and with result=failure when the device roster could not be read.

GET /api/v1/hardware

The Hardware list: the device roster (identity fields as for /devices) plus device-CI columns, a per-page DEX score, claimed IPs and tags.

Permission: Inventory:Read, via require_fleet_read (admit-then-filter). MCP twin: list_hardware_ci (strict argument typing and a lowercase-only os/status/sort/dir; see docs/user-manual/mcp.md).

Query parameters: q, os, status, sort, dir, tag, offset, limit. An unrecognised sort, os or status token, or an invalid tag key, is a 400; any dir other than desc sorts ascending.

Response: { "data": { "devices": [...], "count", "total_matching", "devices_omitted", "ci_degraded", "tags_degraded", "kpis", "query" }, "pagination", "meta" }.

Audit: inventory.devices; result=success on a served page, result=failure (detail hardware roster read failed) when the roster could not be read. A persist failure on the success row fails the request closed with 503.

GET /api/v1/hardware/{id}

One device’s CI record: identity, device-CI blob, installed software and tags, each read independently so a degraded read is distinguishable from an absent one.

Permission: Inventory:Read, via require_fleet_read. An id outside the caller’s fleet-read scope returns the same 404 as a nonexistent id. MCP twin: get_hardware_ci (see docs/user-manual/mcp.md).

Response: { "data": { "agent_id", "hostname", "os", "online", "last_seen", "identity_state", "ci", "ci_state", "software", "tags", ... }, "meta" }. identity_state is found, degraded (the device roster could not be read) or absent; ci_state is found, absent or degraded. agent_id, hostname, os and last_seen are null (and online is false) unless identity_state is found.

Audit: inventory.device.ci; result=failure when the roster read failed (detail state=roster unreadable on the 503, state=<...> identity=roster unreadable on a served 200).

POST /api/v1/hardware/sync

Requests an on-demand software-inventory sync for a device, a scope or the whole fleet (the Software page’s Sync now). Permission: Execution:Execute, checked as a global grant: an operator whose Execution:Execute is limited to management groups is refused with 403 for every scope kind. The route also confines its targets to the caller’s own Execution:Execute visible set and refuses the whole fleet ("scope":"__all__") unless that set is unfiltered (403); with a global grant neither changes the outcome today, and both are defence in depth for when the gate becomes scope-aware. The body names the targets with exactly one of scope (__all__, group:<id> or a device id, up to 256 bytes) or scope_expression (a scope expression, up to 1,024 bytes); source may only be installed_software.

A run reaches agents attached to this server process only. skipped_offline counts the devices this server process did not reach that are not too old: it has no live session for them (a disconnected device, or one attached to another server), or the send was refused by the live stream (for example a gateway-attached agent whose gateway lacks the dispatch capability). Which devices are candidates depends on the scope: a group or a single named device lists its disconnected members too, but an __all__ or scope-expression run lists only this server’s own sessions plus the shared presence record, so a device that is offline everywhere is never counted, and if the presence read is degraded an __all__ run lists fewer devices (those attached to other servers are not listed) while a scope-expression run is refused with 503 (the scope could not be evaluated) and sends nothing. requested and skipped_offline therefore describe what this server could reach; they are not a census of the fleet. Agents below 0.13.1 are skipped and counted in skipped_version. At most 500 devices are reached per request (413). A group, scope or fleet run is limited to one per operator per 60 seconds (429, Retry-After) (an attempt refused for exceeding 500 devices, or with no live target, counts as a run; a send every device refused does not) and one at a time (409; the slot is a 120 s lease a later run can take over, but only while fewer than three stalled runs are alive, after which 409 persists until one of them unwinds or the server restarts), both per server process rather than cluster-wide (with several active servers each allows its own run, still bounded by the 500-device cap); a single named device is exempt. The 202 body carries counts only (requested, agents_reached, skipped_offline, skipped_version) plus command_id, never device ids. A server that is missing a required component answers 500 and writes a result=failure audit row. A browser (session-cookie) request must carry an Origin or Referer naming this site, otherwise it is refused with 403 and a csrf.denied audit row; API-token and MCP-token callers are exempt. Who is reached is decided at send time by the dispatch_confined_arms system-reserved arm, which intersects the target list with the caller’s own Execution:Execute visible set. The MCP tool sync_hardware_software is the twin of this route and shares its cooldown and its single in-flight run. The request, statuses and bounds are in the OpenAPI document. Audit: inventory.sync.request, written before dispatch (see audit-log.md).

POST /api/v1/hardware/{id}/sync

Requests an on-demand agent sync for one device. Permission: Execution:Execute scoped to the device. A browser (session-cookie) request must carry an Origin or Referer naming this site (403 otherwise; token callers are exempt). The body, the 202 and the 409 are described in the OpenAPI document. A device id longer than 256 bytes or containing a byte below 0x20 is a 400, answered before the permission check and with no audit row (the same id rule as GET /api/v1/hardware/{id}, including the registration note there). Audit: inventory.sync.request (see audit-log.md).

Management Groups

Management groups organize agents into a hierarchy for access scoping. Groups can be static (manually assigned members) or dynamic (membership determined by a scope expression evaluated against agent tags and properties).

GET /api/v1/management-groups

List all management groups.

Permission: ManagementGroup:Read

Response:

{
  "data": [
    {
      "id": "a1b2c3d4e5f6",
      "name": "EU Production Servers",
      "description": "All production endpoints in EU datacenters",
      "parent_id": "",
      "membership_type": "static",
      "scope_expression": "",
      "created_by": "admin",
      "created_at": 1710849600,
      "updated_at": 1710849600
    },
    {
      "id": "f6e5d4c3b2a1",
      "name": "Windows Desktops",
      "description": "Dynamic group for all Windows endpoints",
      "parent_id": "",
      "membership_type": "dynamic",
      "scope_expression": "os = 'windows'",
      "created_by": "admin",
      "created_at": 1710850000,
      "updated_at": 1710850000
    }
  ],
  "pagination": { "total": 2, "start": 0, "page_size": 50 },
  "meta": { "api_version": "v1" }
}

POST /api/v1/management-groups

Create a new management group.

Permission: ManagementGroup:Write

Request body:

{
  "name": "EU Production Servers",
  "description": "All production endpoints in EU datacenters",
  "parent_id": "",
  "membership_type": "static",
  "scope_expression": ""
}

Response (201):

{
  "data": { "id": "a1b2c3d4e5f6" },
  "meta": { "api_version": "v1" }
}

GET /api/v1/management-groups/{id}

Get a single group’s details including its current members.

Permission: ManagementGroup:Read

Response:

{
  "data": {
    "id": "a1b2c3d4e5f6",
    "name": "EU Production Servers",
    "description": "All production endpoints in EU datacenters",
    "parent_id": "",
    "membership_type": "static",
    "scope_expression": "",
    "created_by": "admin",
    "created_at": 1710849600,
    "updated_at": 1710849600,
    "members": [
      {
        "agent_id": "agent-eu-prod-01",
        "source": "static",
        "added_at": 1710850000
      },
      {
        "agent_id": "agent-eu-prod-02",
        "source": "static",
        "added_at": 1710850100
      }
    ]
  },
  "meta": { "api_version": "v1" }
}

The group row is read through ManagementGroupStore::get_group_checked and its members through get_members_checked (#1762). A store-not-open / pool-acquire-timeout / query-error degrade on EITHER read returns 503 (A4 envelope, retry_after_ms: 2000) rather than a 404 or an authoritative empty members: []; 404 now always means the group does not exist. The MCP twin get_management_group fails the same way.

PUT /api/v1/management-groups/{id}

Update a management group. Only the fields provided in the request body are changed; omitted fields retain their current values.

Permission: ManagementGroup:Write

Request body:

{
  "name": "EU Production Servers (Renamed)",
  "description": "Updated description",
  "parent_id": "f6e5d4c3b2a1",
  "membership_type": "dynamic",
  "scope_expression": "os = 'linux' AND tag:environment = 'production'"
}

Validation rules:

• The root group (000000000000, “All Devices”) cannot be re-parented. Attempting to set parent_id on the root group returns 400.
• Self-parent: A group cannot be set as its own parent. Returns 400.
• Cycle detection: The new parent must not be a descendant of the group being updated. Moving a group under one of its own children would create a circular hierarchy and returns 400.
• Depth limit: Re-parenting must not exceed the maximum hierarchy depth of 5 levels. Returns 400 if exceeded.

All validation runs at the ManagementGroupStore layer as well as the REST handler, so non-REST administrative callers cannot bypass cycle or depth checks.

Response:

{
  "data": { "updated": true },
  "meta": { "api_version": "v1" }
}

Error (400) — cycle detected:

{
  "error": "re-parenting would create a cycle",
  "meta": { "api_version": "v1" }
}

Error (400) — self-parent:

{
  "error": "group cannot be its own parent",
  "meta": { "api_version": "v1" }
}

Error (400) — depth exceeded:

{
  "error": "maximum hierarchy depth (5) exceeded",
  "meta": { "api_version": "v1" }
}

Error (400) — root group re-parent:

{
  "error": "cannot re-parent root group",
  "meta": { "api_version": "v1" }
}

Error (503) — store unavailable:

Cycle and depth validation walk the hierarchy via recursive ancestor/descendant reads against the management_group_store Postgres substrate (ADR-0042). If those reads degrade (store not open, connection-pool acquire timeout, or a query error) the re-parent cannot be validated safely, so it fails closed with 503 rather than risk applying an unvalidated move — the caller did nothing wrong, the store did. This is distinct from the 400 validation errors above (a genuinely bad request); retry a 503 once the substrate recovers.

{
  "error": "management group store unavailable",
  "meta": { "api_version": "v1" }
}

DELETE /api/v1/management-groups/{id}

Delete a management group. The root group (“All Devices”, ID 000000000000) cannot be deleted and returns 403 Forbidden. Deleting a group cascade-deletes all child groups, their membership records, and their role assignments.

Permission: ManagementGroup:Delete

Response:

{
  "data": { "deleted": true },
  "meta": { "api_version": "v1" }
}

Error (403) — root group:

{
  "error": "cannot delete root group",
  "meta": { "api_version": "v1" }
}

POST /api/v1/management-groups/{id}/members

Add an agent to a static management group.

Permission: ManagementGroup:Write

Request body:

{
  "agent_id": "agent-eu-prod-03"
}

Response (201):

{
  "data": { "added": true },
  "meta": { "api_version": "v1" }
}

DELETE /api/v1/management-groups/{id}/members/{agent_id}

Remove an agent from a management group.

Permission: ManagementGroup:Write

Response:

{
  "data": { "removed": true },
  "meta": { "api_version": "v1" }
}

GET /api/v1/management-groups/{id}/roles

List role assignments scoped to this management group.

Permission: ManagementGroup:Read. This response is authorization topology (who holds what role), so the fleet-wide arm actually authorizing it is the floored UserManagement:Read (#2376), not ManagementGroup:Read itself — see the authorization topology floor. A caller lacking that also succeeds if they are ITServiceOwner of this specific group (a scoped fallback, not the fleet-wide grant) — but a service-scoped API token cannot use that fallback (guardian-confinement-2298 PR 3): the fallback checks group membership only, never the token’s own service-tag scope, and a service-scoped token is denied outright rather than risk it reaching a group outside its own service.

Response:

{
  "data": [
    {
      "group_id": "a1b2c3d4e5f6",
      "principal_type": "user",
      "principal_id": "jane.ops",
      "role_name": "Operator"
    },
    {
      "group_id": "a1b2c3d4e5f6",
      "principal_type": "user",
      "principal_id": "bob.viewer",
      "role_name": "Viewer"
    }
  ],
  "meta": { "api_version": "v1" }
}

POST /api/v1/management-groups/{id}/roles

Assign a role to a principal within this management group. Only the Operator and Viewer roles can be delegated. The caller must be a global Administrator or hold the ITServiceOwner role on this group.

Permission: Global ManagementGroup:Write or ITServiceOwner on this group. A service-scoped API token is denied outright, even one whose minter holds ITServiceOwner on this exact group (guardian-confinement-2298 PR 3) — the group-scoped fallback checks membership only, never the token’s own service-tag scope.

Request body:

{
  "principal_type": "user",
  "principal_id": "jane.ops",
  "role_name": "Operator"
}

Response (201):

{
  "data": { "assigned": true },
  "meta": { "api_version": "v1" }
}

Error (403) — non-delegatable role:

{
  "error": "only Operator and Viewer roles can be delegated",
  "meta": { "api_version": "v1" }
}

DELETE /api/v1/management-groups/{id}/roles

Remove a role assignment from this management group.

Permission: Global ManagementGroup:Write or ITServiceOwner on this group. Same service-scoped-token denial as POST above.

Request body:

{
  "principal_type": "user",
  "principal_id": "jane.ops",
  "role_name": "Operator"
}

Response:

{
  "data": { "unassigned": true },
  "meta": { "api_version": "v1" }
}

GET /api/v1/management-groups/agent-count-preview

Preview the number of currently-visible agents that would match a would-be management group’s filter criteria, before creating it (#4033, #2146 API-parity Batch A). REST/MCP/dashboard-fragment twin of /fragments/create-group-form’s own live count. This route and its MCP twin call the same shared builder (group_agent_count_preview.hpp), so those two cannot drift from each other; the dashboard fragment keeps its own separate, behaviourally-equivalent inline implementation (DashboardRoutes::parse_filters), except that for an over-bound filter it hides the count and shows a static sentence (#5623). For a filter within the bound, the number it shows and this route’s agent_count are expected to agree today, but are not structurally guaranteed to. MCP twin: preview_management_group_agent_count.

Permission: ManagementGroup:Write — matching the fragment’s own gate exactly (only an operator who could create the group may preview it), not ManagementGroup:Read, even though this route performs no mutation.

Query parameters:

An empty filter set (no recognised filter keys supplied) returns a genuine 0 — no scoped count to report, and no store read is made.

Response:

{
  "data": { "agent_count": 42, "unindexed_filter_keys": [] },
  "meta": { "api_version": "v1" }
}

unindexed_filter_keys is always present (additive, #5623): the mangled keys, in a stable order (sorted by key) and without duplicates, of any filter whose value is longer than 2048 bytes (measured as ingest stores it, so a NUL or invalid UTF-8 byte counts as 3), and an empty array when none is. Such a value is not indexed in newly stored responses, so when the array is not empty agent_count can be 0 or an undercount. The array names keys only, never the values. agent_count and every status code are unchanged, including the 503 when the response store is degraded.

Forensics-tier rows (#4990). Rows written by a Forensics-tier plugin are counted only for a caller who also holds Forensics:Read (see “Forensics-tier rows” under Command/Instruction Responses). For any other caller they are absent from the count with no marker, so a low or zero agent_count does not prove that no matching data exists. If the caller’s Forensics authority cannot be determined the route answers a retryable 503 with retry_after_ms instead of a partial count. The route writes no audit row of its own.

API Tokens

API tokens provide non-interactive authentication for scripts and automation. Tokens are scoped to the creating user’s permissions. The raw token string is returned exactly once at creation time and cannot be retrieved afterward.

Storage failure: if the server’s token store database failed to open at startup (bad data directory, permissions), all three token endpoints return 503 with message service unavailable rather than 404 or an empty list, so automation can distinguish a server-side outage from a missing token. Note that Bearer-token authentication against an unavailable token store deliberately fails closed with 401, not 503 — an automation client seeing unexpected 401s during an outage should check server health (/readyz reports api_token_store) before rotating credentials.

GET /api/v1/tokens

List the current user’s API tokens. Raw token values are never returned.

Permission: ApiToken:Read

Response:

{
  "data": [
    {
      "token_id": "a1b2c3d4",
      "name": "CI Pipeline Token",
      "principal_id": "admin",
      "created_at": 1710849600,
      "expires_at": 1742385600,
      "last_used_at": 1710936000,
      "revoked": false
    }
  ],
  "pagination": { "total": 1, "start": 0, "page_size": 50 },
  "meta": { "api_version": "v1" }
}

Rotation fields (P2 #11): rotation_group, supersedes_token_id, overlap_expires_at, and confirmed_at appear on an item only while a rotation is (or was) in flight for that token — a token that has never been rotated omits all four. rotation_group is present on both the predecessor and the successor row of an in-flight pair (it links them); supersedes_token_id is present only on the successor and equals the predecessor’s token_id; overlap_expires_at is present on the predecessor while the overlap window is open (the epoch it is auto-revoked); confirmed_at is present once an explicit credentials/confirm-style confirmation (below) has closed the rotation. A caller that only checks for the absence of these fields on a fresh token needs no code change — they were not serialized before P2 #11 either.

POST /api/v1/tokens

Create a new API token. The raw token is returned in the response and is never shown again. Store it immediately.

Permission: ApiToken:Write

Request body:

{
  "name": "CI Pipeline Token",
  "expires_at": 1794355200,
  "mcp_tier": "readonly"
}

The expires_at above is a placeholder epoch: with mcp_tier set it must be in the future and at most 90 days out, so compute it at call time, for example $(date -d '+30 days' +%s) (macOS: date -v+30d +%s).

mcp_tier is honored at mint time (a value outside readonly/operator/supervised is rejected). A tiered (mcp_tier set) or service-scoped token also requires a valid expires_at; the 90-day cap applies to tiered (mcp_tier set) tokens only, so a service-scoped token without a tier may expire later than that. Setting scope_service requires RBAC to be enabled and either a global ManagementGroup:Write grant or ITServiceOwner on the "Service: <scope_service>" management group — see Service-Scoped Tokens.

Validation errors (400):

Response (201):

{
  "data": {
    "token": "yzt_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678",
    "name": "CI Pipeline Token"
  },
  "meta": { "api_version": "v1" }
}

Warning: Copy the token value immediately. It cannot be retrieved after this response.

The response is sent Cache-Control: no-store, no-cache, must-revalidate and Pragma: no-cache, because the body carries a raw one-time secret (the same headers as the rotate and engine mint routes).

DELETE /api/v1/tokens/{token_id}

Revoke an API token. The token becomes immediately unusable.

Permission: ApiToken:Delete

Ownership constraint: A caller with ApiToken:Delete may only revoke tokens they created. The global admin role, or a session with an active just-in-time admin elevation, is the only bypass and may revoke any token. Attempting to revoke another user’s token returns 404 token not found — identical to the response for a token that does not exist — so the endpoint cannot be used as an enumeration oracle by a non-owner with ApiToken:Delete. Denied attempts are recorded in the audit log with action=api_token.revoke, result=denied, and detail=owner=<real owner> so forensics can distinguish a probe from a legitimate self-revoke.

The same ownership constraint applies to the HTMX dashboard path DELETE /api/settings/api-tokens/{token_id}. The same bypass applies there: the global admin role or a just-in-time-elevated session may revoke any token.

Response:

{
  "data": { "revoked": true },
  "meta": { "api_version": "v1" }
}

Error (404) — token not found or not owned by caller:

{
  "error": {
    "code": 404,
    "message": "token not found"
  },
  "meta": { "api_version": "v1" }
}

POST /api/v1/tokens/{token_id}/rotate

Self-service overlap-pair rotation of a human-owned API token (P2 #11, SOC 2 CC6.3): mints a successor token while the existing (predecessor) token stays valid for an overlap window — at most two active tokens in the rotation group during the overlap. {token_id} in the path is the predecessor’s id. The raw successor secret is returned exactly once per reveal (see the grace-window re-serve note below), the same discipline the engine-principal credentials/rotate route above uses. MFA step-up runs on every call to this route, including an idempotent re-serve.

Permission: ApiToken:Rotate — a DISTINCT operation from ApiToken:Write (round-4 security finding): ApiToken:Write also gates POST /api/v1/tokens (mint) and its settings twin, so a shared op would let an operator-tier MCP token mint a brand-new, caller-chosen-tier token — a privilege escalation, not a parity fix. See mcp_policy.hpp’s tier_allows() operator-tier comment for the full analysis. Under the default RBAC-off configuration, this permission is reachable by any non-admin owner (#2963 legacy self-service allowlist) — ownership, not role, is what actually gates who can succeed; see Rotating a Token for the operator-facing explanation.

Ownership constraint — self-service only, no admin bypass: unlike DELETE /api/v1/tokens/{token_id} above, there is no admin override here. A human token’s raw successor secret authenticates as that user, so an admin rotating or confirming someone else’s token would hand out (or complete the cutover of) a credential that impersonates them — identity takeover, not a permission gap an admin role could legitimately cross. An admin who needs to act on another user’s token still has DELETE (revoke). Attempting to rotate a token you do not own returns 404 token not found — identical to the response for a token that does not exist, closing the same enumeration-oracle gap the DELETE route closes. Denied attempts are recorded in the audit log with action=api_token.rotate, result=denied, and detail=owner=<real owner>.

Request body (optional):

{ "overlap_secs": 604800 }

overlap_secs defaults to 7 days (604800), with the same 24-hour floor / 10-year ceiling as the engine-principal rotate route — a value outside that range is rejected (400), never silently clamped.

Lifetime-neutral by design (SOC 2 CC6.3): the successor token always inherits the predecessor’s expires_at verbatim — a perpetual (never-expiring) token stays perpetual, a 30-day token stays a 30-day token measured from its own original grant, never recomputed as “90 days from now”. There is no request field to override this; the store-level successor_expires_at override that exists internally for the engine-principal arm is deliberately not exposed on this route. Rotating a credential must never silently extend its authorization lifetime — an auditor reviewing rotation evidence for CC6.3 must be able to trust that rotation and grant renewal are two separate, independently-audited actions, never one fused into the other. A caller that genuinely needs a longer-lived replacement token should mint a fresh one via POST /api/v1/tokens instead.

Response: same Cache-Control: no-store, no-cache, must-revalidate + Pragma: no-cache headers as POST /api/v1/tokens, since the body carries a raw one-time secret.

{
  "data": {
    "token": "yzt_...",
    "token_id": "...",
    "expires_at": 1742385600,
    "overlap_expires_at": 1710936000
  },
  "meta": { "api_version": "v1" }
}

token_id and expires_at describe the successor, found structurally — the active row whose supersedes_token_id equals {token_id} (the predecessor being rotated), never merely “any linked row of this principal’s active set” and never by “most recently created” (which is second-resolution and can tie). A human principal routinely holds several unrelated tokens with independent in-flight rotations, so the match must be scoped to the exact predecessor in the path — a broader match can return a different rotation’s successor.

overlap_expires_at, by contrast, describes the predecessor — consistent with the GET /api/v1/tokens field of the same name above (§“Rotation fields”): it is stamped on the predecessor row, not the successor, and is echoed here purely for the caller’s convenience (the epoch at which the predecessor this call just rotated is auto-revoked). There is no separate overlap_expires_at on the successor row itself; do not expect one from GET /api/v1/tokens until the successor is itself rotated in turn.

Success audit: action=api_token.reveal — the reveal itself is the success event, mirroring the engine-principal route’s engine_principal.credential.reveal; a grace-window re-serve gets its own row too, since every time the raw secret leaves the server is independently on the audit chain.

Errors:

POST /api/v1/tokens/{token_id}/confirm

Explicit maker-checker confirmation that a rotation’s successor secret has been received and installed. {token_id} in the path is the successor’s id — the value the rotate response above returned. On success, the predecessor token is revoked and the successor becomes the sole active token in the rotation group.

Permission: ApiToken:Rotate (same distinct-operation rationale as rotate above)

Proof of possession (#3015, SOC 2 CC6.3) — BREAKING: unlike before, a request body is now required — {"secret": "<raw successor secret>"}, the raw successor secret rotate returned. Confirm revokes the predecessor immediately, so it must never proceed on token_id alone — a caller who merely learned or guessed the (non-secret) successor token_id could otherwise force an immediate cutover without ever having received the new credential. A caller that previously confirmed with only the {token_id} path parameter now gets 400. The check is performed immediately after auth/step-up, before the ownership/existence lookup below, so a missing secret is 400 even against an unowned or nonexistent token_id — it is never an enumeration oracle either way, since neither response discloses whether the token exists.

Request body (required):

{ "secret": "yzt_..." }

secret is verified last, strictly after the ownership check and every store-side admission check (pair-state, the successor pin, the authority-inheritance guard) have passed — via a constant-time hash comparison against the successor’s stored hash, read fresh inside the same advisory-locked transaction as the rest of this call. It is never persisted, logged, or echoed into an audit/error string.

Ownership constraint: the same self-service-only posture as rotate above — no admin bypass, 404 token not found for both a nonexistent successor id and one owned by someone else, and the same action=api_token.confirm/result=denied/detail=owner=<real owner> audit row on a denied attempt.

Response:

{
  "data": { "confirmed": true },
  "meta": { "api_version": "v1" }
}

Errors: the same state matrix as the engine-principal credentials/confirm route above (replay-after-success is a terminal 409, an ambiguous empty/malformed-pair read is a retryable 503, unresolved rotation metadata on the sole survivor is a terminal 409), substituting token is not a human-owned credential / principal has a non-human active credential for the engine-kind equivalents. 401/403 follow the same step-up and permission rules as rotate. The same authority-inheritance 400 — no such token to confirm also applies here, as defence-in-depth only (see the rotate error matrix row above, including the #2963 empty-tier/scope exception). This is not a same-session pin — the caller confirming does not have to be the same session that called rotate; ownership and the raw successor secret (proof of possession) are the actual gates on who may confirm. The check re-verifies that the CALLER’S CURRENT mcp_tier/scope_service equals the successor’s own (or the caller holds no standing tier/scope at all, #2963) — since the successor’s tier/scope are fixed at mint time and cannot legitimately diverge from the predecessor’s, this defense-in-depth check is not reachable as a live path today for a caller presenting the correct current authority, outside a future bypass of rotate’s own guard.

secret missing, empty, or not a string is 400 — secret required (checked before the 404 ownership belt, see above). A wrong secret is 403 — rotation secret mismatch — the presented secret does not verify against the pending successor — distinct from every other outcome, reachable only after every other admission check has already passed. If the authoritative successor row cannot be re-read to verify the secret (should not happen under the lock already held), that’s a fail-closed 503 — failed to verify rotation secret, folded into the general store-failure 503 row above.

Engine Principals

Engine principals are the durable identities behind autonomous use-case-engine modules (ADR-1005 item 2b) — a distinct principal class from human users and human-created API tokens, with a named responsible human owner, a grant justification captured at creation, and a required internal/external classification. Design reference: docs/auth-engine-principals-design.md. Every credential minted against an engine principal is hard-locked to MCP tier readonly and can never be granted the admin/Administrator role or any built-in role (assignment refuses them). A custom role that covers every permission is not refused at assignment (maintainer ruling 2026-10-23, #2485); it is detected afterwards by the pull-only auditor route below.

Every mutating route is admin + MFA-step-up gated. The read routes (GET/list, GET /{id}, and GET /audit/no-admin) are admin + RBAC gated (EnginePrincipal:Read for the two engine-principal reads, AuditLog:Read for /audit/no-admin) but do not require a fresh MFA step-up. Beyond that, every route, reads included, structurally denies a caller whose own session is engine-classed (principal_kind="engine" or auth_source="engine_token"), with one exception: GET /api/v1/engine-principals/{id}/roles carries no engine-session check and relies on its EnginePrincipal:Read gate alone. The two role mutations (POST and DELETE) are step-up-gated like every other mutating route here, so they refuse an engine-classed session at the central check. An engine-classed session can therefore not list, read or mutate engine principals through the other routes, not even its own. A denied engine-classed caller gets 403. On the read routes the handler issues it and the corresponding audit verb is recorded with result=denied. On the mutating routes the 403 is issued by the central step-up check, before the handler runs and before any role grant is consulted, so the handler’s own audit verb is never written; the only audit row is the step-up refusal mfa.step_up.required (result=error) whose detail carries reason=engine_principal_denied and stage=pre_authz.

Storage failure: if the engine-principal store failed to open at startup (no PostgreSQL configured, or a migration failure), every route on this surface returns 503 service unavailable.

Audit-persist failure (fail closed on mutations): these routes emit a privileged-action audit row, and a mutation that cannot record it must never look like a clean success. If the audit-store write itself fails, every mutating route (create, revoke, transfer-owner, credentials/credentials/rotate/credentials/confirm, and the role assign/unassign routes documented later) fails closed — it returns 503 with a Sec-Audit-Failed: true header instead of its normal 2xx (ADR-1005 “mutations fail closed on audit failure”). The mutation may already have taken effect (the audit is emitted after the store write), so treat such a 503 as unconfirmed and reconcile via a read. This is a stricter posture than the software-package/deployment mutations elsewhere in this API, which set-and-proceed (stay 2xx with Sec-Audit-Failed) on the same audit-drop: engine-principal management is a privileged-identity surface, so ADR-1005 holds it to fail-closed rather than proceed-and-signal.

The credential mint and rotate routes additionally withhold the one-time secret on this path — nothing is placed in the 503 body. Recovery differs by route: a mint whose audit dropped leaves a credential that exists but is unusable (no one holds its secret) — GET the principal to see it, then rotate it (mints an audited successor you can then confirm) to obtain a usable secret; a rotate whose reveal-audit dropped can be rotated again within the grace window (about two minutes, by the same operator, against the same server replica; after a restart, on another replica or once the window ends the retry is 409) to re-serve the same successor secret (an audited re-serve, not a new credential). If the window has passed, find the stuck successor with GET /api/v1/engine-principals/{id} (in active_credentials, the credential whose overlap_expires_at is 0 while another credential of the same rotation_group has a non-zero value; that read fails closed with 503, so a 200 list is authoritative) and revoke it with DELETE /api/v1/tokens/{token_id} (REST only; it needs ApiToken:Delete, a fresh MFA step-up and an effective administrator, since the credential’s owner is the engine principal and any other caller gets 404), then rotate again from the remaining sole credential. Do not revoke only the predecessor, which leaves a credential nobody holds, and do not revoke the principal itself: that is terminal. Note the compounding case under a sustained audit outage: repeated mint/rotate failures can leave two unconfirmed credentials, at which point the store’s ≤2-active guard blocks further rotation — recover once the audit store is healthy by revoking the stuck successor as described above and rotating again from the remaining credential (a second mint is refused while any active credential exists).

The read routes (GET/list, GET /{id}, GET /audit/no-admin, GET /{id}/roles) and the engine-session denial above instead set the same Sec-Audit-Failed: true header but still serve their response (except the 503 failure paths of the list and GET /{id} routes below, which serve nothing) — matching the MCP twins’ audit_persisted:false body field. Reads proceed (rather than fail closed like the behavioural-PII device/network reads) because they commit no state and disclose only authorization topology metadata — principal ids, owners, role grants — not per-person behavioural PII; the fail-closed-on-read posture exists specifically to keep individual-identifying data off an unaudited response, which does not apply here. Alert on Sec-Audit-Failed: true from this surface as a SOC 2 CC7.2 evidence-gap signal (the same alert that covers the behavioural-PII routes fires on it), while noting the serve behaviour differs: these reads still return data, those withhold it.

{id} convention: on every route below (GET /{id}, DELETE /{id}, the credentials/credentials/rotate/credentials/confirm/transfer-owner sub-resources), {id} is the full principal_id, i.e. engine:<slug> (e.g. GET /api/v1/engine-principals/engine:vuln-uce) — none of these routes prepend the engine: prefix themselves. This is the opposite convention from the .../{id}/roles role-assignment sub-resource documented later in this file, where {id} is the bare slug and the server reconstructs the full id internally — don’t assume the two sections share one convention.

POST /api/v1/engine-principals

Create a new engine-principal identity. principal_id is derived server-side as "engine:" + slug — the reserved engine: namespace.

Permission: Security:Write

Request body:

{
  "slug": "vuln-uce",
  "display_name": "Vuln UCE",
  "owner_username": "alice",
  "classification": "internal",
  "justification": "First-party vulnerability-management use-case engine module"
}

display_name is accepted but not actually enforced non-empty by the REST route or the store — an empty/omitted display_name is persisted as-is; contrast with the create_engine_principal MCP tool, which additionally rejects an empty display_name at the tool layer (see docs/user-manual/mcp.md).

Validation errors (400):

Response (201):

{
  "data": { "principal_id": "engine:vuln-uce" },
  "meta": { "api_version": "v1" }
}

GET /api/v1/engine-principals

List every engine principal (all lifecycle states), with each principal’s active-credential count.

Permission: EnginePrincipal:Read

Response:

{
  "data": [
    {
      "principal_id": "engine:vuln-uce",
      "display_name": "Vuln UCE",
      "owner_username": "alice",
      "classification": "internal",
      "lifecycle_state": "active",
      "created_at": 1710849600,
      "active_credential_count": 1
    }
  ],
  "pagination": { "total": 1, "start": 0, "page_size": 1 },
  "meta": { "api_version": "v1" }
}

Errors: 503 — engine-principal store not open (see Storage failure above). 503 with Retry-After: 2, retry_after_ms: 2000 and an engine_principal.list audit row with result=failure — the engine-principal list or the token store’s credential counts could not be read (the two stores share one connection pool, so pool exhaustion shows here), so no list is served: an empty list or a count of 0 is never shown when the read did not answer.

GET /api/v1/engine-principals/{id}

Get one engine principal’s full identity row plus its active credentials (token id, name, timestamps, rotation group, overlap-expiry — never the raw secret; token_hash stays masked). active_credentials here is an array of credential objects — contrast with the list route above (active_credential_count, an integer) and with the MCP get_engine_principal twin, whose active_credentials field is an integer count under the same field name (see docs/user-manual/mcp.md).

Permission: EnginePrincipal:Read

Errors: 404 — engine principal not found. 503 — engine-principal store unavailable (not open, or the read itself failed). 503 with Retry-After: 2, retry_after_ms: 2000 and an engine_principal.get audit row with result=failure — the token store could not be read, so no active_credentials list is served (an empty list would read as “no credential”).

DELETE /api/v1/engine-principals/{id}

Terminal, irreversible revoke. Every active credential is revoked first, then the identity’s lifecycle_state flips to revoked — a caller can never observe a revoked identity with a still-valid credential. Idempotent in the sense that calling this on an already-revoked principal still returns 200 success (never an error) — but it is not audit-idempotent: a repeat call re-emits a fresh engine_principal.revoke success audit row each time, recording the repeat operator action (with credentials_revoked=0 on the repeat, since there is nothing left to revoke), not just the original revoke.

Permission: Security:Write

Request body (optional):

{ "superseded_by": "engine:vuln-uce-2" }

superseded_by is an optional successor-principal id recorded on this row for audit-trail continuity — recovery from a compromised or retired principal mints a fresh successor principal rather than un-revoking this one.

Response:

{
  "data": { "revoked": true, "credentials_revoked": 1 },
  "meta": { "api_version": "v1" }
}

Errors: 404 — engine principal not found. 503 — a genuine store failure at any step of the sequence (the principal lookup, the credential-store revoke, or the identity revoke itself) — never an idempotent no-op; credentials are revoked strictly before the identity, so a 503 here never leaves the identity flipped to revoked while a credential is still live. 503 + Sec-Audit-Failed: true — the revoke audit row could not persist (see Audit-persist failure above); the revoke may already have taken effect, so reconcile via GET.

POST /api/v1/engine-principals/{id}/credentials

Mint the first credential for an engine principal. The raw secret is returned exactly once in this response — capture it immediately; it cannot be retrieved again, only rotated (below) or revoked. A second call against a principal that already has an active credential returns 409 — use the rotate route once a credential exists.

Permission: Security:Write

Request body (optional):

{ "ttl_days": 90 }

The body is optional only when it is empty or whitespace-only (the credential then lasts 90 days). Any other body must be a JSON object: a truncated document, an array, a string, a number or null is 400 and mints nothing. Within an object, ttl_days defaults to 90 only when it is omitted. It must be a JSON integer between 1 and 90 (400 otherwise, including a string, float, boolean or null — the engine-credential ceiling matches the tiered-token 90-day cap elsewhere on this surface).

Response (201): headers carry Cache-Control: no-store, no-cache, must-revalidate and Pragma: no-cache so a shared proxy or browser history never retains the secret.

{
  "data": { "token": "yzt_...", "token_id": "...", "expires_at": 1760000000 },
  "meta": { "api_version": "v1" }
}

token is the raw secret (shown once); token_id and expires_at let a pure-REST caller correlate the credential it just minted without a follow-up GET.

Errors: 404 — engine principal not found. 409 — engine principal is not active (revoked), or the principal already has an active credential (mint is single-shot; use credentials/rotate instead). 400 — ttl_days wrong type or out of range, or a non-empty body that is not a JSON object. 503 — CSPRNG failure or any other store failure (a CSPRNG failure also sets Retry-After: 5 and increments yuzu_secure_random_failure_total{reason="prng_failure",site="engine_principal"}). 503 with Retry-After: 2 when the check that the principal has no active credential could not read the token store; nothing is minted, and the audit row is engine_principal.credential.mint with result=failure. Retry once the store answers. 503 with the secret withheld and the audit row engine_principal.credential.mint with result=partial when the credential was created but the read that locates it for the response could not answer: the credential exists but no one holds its secret, so do not retry the mint (that is 409); rotate it. The same 503, withheld secret and result=partial row apply when the read answers but finds no active credential (the new credential was revoked out of band between the insert and the read-back; the detail says so): list the principal’s credentials and rotate only if one is listed. 503 + Sec-Audit-Failed: true — the mint audit row could not persist: the credential was created but its one-time secret is withheld (never in the body), so the credential exists but is unusable — see Audit-persist failure above for recovery.

POST /api/v1/engine-principals/{id}/credentials/rotate

Overlap-pair rotation (design doc §7): mints a successor credential while the existing (predecessor) credential stays valid for an overlap window — at most two active credentials per principal during the overlap. The raw successor secret is returned exactly once per reveal (see below for the grace-window exception). MFA step-up runs on every call to this route, including an idempotent re-serve — a rotate call is never exempt from step-up just because it returns a secret the caller already saw.

Permission: Security:Write

Request body (optional):

{ "overlap_secs": 604800 }

overlap_secs defaults to 7 days (604800). The overlap window has a 24-hour floor and a 10-year ceiling — a value below the floor (or above the ceiling) is rejected outright (400), never silently truncated up to the floor. The window must also end before the predecessor expires and before the successor does, and the successor expires 90 days after the rotation, so in practice the window is shorter than 90 days; a longer one is 400 as well. overlap_secs must be a JSON integer when present, and a non-blank body must be a JSON object: a string, float, boolean or null value, or a truncated or non-object body, is 400 and rotates nothing (an empty or whitespace-only body keeps the default).

Grace-window re-serve: a same-caller retry within a ~120-second grace window after the original mint re-serves the same successor secret (rather than erroring or minting a second successor). Each successful return — the original reveal or a grace-window re-serve — is independently recorded under its own engine_principal.credential.reveal audit row, since every time the raw secret leaves the server is independently on the audit chain, whether or not the bytes are new. Once the grace window lapses, a further rotate call while a rotation is already in flight errors — the caller must fall back to credentials/confirm (below) or the principal-level revoke-and-replace runbook, never an indefinite retry loop.

Response: same no-store headers as the mint route; the data object carries token, token_id, expires_at and overlap_expires_at. expires_at is 90 days from the rotation; it is not inherited from the predecessor. overlap_expires_at is the successor row’s own stamp and is always 0, because only the predecessor is stamped; read the predecessor’s stamp on its entry in active_credentials of GET /api/v1/engine-principals/{id}.

No 404 path: unlike credentials (mint) and transfer-owner, this route never looks up {id} via a get() call before acting — it drives the rotation state machine straight off the principal’s active credential rows. An unknown or revoked {id} therefore does not 404.

Errors:

POST /api/v1/engine-principals/{id}/credentials/confirm

Explicit maker-checker confirmation that a rotation’s successor secret has been received and installed by its consumer. This is a separate attestation from the rotate reveal above — it is never inferred from a successful rotate call. On success, the predecessor credential is revoked and the successor becomes the principal’s sole active credential (closing the overlap window early, ahead of the auto-revoke sweep).

Permission: Security:Write

Proof of possession (#3015, SOC 2 CC6.3) — BREAKING: the request body now also requires secret, the raw successor secret rotate returned. Confirm revokes the predecessor immediately, so it must never proceed on token_id alone — a caller who merely learned or guessed the (non-secret) successor token_id could otherwise force an immediate cutover without ever having received the new credential. A caller that previously confirmed with only token_id now gets 400. The presented secret is verified last, strictly after every other admission check (ownership, pair-state, the token_id pin, and the initiator binding below) has passed — so a wrong secret from a caller who fails an earlier check gets that check’s own non-disclosing error, never a secret-specific one; only a caller who has already cleared every other gate can reach the mismatch outcome.

Request body:

{ "token_id": "a1b2c3d4e5f60718293a4b5c", "secret": "eng_..." }

token_id (required) is the successor’s token id returned by the rotate response above — it pins this confirm to that exact rotation. A stale or mismatched id (for example a blind retry of an old confirm after a second rotation has started) is rejected with 409 and no state change, so a replayed confirm can never resolve a later rotation early. The success audit row records the confirmed id (token_id=<id>).

secret (required) is the raw successor secret from the rotate response — never persisted, logged, or echoed into an audit/error string. Missing, empty, or non-string is 400 — secret required. Verified via a constant-time hash comparison against the successor’s stored hash, read fresh inside the same advisory-locked transaction as the rest of this call; a wrong secret is 403 — rotation secret mismatch — the presented secret does not verify against the pending successor — distinct from every other outcome below, since it is reachable only after every other gate has already passed.

Replaying a confirm after its own success (a network-dropped 200, a double-submit) is a terminal 409 conflict, not a retryable 503: once the rotation has resolved the successor is the sole active credential, and the confirm returns an explicit already confirmed / already resolved answer with no state change. Treat it as done and stop retrying (rotate again only if you genuinely need a fresh rotation). See the error table below for the full state matrix.

Response:

{
  "data": { "confirmed": true },
  "meta": { "api_version": "v1" }
}

Like credentials/rotate above, this route never looks up {id} via a get() call before acting — there is no 404 path here either.

Errors:

POST /api/v1/engine-principals/{id}/transfer-owner

Reassign the named responsible owner of an active engine principal. Admin-forced — deliberately does not depend on the outgoing owner’s cooperation (an account under termination-for-cause cannot use engine-principal ownership as a lever to stall its own deprovisioning).

Permission: Security:Write

Request body:

{ "new_owner": "bob" }

new_owner must reference an existing user (FK-validated).

Response:

{
  "data": { "transferred": true },
  "meta": { "api_version": "v1" }
}

Errors: 400 — new_owner must reference an existing user. 404 — engine principal not found. 409 — engine principal is not active. 503 — the transfer call itself failed. 503 + Sec-Audit-Failed: true — the transfer audit row could not persist (see Audit-persist failure above); the transfer may already have taken effect, so reconcile via GET.

GET /api/v1/engine-principals/audit/no-admin

Auditor-runnable check of the “no admin” rule for every engine principal. Reads every grant held by an engine: id from the grant table, with each role’s permissions, against the live RBAC reference tables and reports each detected grant: a literal admin/Administrator role (admin_role), any role flagged is_system (system_role), or a wildcard_grant (a role, or with an empty role the union of a principal’s roles, that allows every securable × operation pair of the grid as it is at run time). Assignment refuses the admin names and built-in roles but not a custom full-grid role (maintainer ruling 2026-10-23, #2485); this route is the detective control for that case. It is point-in-time and pull-only: nothing schedules it or alerts on a result, and role permissions can change after assignment.

Permission: AuditLog:Read — deliberately not Security, since this is a read-only evidentiary query, not part of the write-path bar it verifies; a read-only auditor role can run it without holding engine-principal write access. With RBAC disabled the route is admin-only like every other audit read (#5771).

Response:

{
  "data": { "ok": true, "violations": [] },
  "meta": { "api_version": "v1" }
}

ok:true means no role held by an engine principal, and no engine principal’s union of roles, allows every pair of the current grid at the moment of the run. A role that grants every pair but one is not reported, and deny rows are ignored. Each entry of a non-empty violations array carries principal_id, role (the role name; empty for a union-only wildcard) and reason (admin_role / system_role / wildcard_grant; the MCP twin’s include_revoked=false can also return orphan_grant, see below). Grants are read by principal id whatever their principal type, so a user-typed grant on an engine: id is reported too. A row with reason admin_role or system_role means the assignment check was bypassed (data corruption, direct DB write, or a code regression) and should be treated as a security incident. A wildcard_grant is a custom role that covers the whole grid, which assignment does not refuse: review whether that grant is intended. The success audit row engine_principal.audit.no_admin carries violations=N scope=all and up to ten principal_id:reason pairs; those rows are the evidence the control operated. A dropped success-row write is signalled only by Sec-Audit-Failed on this route (the MCP twin gives no signal). The Tokens page also calls this route incidentally, in the browser, when a viewer who holds AuditLog:Read loads the principals panel; that is not a schedule and not a control, so a period with no rows is not evidence that the check ran or that it passed. The grants, roles and role permissions are three separate reads, not one snapshot.

Errors (503): rbac resolution unavailable - cannot verify when the grants, roles or role permissions could not be read, and rbac reference data unavailable — cannot verify when the RBAC reference tables (securable_types/operations) came back empty. Both carry Retry-After: 2 and retry_after_ms: 2000 (the MCP twin uses the same 2000 ms hint). Both are fail-closed: there is no partial violations list, the audit row is engine_principal.audit.no_admin with result=failure and no success row is written. Treat them as “unable to verify,” never as “clean.”

Sessions

Operator and dashboard sessions are the cookie-based sessions issued by POST /login. The endpoints below let an admin force-log-out another user from every device, and let any authenticated principal sign out of every browser at once. They are the SOC 2 CC6.3 (revocation) and CC6.8 (termination) evidence path; both endpoints emit auditable actions distinguishable by SIEM correlation.

The DB primitive (AuthDB::invalidate_all_sessions) and the in-memory counterpart already fire when a user is removed (DELETE /api/settings/users/{username}) or when their role changes; these REST endpoints expose the same primitive standalone for incident response and operator self-service.

DELETE /api/v1/sessions?username=<name>

Revoke every active cookie session for a named user. The user remains valid (no role change, no account disable); they simply have to authenticate again to obtain a new session cookie. API tokens belonging to the user are deliberately NOT revoked — operators force-logging out a leaked cookie session typically want to leave CI/CD and automation tokens running. Use DELETE /api/v1/tokens/{token_id} (or the user’s own DELETE /api/v1/sessions/me) to revoke those.

Permission: UserManagement:Write

Self-target behaviour. An admin invoking this with their own username is permitted (signing yourself out of every device is recoverable — re-authenticate and you are back), but the audit row is recorded as session.revoke_all.self instead of session.revoke_all so SIEM rules can split operator self-service from a sibling-admin force-logout. This is a deliberately weaker guard than the #397/#403 self-target guard on DELETE /api/settings/users/{username}, which exists to prevent admin-role self-lockout (an unrecoverable state).

Example:

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://yuzu.example.com/api/v1/sessions?username=alice"

Response (200):

{
  "data": {
    "username": "alice",
    "revoked": 2,
    "db_persisted": true,
    "audit_emitted": true
  },
  "meta": { "api_version": "v1" }
}

revoked is the number of sessions wiped (the fleet-wide durable count on a Postgres-backed deployment, or the local cookie count in the config-file-only fallback). db_persisted reports whether the durable session delete succeeded — since HA WS-1/1a this goes through the durable SessionStore (invalidate_user), never AuthDB. When false, the audit row is recorded with result="partial" and detail carries db_error=true. Remediation: retry — the durable delete is idempotent, so re-issuing the request converges. A server restart does NOT revoke the sessions: durable sessions survive a restart by design (ADR-2002 §4), so a session that failed to be revoked stays valid until its absolute 8-hour expiry, not “resurrected” by restart. The local cache is wiped on this replica regardless (the operator’s “stop NOW” intent is honoured there immediately), but the durable rows — and any other replica’s cache — are only cleared once the delete actually lands.

audit_emitted reports whether the SOC 2 CC6.6 audit row landed in the audit store. When false the response also sets the Sec-Audit-Failed: true header — SREs scraping for evidence-integrity gaps should alert on either signal. The revoke side-effect still completes when audit_emitted=false (operator’s “stop NOW” intent is honoured); only the SOC 2 evidence chain is degraded for that request. This split was introduced in PR #883 (HIGH-2) to close a silent-failure window where a locked audit DB or disk-full condition produced a 200 OK that masqueraded as full evidence.

Audit: successful cross-user invocations emit session.revoke_all with target_type=User, target_id=<username>, and detail=count=<N> (or count=<N> db_error=true on partial failure). When the caller’s own username is supplied, the action is session.revoke_all.self instead.

The admin route emits two distinct 400 bodies — operators scripting the endpoint should distinguish them.

Error (400) — missing username query parameter:

{
  "error": { "code": 400, "message": "username query parameter required" },
  "meta": { "api_version": "v1" }
}

Error (400) — malformed username value:

{
  "error": { "code": 400, "message": "invalid username format" },
  "meta": { "api_version": "v1" }
}

The username parameter accepts either a strict local username OR a durable SSO principal (is_valid_principal, #1852) — an OIDC principal (oidc:<iss>#<sub>) or, since ADR-2001 PR4a, a SAML principal (saml:<entity_id>#<NameID>), so an admin can force-log-out an SSO operator authenticated via either protocol. Local usernames stay on the strict alphanumeric/._- charset; an SSO principal permits the : # / . _ - @ ~ % | alphabet a real IdP issuer URL and opaque subject need. NUL bytes, control characters, newlines, and shell/SQL metacharacters (;, =, \, quotes, backtick, space) are rejected in both cases — passing them through to the SQL bind would silently truncate/diverge from the audited target string (sec-H1). A 400 with the invalid username format message indicates the client has malformed input; retrying with the same value will not succeed.

SAML sessions are now force-loggable (ADR-2001 PR4a). A SAML session’s Session::username is the stable principal saml:<entity_id>#<NameID> (saml_principal_id, mirroring the OIDC shape exactly), not the raw NameID — create_saml_session mints it via the saml: reserved prefix, which is_valid_principal accepts on the same wider SSO charset as oidc:. An admin can therefore force-log-out a SAML operator with:

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://yuzu.example.com/api/v1/sessions?username=saml%3Aentity-id%23NameID"

(URL-encode the : and #.) SAML sessions are also revoked automatically as part of SCIM deprovision — see “SCIM ↔ SAML identity linkage” in docs/user-manual/scim-provisioning.md, which covers the NameID-Format precondition for that automatic linkage. This closes the gap previously tracked as #1859/#1860.

Error (403) — caller lacks UserManagement:Write:

{
  "error": { "code": 403, "message": "forbidden" },
  "meta": { "api_version": "v1" }
}

DELETE /api/v1/sessions/me

Self-revoke “Sign out everywhere”. Wipes every cookie session belonging to the authenticated caller AND revokes every API token they own. This is intended as the lost-device recovery flow: every credential bearing the caller’s identity is killed in one call.

Permission: Any authenticated caller: a cookie session or a plain API token (one with no mcp_tier and no service scope) is accepted. MCP-tier tokens and service-scoped automation tokens are explicitly rejected with 403 — those credential classes have no other write privilege and accepting them here would create a novel DoS surface against the human owner. Use the dashboard, a fresh password-authenticated session or a plain API token.

Example:

curl -s -X DELETE \
  -H "Origin: https://yuzu.example.com" \
  -H "Cookie: yuzu_session=$COOKIE" \
  "https://yuzu.example.com/api/v1/sessions/me"

Response (200):

{
  "data": {
    "revoked": 3,
    "api_tokens_revoked": 2,
    "db_persisted": true,
    "audit_emitted": true
  },
  "meta": { "api_version": "v1" }
}

The response sets Set-Cookie: yuzu_session=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0 so the client side completes the revocation by deleting the cookie from the browser jar. audit_emitted and the Sec-Audit-Failed: true header have the same semantics as on the admin route above — false means the revoke completed but the audit row was lost (locked DB / disk full / pipeline exception), and the SOC 2 CC6.6 evidence chain is degraded for that request.

Error (403) — non-interactive credential:

The caller authenticated with an MCP-tier token (X-Yuzu-Token carrying a non-empty mcp_tier) or a service-scoped token. The denial is audited as session.revoke_all.self with result=denied.

{
  "error": {
    "code": 403,
    "message": "self-revoke requires an interactive session, not an MCP-tier or service-scoped token"
  },
  "meta": { "api_version": "v1" }
}

Audit: every successful invocation emits session.revoke_all.self with target_type=User, target_id=<caller>, detail=count=<N> api_tokens_revoked=<M> (with db_error=true appended on partial failure). The dashboard’s “Sign out everywhere” button on the operator’s own row in Settings → Users uses this endpoint and follows up with a redirect to /login.

Users

POST /api/v1/users/{username}/unlock

Clear a user’s account-lockout counter. After --auth-lockout-threshold consecutive failed local-password logins an account is temporarily locked (SOC 2 CC6.3 — see the account-lockout flags in the server-admin guide). The lock already auto-expires after --auth-lockout-window-secs; this endpoint is the operability path for an admin who needs to restore access immediately (e.g. a locked-out VIP who can’t wait out the window).

Permission: UserManagement:Write (plus MFA step-up when MFA is enrolled — parity with DELETE /api/v1/sessions).

Self-target behaviour. An admin invoking this with their own username is permitted — clearing your own lockout is recoverable. This is the same weaker-than-#397/#403 guard reasoning as DELETE /api/v1/sessions.

Body: none.

Example:

curl -s -X POST \
  -H "Origin: https://yuzu.example.com" \
  -H "Cookie: yuzu_session=$COOKIE" \
  "https://yuzu.example.com/api/v1/users/alice/unlock"

Response (200):

{
  "data": {
    "username": "alice",
    "unlocked": true,
    "audit_emitted": true
  },
  "meta": { "api_version": "v1" }
}

audit_emitted and the Sec-Audit-Failed: true header have the same semantics as the session-revoke routes above — false means the unlock completed but the audit row was lost, degrading the CC6.3 evidence chain for that request.

Errors: 400: username empty or malformed (e.g. contains a reserved :); 401: MFA step-up required (stale or absent proof; see meta.challenge_url); 403: caller lacks UserManagement:Write, or a SAML session (step-up is not available for SAML sessions, unless --mfa-step-up-window-secs is 0 or less, which lets SAML sessions through on the 37 step-up-gated routes); 500: the AuthDB (Postgres) write failed (a best-effort auth.lockout.cleared/error audit is still attempted); 503: the lockout subsystem is not wired (no AuthDB).

Audit: a successful unlock emits auth.lockout.cleared with result=ok, target_type=User, target_id=<username>, detail=admin_unlock. A failed write emits the same verb with result=error. Note that a lockout cleared automatically (no operator action) emits auth.lockout.cleared with result=ok and detail=reset_on_successful_login when the user next logs in successfully; the threshold crossing itself emits auth.lockout.applied. These two verbs are the durable CC6.3 evidence; blocked-while-locked attempts are tracked only via the yuzu_auth_lockout_blocked_total metric (no per-attempt audit row or analytics event) to avoid amplification under a sustained brute-force.

POST /api/v1/users/me/password

Change the caller’s own local-account password (#5342). The caller proves the current password; the new one must be 12–1024 bytes of UTF-8 (bytes, not characters — a character outside ASCII takes 2–4 bytes). The dashboard’s Settings → User Management → Change password button uses this route.

Who can call it: an interactive dashboard session whose account is local (auth_source=local). There is no extra permission check — every local user may change their own password. Under --auth-mode=sso-only only the configured break-glass account, and only while it is armed, may use it (see the 403 sso_only_local_disabled row below). Non-admin users have no dashboard page for it yet: the button is on the admin-only User Management page, so a non-admin signs in and uses Access → Users and roles → Your account → Change password, or calls the route directly.

Order of checks. Each step runs only if every earlier one passed. For a cookie session the server-wide same-site check (see step 3) answers first, before any step-up evaluation. The central MFA step-up check (step 4) then runs, before the handler’s own steps 2 and 3, and the handler repeats it from the same per-request verdict (a token caller skips the same-site check). An over-cap request body whose size is declared in Content-Length is refused 413 before any of these, because the pre-routing body cap runs first. This route is in a body class that does not require a measurable body, so a chunked over-cap body from a cookie session with no same-site Origin/Referer is answered by the same-site 403 before the post-read 413 (which runs after the body is read, just before the step-up check):

1. Authentication (401 without a session).

2. Session class: an API, MCP or engine token, or a service-scoped token, is 403 token_session; an OIDC or SAML session is 409 not_local (change it at the identity provider).

3. Same-site request (this route’s own copy): Origin/Referer must be the dashboard’s own origin (or a --csrf-trusted-origin entry), and a request carrying neither header is refused with 403 csrf. Content-Type must be application/json, else 415 (not audited). A cookie-session caller never reaches the csrf refusal: the server-wide check (see Authentication) answers first, with message cross-site request refused and no csrf code, and this copy is defence in depth.

4. MFA step-up, when the account is enrolled and its proof is stale — 401 step-up envelope (meta.mfa_step_up_required, meta.challenge_url).

5. Body and length policy — 400, not audited (nothing security-relevant was attempted, and a policy rejection never records the length). The body is never echoed, because it may hold a password.

6. The current password, through the same lockout-accounted check as POST /login: a wrong password is 403 wrong_current and counts toward account lockout; a locked account gets the same 403 and message (account_locked in the audit row only — no lock-state oracle). A password that could not be verified — the auth store could not be read, or the stored password changed while it was being checked — is a retryable 503 verify_transient and never counts. If the lockout counter cannot be recorded the answer is 503 store_unavailable (fail closed: an uncounted guess is never answered as an ordinary wrong password). A correct current password clears a non-zero failure counter (auth.lockout.cleared, detail=reset_on_password_change).

7. One transaction. Under the account’s row lock, the server re-checks that the stored password is still exactly the one step 6 verified and that the account is still an active local account, then — together, or not at all — writes the new password, deletes every session of the account (including the caller’s own, durably and on every replica), wipes a provisional (not yet enrolled) TOTP secret, and writes the user.password_change audit row. A refusal here changes nothing (your session stays valid): 409 conflict (the password changed concurrently, e.g. an admin reset), 409 not_local (the account became SCIM-managed in between), 404 not_found (it was deactivated). If the audit row cannot be written the change is not made: 503 audit_unavailable with Sec-Audit-Failed: true. Any other store failure is 503 store_unavailable. A 503 body says what is true: nothing was changed unless the server lost contact with the database at commit; a successful sign-in with the new password confirms the change, which is audited either way.

Body: {"current_password": "<string>", "new_password": "<string>"}. Only new_password is length-checked at step 5. current_password is not: one longer than 1024 bytes is answered exactly like a wrong password (403 wrong_current, counts toward lockout) without being hashed, as /login does. A new_password equal to the current one is accepted — it is stored with a fresh salt and every session is signed out, as for any change.

Example:

curl -s -X POST \
  -H "Cookie: yuzu_session=$COOKIE" \
  -H "Origin: https://yuzu.example.com" \
  -H "Content-Type: application/json" \
  -d '{"current_password":"old-password-123","new_password":"a-new-long-password"}' \
  "https://yuzu.example.com/api/v1/users/me/password"

Response (200) — with a Set-Cookie header that clears the session cookie:

{
  "data": {
    "username": "alice",
    "password_changed": true,
    "sessions_revoked": 3,
    "session_reissued": false,
    "provisional_mfa_cleared": false,
    "audit_emitted": true
  },
  "meta": { "api_version": "v1" }
}

No replacement session is issued: the caller is signed out and signs in again with the new password. sessions_revoked counts the sessions deleted at step 7 (the caller’s included). provisional_mfa_cleared is true when an un-enrolled TOTP secret was wiped (an enrolled second factor is never touched). session_reissued is always false and audit_emitted always true — a 200 means the user.password_change row committed with the change. API tokens are not touched. Only a 200 clears the cookie; a refusal leaves it alone.

Errors:

Every 503 carries retry_after_ms and a Retry-After header.

Audit: user.password_change, target_type=User, target_id=<caller>, the caller as principal on every row. Success is result=ok, detail=self_service sessions_revoked=<N> provisional_mfa_cleared=<true|false>, written in the same database transaction as the change — the change and its evidence commit or abort together, so there is no rollback step and no “changed but unrecorded” state; there is no separate session.revoke_all row. Refusals are result=denied (error for 503) with the detail tokens above. The password, its hash and its length never appear in any audit row or log line.

Metric: yuzu_auth_password_changes_total{kind="self", result="ok"|"denied"|"error"} (the not-audited 400/415 count as denied).

POST /api/v1/users/{username}/password

Reset another user’s local-account password (#5342) without knowing the current one. The dashboard’s Settings → User Management → Reset password button uses this route.

Who can call it: a durable Administrator — not an ordinary permission check. The route uses the same is_rbac_administrator predicate as the RBAC role-assignment routes, then re-checks it against the enforcement regime in effect right now, and applies the same rule whatever the target’s role:

• RBAC off: the caller’s own account, re-read from the auth store, must hold the admin role.
• RBAC on: the caller must hold an Administrator grant as a user principal.

A JIT elevation, an IdP-group-derived session role (an OIDC session whose admin role comes only from --oidc-admin-group), a group-held Administrator grant, or a custom role holding UserManagement:Write is refused 403 durable_admin_required. If the stores cannot confirm the caller’s authority the answer is 503 admin_gate_unavailable (retryable; never downgraded to a 403). The caller must use an interactive dashboard session; API, MCP, engine and service-scoped tokens are refused 403 token_session. A SAML session is refused 403 by the central MFA step-up check before the administrator check is reached, because there is no SAML MFA attestation in this release.

Order of checks: authentication → for a cookie session, the server-wide same-site check, then the central MFA step-up check (the handler’s own step-up below repeats it from the same verdict) → username format (400, not audited) → session class (403 token_session) → same-site Origin/Referer (403 csrf; this route’s own copy, defence in depth, since the server-wide check answers a cookie-session caller first with cross-site request refused) and Content-Type: application/json (415, not audited) → the durable-Administrator check (403 durable_admin_required / 503 admin_gate_unavailable) → not yourself (403 self_target) → not the break-glass account (403 break_glass_target) → MFA step-up (when the caller is enrolled) → body and the 12 to 1024 byte policy (400, not audited) → one transaction (below).

• Not yourself: targeting your own username is 403 self_target — use POST /api/v1/users/me/password, which requires your current password, so a stolen admin cookie cannot re-key its own account.
• Not the break-glass account: the account named by --break-glass-user is 403 break_glass_target. It is re-keyed only out of band on the server host, or by signing in as it while armed and using POST /api/v1/users/me/password, so an identity-provider compromise cannot invalidate the escape hatch.
• One transaction: under the target’s row lock — together, or not at all — the new password is written, every dashboard session of the target is deleted (durably, on every replica), a provisional (not yet enrolled) TOTP secret is wiped, any lockout is cleared, and the audit row(s) are written. If the audit row cannot be written nothing changes: 503 audit_unavailable with Sec-Audit-Failed: true; any other store failure is 503 store_unavailable; a 503 body says nothing was changed unless the server lost contact with the database at commit; a successful sign-in with the new password confirms the change, which is audited either way. An enrolled second factor is not touched — if the account may be compromised, clear it too (yuzu-server --mfa-reset <user>, see Authentication).
• Local accounts only: the account is classified under the lock. An SSO principal or a SCIM-provisioned account is 409 not_local; an absent or deactivated account is 404 not_found — and a refusal changes nothing (the target’s sessions stay valid). A path segment cannot carry an SSO principal’s / and #, so in practice only local usernames reach the handler. An account literally named me cannot be reset over REST — POST /api/v1/users/me/password is the self route (#5359 tracks reserving the name).

Body: {"new_password": "<string>"}.

Example:

curl -s -X POST \
  -H "Cookie: yuzu_session=$COOKIE" \
  -H "Origin: https://yuzu.example.com" \
  -H "Content-Type: application/json" \
  -d '{"new_password":"a-temporary-long-password"}' \
  "https://yuzu.example.com/api/v1/users/bob/password"

Response (200):

{
  "data": {
    "username": "bob",
    "password_reset": true,
    "sessions_revoked": 2,
    "lockout_cleared": true,
    "provisional_mfa_cleared": false,
    "api_tokens_active": 1,
    "remediation": "the account's API tokens were NOT revoked; if it may be compromised, revoke them (DELETE /api/v1/tokens/{id})"
  },
  "meta": { "api_version": "v1" }
}

• lockout_cleared — true only when the target had a lockout (locked_until set — even if the lock has since expired — or a non-zero failure count) and it was cleared, in the same transaction as the reset, with an auth.lockout.cleared row (detail=password_reset) in the same commit. false means there was nothing to clear (no auth.lockout.cleared row is written).
• provisional_mfa_cleared — true when an un-enrolled TOTP secret was wiped, so an enrolment started before the reset cannot be finished and the next enrolment gets a fresh secret.
• api_tokens_active — API tokens are deliberately left alone (automation may depend on them, and a reset is not by itself a compromise finding), so the response reports how many active tokens the account holds. If the token store cannot be read it is null and "api_tokens_unknown": true is added; remediation then says the count could not be confirmed. The dashboard shows a warning unless the count is a confirmed 0.

Errors:

Audit: user.password_reset, target_type=User, target_id=<target>, principal = the caller on every row. Success result=ok, detail=admin_reset target_role=<admin|user> sessions_revoked=<N> provisional_mfa_cleared=<true|false>, plus — only when a lockout existed — auth.lockout.cleared (result=ok, detail=password_reset); both are written in the same transaction as the reset (no rollback step, no unrecorded state). Refusals as for the self route.

Metric: yuzu_auth_password_changes_total{kind="admin", result=...}.

Rate limit: both password routes share the per-IP /login rate-limit bucket (login_rate_limit_per_ip), not the general API bucket, because the self route verifies a password. Over the limit: 429 with Retry-After: 1.

No MCP twin (parity exception). Neither password route has an MCP tool, by design, recorded as exception: rows in docs/api-parity-ledger.md. Self-service change is permanently excluded: an MCP caller is a token, not the human, and a token that could change its owner’s password would turn a token leak into an account takeover. Admin reset is deferred: UserManagement:Write is approval-gated at the supervised MCP tier, and an approval ticket stores the tool’s arguments in plain text and shows them to approvers, so a password argument would be persisted and displayed. The planned tool takes no password argument — the server generates a temporary password and forces a change at next sign-in (#5357).

POST /api/v1/users/{username}/elevation-eligibility

Grant or revoke a user’s JIT-admin-elevation eligibility — who may activate a time-boxed admin elevation via POST /api/v1/elevate (SOC 2 CC6.3/CC6.6). This is the per-user users.elevation_eligible flag, distinct from holding standing admin and enumerable for access reviews. See JIT Admin Elevation below and docs/auth-architecture.md “JIT admin elevation”.

Permission: admin + MFA step-up (an active elevation suffices only to revoke). Self-grant is blocked — an operator cannot set their own eligibility (another admin must). Granting (eligible=true) needs the caller’s own administrator role: a session that is administrator only through an elevation gets 403 (audit user.elevation_eligibility.set / denied / elevated_session_eligibility_grant_blocked). Revoking is still open to an elevated session.

Body: {"eligible": <bool>}.

Side effect: setting eligible=false immediately terminates any in-flight elevation for that user.

Two route forms, same handler:

• Path form — POST /api/v1/users/{username}/elevation-eligibility — local usernames only in practice: both forms validate the target with is_valid_principal (#1852), but a path segment cannot carry the / and # an SSO principal contains, so only a local username reaches the handler this way.
• Query form — POST /api/v1/users/elevation-eligibility?username=<principal> — required for a durable SSO principal (oidc:<iss>#<sub>). A path segment cannot carry the / (in the issuer URL) and # an SSO principal contains — the server percent-decodes the path and strips the URL fragment before route matching, so the path form 404s for every real IdP identity. The query form accepts the same shapes as DELETE /api/v1/sessions above (is_valid_principal, #1852): a strict local username, or an SSO principal (URL-encode the # as %23; / does not need escaping in a query value).

This is an UPDATE-only operation against an existing users row, never an INSERT — an SSO principal only has a row once the operator has logged in at least once (first login auto-provisions it). Granting eligibility against a principal with no row yet returns 404, which for an SSO principal specifically means “this operator has never signed in” rather than “no such user was ever created”.

curl -s -X POST -H "Cookie: yuzu_session=$COOKIE" \
  -H "Origin: https://yuzu.example.com" \
  -H "Content-Type: application/json" -d '{"eligible":true}' \
  "https://yuzu.example.com/api/v1/users/alice/elevation-eligibility"

# SSO principal — MUST use the query form; note the URL-encoded '#' (%23):
curl -s -X POST -H "Cookie: yuzu_session=$ADMIN_COOKIE" \
  -H "Origin: https://yuzu.example.com" \
  -H "Content-Type: application/json" -d '{"eligible":true}' \
  'https://yuzu.example.com/api/v1/users/elevation-eligibility?username=oidc:https://idp.example.com/%23sub-4821'

Response (200): {"status":"ok"}.

Errors: 400: invalid username/principal or non-boolean body; 401: not authenticated, or MFA step-up required (stale or absent proof; see meta.challenge_url); 403: not admin, self-grant, a grant (eligible=true) from a session that is administrator only through an elevation, or a SAML session (step-up is not available for SAML sessions; this holds even when --mfa-step-up-window-secs is 0 or less, because the elevation routes own their gate and substitute a 300 s window); 404: user not found (for an SSO principal: the operator has never logged in); 503: AuthDB unavailable (--postgres-dsn unset/unreachable).

Audit: user.elevation_eligibility.set, result in {ok, denied, error}, detail=eligible=<bool> (plus elevations_cleared=<N> when a revoke dropped active windows; self_grant_blocked or elevated_session_eligibility_grant_blocked on a 403).

POST /api/v1/users/elevation-eligibility

The query-parameter form of the route above. It uses the same handler, permission, body ({"eligible": <bool>}), response (200 {"status":"ok"}), errors and audit. The target is passed as ?username=<principal> instead of a path segment. This form is required for an SSO principal (oidc:<iss>#<sub>; URL-encode the # as %23), because a path segment cannot carry that principal’s / and #. A local username may use either form. A missing or empty username returns 400. See the section above for the full permission rules (admin plus MFA step-up, self-grant blocked, granting needs the caller’s own administrator role). Revoking with eligible:false also ends any active elevation. If that clean-up fails, the route returns 503 even though the flag change was saved; retry to finish the revocation.

Quarantine

Quarantine isolates a device from receiving commands or participating in normal operations. Quarantined devices remain connected but are blocked from instruction execution.

Scoped per-target authorization (#1788). All three routes below authorize per-device, matching the MCP quarantine_device tool: a management-group-confined operator holding Security:Execute/Security:Read only through a group can act on and see devices inside their own group(s), and is refused (403) for devices outside them. On GET and DELETE, a global grant (or an unfiltered/legacy-RBAC-disabled deployment) still reaches every device, unchanged; POST additionally applies the dispatch approval check described below. If the per-target scope gate is ever left unconfigured, every request on these routes fails closed with a 500 rather than silently widening to a fleet-wide check.

GET /api/v1/quarantine

List currently quarantined devices visible to the caller — admit-then-filter (ADR-0017): the route makes one Security:Read list-gate decision per request and applies the resulting scope in the store query, so a device outside the caller’s management-group scope is omitted from the list entirely, not merely hidden from write access, and an out-of-scope record costs neither a per-record permission check nor an audit row.

Permission: Security:Read, resolved once through the fleet-read list gate. MCP twin: list_quarantined_devices (capped at 500 records per call; this route returns the complete list; see docs/user-manual/mcp.md).

Fail-closed on a degraded read (ADR-0047). A store/pool/query failure returns 503 ("quarantine list unavailable — try again"), never a silently-empty list — a device could still be actively contained while the caller would otherwise see “nothing quarantined”. Each failure increments yuzu_server_quarantine_read_degrade_total — see docs/user-manual/upgrading.md and docs/user-manual/metrics.md. If the list gate itself cannot decide (an unavailable authorization store, or a service-scoped API token whose ITServiceOwner ceiling cannot be read) it answers with its own 401/403/503 and the store is not read. An unwired gate answers 500, never an unfiltered list.

Response:

{
  "data": [
    {
      "agent_id": "agent-compromised-01",
      "status": "active",
      "quarantined_by": "admin",
      "quarantined_at": 1710849600,
      "whitelist": "10.0.1.50,10.0.1.51",
      "reason": "Suspicious network activity detected",
      "last_applied_at": 1710849660,
      "last_confirmed_at": 1710849675
    }
  ],
  "pagination": { "total": 1, "start": 0, "page_size": 50 },
  "meta": { "api_version": "v1" }
}

last_applied_at/last_confirmed_at (#3425), both 0 = never. Endpoint-containment confirmation state written by QuarantineContainmentReconciler, the background component that re-applies a device’s own firewall on reconnect. last_applied_at means a system re-dispatch of the stored whitelist was accepted (agents_reached > 0) — NOT proof of containment (a gateway-attached agent’s send_to only queues the frame). last_confirmed_at is set only after a follow-up quarantine.status read reports state|active — but that read is the target agent’s own self-report (cert-bound to its identity, not independently corroborated by any network-side signal), so treat it as strong operational evidence of containment, not proof. See docs/user-manual/security-hardening.md “Reconnect re-application (#3425)” for the full trust boundary.

POST /api/v1/quarantine

Quarantine a device.

Permission: Security:Execute, scoped per-device (see the note above)

Audit-before-change (ADR-0033 §9). After authorisation and validation the route writes a quarantine.enable row with result=attempt before it changes the record. If that row cannot be written the request is refused with 503 (Sec-Audit-Failed: true) and containment is unchanged. The change is then recorded as success or failure; a lost outcome row is flagged with the same header on the response.

Supervised MCP tokens are approval-gated here too. A bearer token minted with mcp_tier: "supervised" gets 403 on this route (and on the DELETE release below): supervised Security:Execute requires an approval ticket, and the ticket-then-recall flow exists only on the MCP transport (quarantine_device). The REST route mirrors the denial so switching transports cannot bypass the approval gate (#520).

Dispatch approval check (#6065). After the scoped Security:Execute gate and whitelist validation, and before the attempt audit row or any record is written, the route runs the shared dispatch check for quarantine.quarantine, the same one MCP quarantine_device runs. REST has no approval-ticket path today, so the check admits only an administrator: here that means an account whose account role is admin (a live temporary JIT elevation counts as that role). Holding the RBAC Administrator role or a global Security:Execute grant on an account whose role is user does not make the account an administrator for this check.

With RBAC off (the default) nothing changes for non-administrators: the scoped gate already refuses Security:Execute without the admin account role (a JIT elevation counts), and the dispatch check adds no refusal. With RBAC on, a caller must be an administrator in that sense and hold Security:Execute globally in their own right; a live JIT elevation supplies the first condition, not the second.

Statuses these routes can answer beyond the usual 400 (body) and 503 (store). The table is grouped by cause, not ordered by when a request meets them: the 500 for an unwired audit identity writer comes first, right after authentication; the 401 for a changed principal comes at the second look-up, after the scoped gate and whitelist validation, and before the dispatch check:

Status	When	Reason label (audit detail, metric)
403	RBAC on: the caller holds Security:Execute globally but is not an administrator (account role user, no live JIT elevation)	approval_required
403	RBAC on: the caller’s own Security:Execute grant is not global (for example it is held only through a management group, or the caller is an administrator only through a JIT elevation), or the RBAC store could not be read (a transient failure reads the same as a denial)	forbidden
400	The quarantine.quarantine pair cannot be classified	unclassified or ambiguous
403	Other chokepoint refusals map the same way (kill_switched, anonymous_operator); neither is reachable for this pair today, because quarantine is exempt from the per-action kill switch and an unauthenticated request ends at the 401	kill_switched, anonymous_operator
401	The request’s second session look-up named a different principal than the first (for example a session cookie lapsed and a bearer token for another account is on the same request); written as a quarantine.enable row with result=denied and detail authenticated principal changed during the request now=<second account> (the account name has control bytes, spaces, commas, = and ; replaced by _ and is cut at 128 bytes), naming the first account as the actor	none
500	The dispatch check is not wired on this server (also written as a quarantine.enable row with result=failure)	none
500	The audit identity writer is not wired on this server (misconfiguration; written as a quarantine.enable row with result=failure and detail audit identity writer not configured)	none

Every refusal carries error.message and error.remediation. For approval_required the message states that the action needs an administrator caller or a redeemed approval ticket, and the remediation names the MCP supervised flow; REST serves that shared MCP wording until #6065 PR-C gives REST its own. For forbidden the message is permission denied: Security:Execute and the remediation says the caller lacks the grant. That remediation does not help a group-only holder, a JIT-elevated administrator with no grant of their own, or a transient RBAC read failure: for the last, check yuzu_server_rbac_read_degrade_total before treating the refusal as permanent. The 403 bodies never carry a permission field: holding that permission would not admit the caller, so naming it would be a false remediation hint. A refused request writes no quarantine record and no attempt audit row. It writes a quarantine.enable row with result=denied and the reason in detail, and increments yuzu_server_dispatch_denied_total{reason}. A session that expires between the first authorisation check and the request’s second look-up now ends at the 401 instead of writing a record attributed to system. The second look-up must also name the same principal as the first: a request whose two look-ups resolve to different principals (for example a session cookie that lapsed and a bearer token for another account on the same request) ends at 401 with a denied row naming the first, and writes no record. Every audit row the handler writes after its first look-up names the session the route resolved, not a fresh look-up of the request, so the attempt and outcome rows name the same account as the record’s quarantined_by; rows written by the scoped permission gate itself, and the failure row for an unwired writer, still come from a look-up of the request. A server whose audit identity writer is not configured answers 500 on both routes and changes nothing. The denied rows are best-effort, as for a dispatch-check refusal: a lost write does not change the status.

Request body:

{
  "agent_id": "agent-compromised-01",
  "reason": "Suspicious network activity detected"
}

Response (201):

{
  "data": { "quarantined": true },
  "meta": { "api_version": "v1" }
}

400 vs 503 (ADR-0047). A 400 means a business/state error (a missing agent_id, the device is already quarantined, or whitelist fails server-edge validation) — retrying the identical request will not succeed, and error.retry_after_ms is null. A 503 means a genuine store/pool failure — retrying is reasonable, and error.retry_after_ms carries a concrete 5000 hint (REST’s envelope has no nested data object — that’s MCP’s JSON-RPC shape; REST matches the MCP quarantine_device twin’s A5 behavior, not its exact field path).

This route records; it does NOT itself dispatch — and the twins have diverged on the already-quarantined case (#3127). POST /api/v1/quarantine writes the quarantine record only, synchronously. The live plugin isolation is dispatched by the MCP quarantine_device tool, which has no REST twin. Two consequences for a client that treats the two transports as interchangeable:

• A 201 here means the record was written, not that the device’s firewall is enforcing anything yet. To isolate a device immediately, dispatch quarantine.quarantine through the normal execution routes as well — see Security Hardening. As of #3425, “yet” is load-bearing: this route no longer leaves a record permanently unenforced. QuarantineContainmentReconciler reconciles every active record regardless of which surface created it — a record written here for a device that is (or later becomes) connected is automatically dispatched the stored whitelist typically within one reconciler tick (~20s) of the device being connected, without a second call — a brand-new record isn’t in the heartbeat fast path’s cache until the next periodic tick populates it, so a heartbeat arriving in that narrow window doesn’t shortcut the wait. A record created here for a reachable device does not stay dormant — the one exception is a stored whitelist the re-dispatch validator refuses. As of #3425 (d1f71c58f) this route validates whitelist at write time (400 instead of 201 for a malformed value), the same rule MCP’s quarantine_device already enforced — so a fresh write here can no longer land in this state. A validation_failed reconcile now points at a record written via this route before d1f71c58f shipped, or — on a fleet with pre-#3623 history — one migrated from a legacy quarantine.db by the since-retired migrate_from_sqlite backfill (ADR-0047, which copied whitelist verbatim with no validation), not a fresh call. Either way, every reconcile attempt then counts validation_failed and nothing is ever dispatched. That failure is loud, not silent — the device stays in yuzu_server_quarantine_endpoint_unconfirmed{reachability="connected"} and trips YuzuQuarantineEndpointUnconfirmed after 15 minutes — but it is a real way for a record to go permanently unenforced through this route. If record-only-without-live-isolation is the intent (e.g. flagging for review), enforce it at the caller/workflow level; do not rely on this route’s absence of its own dispatch.
• The MCP tool now treats an already-active record as a retryable re-dispatch, not a terminal error; this route still answers 400, because with no dispatch of its own there is nothing for it to re-drive. The 400-vs-503 split above is unchanged and still mirrors the twin; the already-quarantined outcome no longer does.

A quarantined device is refused at dispatch (#881). Once a device is quarantined, every dispatch route below — POST /api/command, POST /api/instructions/{id}/execute, and the scope/group/broadcast arms — drops that device before the command reaches the agent, increments yuzu_server_dispatch_target_rejected_total{reason="quarantined"}, and writes a quarantine.dispatch_denied audit row (target_type=Security; target_id is the device, or * on a fail-closed denial and on the summary row that follows a capped per-device fan-out — see Audit Log).

POST /api/command reports what it withheld. The success body carries withheld_quarantined, (#3424/#3511) withheld_unknown_plugin and (#5294) withheld_kill_switched_os — all always present, 0 on a clean dispatch — so agents_reached: 97 on a 100-device group is distinguishable from three devices being offline, and a MIXED partial dispatch (some reached, some plugin-absent) is never silently invisible in the response. The success body also carries audit_emitted (#2557), the same field every denial arm that calls emit_behavioral_audit on this route already carries (the body-type, targeting-shape, Destructive-untargeted, Destructive-no-visible-target, no-target-named and classification-denial 400/403/404 arms) — NOT the scope-parse 400 (an unrelated JSON shape with no audit call at all) or the sent==0 503 family, neither of which ever carried it — present and false only when the paired command.dispatch result=success audit row failed to persist (the response also sets Sec-Audit-Failed: true in that case), omitted entirely when no audit store is configured. Before #2557 the success path’s audit call was unguarded against a throwing sink and never reported this field at all — the one response shape most likely to be read as “everything is fine” was also the one place a silent audit-persist failure was invisible to the caller. The dashboard’s own execute console (/api/dashboard/execute, a separate HTML-fragment handler, not this route) now names the same containment/quarantine/plugin-absence causes on a zero-agents-reached dispatch; it does not yet surface withheld counts on a MIXED partial dispatch the way this route’s success body does — tracked as a follow-up.

Its 503 now names the cause. Several conditions previously shared one body (“failed to send command to any agent”), and two of them are fleet-wide/request-wide states rather than a transport failure:

error.reason	Meaning	retry_after_ms
containment_unreadable	The gate is failing closed: containment state cannot be read, so every target on every dispatch is refused. A server condition, not a device one.	5000
quarantined	Every target named is contained. The dispatch was withheld, not attempted.	null — retrying will not help until the device is released
plugin_not_found (#3511)	The dispatched plugin is absent from every target’s reported inventory — a command guaranteed to fail, withheld before dispatch rather than reported as a false success. Permanent for the current plugin name. If the plugin name and spelling are correct and it genuinely is installed on the target, the agent’s REPORTED inventory is stale: it is populated once at registration and does not refresh until the agent’s management connection next re-registers (a reconnect — daemon restart, or any dropped/re-established connection) — this reason can persist until then even after installation completes.	null — retrying will not help; check the plugin name/spelling instead, or trigger a reconnect on the target agent if the plugin was only just installed
kill_switched_os (#5294)	Every reachable target runs an OS for which this plugin action’s per-OS kill switch is OFF. The dispatch was withheld, not attempted.	null — retrying will not help until the switch is turned back on for that OS
os_gate_unreadable (#5294)	Agent presence could not be read while a per-OS kill switch is set, so the dispatch failed closed rather than reaching only this replica’s local agents. Transient.	5000
(absent)	Genuinely no agent reachable — the pre-existing meaning.	(absent)

plugin_not_found, kill_switched_os and os_gate_unreadable are never produced for a protective action (the quarantine plugin’s four actions and __guard__.push_rules); see Upgrading.

reason is a top-level key on the error object, not part of the A4 error.data envelope. POST /api/instructions/{id}/execute carries the same reason 503 split as POST /api/command above (containment_unreadable / quarantined / plugin_not_found / kill_switched_os / os_gate_unreadable, same retry_after_ms values) — closed alongside the architect finding that its response-building code was reading dispatch_outcome.command_id/.sent only, discarding the richer fields already available on the same struct.

A fourth, structurally distinct condition — invalid_scope — is 400, not part of the 503 table above. This route (unlike POST /api/command) accepts a caller-supplied scope expression; a malformed one is a client mistake, not a fleet-state fact, so it reports error.reason: "invalid_scope" at 400 with retry_after_ms: null, checked before the 503 cascade so a bad expression is never shadowed by containment_unreadable. Its generic catch-all (no reason key, matching the (absent) row above) additionally covers ADR-1007’s per-device concurrency-claim exclusion, unique to this route since it — unlike /api/command — accepts a concurrency_mode: for a per-device definition, every named target may have been excluded by an already-open claim rather than being unreachable at all; the message points at yuzu_server_dispatch_concurrency_skipped_total. The bundle and result-set producers still do not carry this split — their own response-building code was not extended to surface the richer per-arm result their shared dispatch closure now carries (a separate, smaller follow-up per route). The quarantine plugin’s own four actions (quarantine, unquarantine, status, whitelist) are exempt so that release stays reachable, and so are four server-internal pushes that are not operator dispatch — echo.fleet_snapshot, __guard__.push_rules, asset_tags.sync and __sync__.now, a closed set counted (not per-event audited) by yuzu_server_system_reserved_push_total. Nothing else is. If containment state becomes unreadable for longer than a 60-second last-known-good window, dispatch fails closed and refuses every target fleet-wide — alert on yuzu_server_quarantine_gate_total{outcome="fail_closed"}, which is an outage signal rather than a quarantine one (see Metrics).

DELETE /api/v1/quarantine/{agent_id}

Release a device from quarantine. This ends the server’s quarantine record only: it does not remove the device’s firewall rules. To lift those, run the quarantine plugin’s release instruction (security.quarantine.release, “Release Device from Quarantine”) from the Instructions page or through execute_instruction.

Permission: Security:Execute, scoped per-device (see the note above)

Like POST, the release writes a quarantine.disable row with result=attempt before the change and answers 503 (Sec-Audit-Failed: true) without releasing the device if that row cannot be written.

Dispatch approval check (#6065). After the scoped gate, and before the attempt audit row and the release, the route runs the same dispatch approval check as POST, for the quarantine.unquarantine pair: a caller who cannot create a record cannot end one. The answers, statuses and reason labels are the table under POST, with the pair read as quarantine.unquarantine and the audit verb as quarantine.disable; a refusal leaves the record active, writes a quarantine.disable audit row with result=denied and detail reason=<label> securable=<name> (no attempt row), and increments yuzu_server_dispatch_denied_total{reason}. The remediation text names the MCP supervised flow, which has no release tool, so a non-administrator has no path to release through REST, the dashboard or MCP; an administrator releases it. Running the plugin’s unquarantine without ending the record does not release the device from the server’s side: the record stays active, the lens can keep reading the earlier confirmation, and containment is re-applied at the next session change, so an administrator should end the record first.

The 401 for a changed principal, the 500 for an unwired audit identity writer and the session-stamped audit rows are exactly as for POST above, with the audit verb quarantine.disable.

Response:

{
  "data": { "released": true },
  "meta": { "api_version": "v1" }
}

400 vs 503 (ADR-0047). Same distinction as POST above — 400 means the device is not currently quarantined (retrying will not help); 503 means a genuine store/pool failure (retrying is reasonable).

Internal CA

The server’s built-in certificate authority (see docs/pki-architecture.md) can be managed via the Settings → Certificates and secrets page (or the Settings → Internal CA panel on the Settings page) or the REST endpoints below. root and crl are public (clients and browsers need them to establish trust / check revocation before they have a session); the inventory and revoke endpoints are gated by the Security securable.

Note on Security operations: certificate revocation uses Security:Delete (a destructive operation on an issued cert), while device quarantine uses Security:Execute. A custom role scoped to security operations needs both.

GET /api/v1/ca/root

Download the CA root certificate (PEM) and add it to an OS/browser trust store. Public — no authentication. Returns Content-Type: application/x-pem-file, Content-Disposition: attachment; filename="yuzu-ca.pem", Cache-Control: public, max-age=86400. 404 if no CA root exists; 503 if the CA store is unavailable (a genuine database error, distinct from no-root).

curl https://yuzu.example.com/api/v1/ca/root -o yuzu-ca.pem
openssl x509 -in yuzu-ca.pem -noout -fingerprint -sha256

GET /api/v1/ca/crl

Download the current certificate revocation list (DER). Public — no authentication. Returns Content-Type: application/pkix-crl, Cache-Control: no-cache, must-revalidate. 503 if no CRL has been published yet (transient — the server pre-publishes at startup and republishes on each revocation).

curl https://yuzu.example.com/api/v1/ca/crl -o yuzu.crl
openssl crl -inform DER -in yuzu.crl -noout -text

GET /api/v1/ca/issued

List certificates issued by the internal CA. Permission: Security:Read. Query params limit (1–1000, default 200) and offset (default 0). The full certificate PEM and enrollment reference are intentionally omitted. 503 if the CA store is unavailable.

The inventory is fleet-wide data about every enrolled agent (subject, SAN), so it is held to the same rules as the filtered list below. A caller whose view of the fleet is confined (management-group confinement), or who holds no Inventory:Read grant, is refused 403 with no permission named, and the refusal is written as a denied crypto.ca.certificates.view row (target inventory, detail cid=<cid> ws=crypto_widget_windows_v1 withheld=confined or withheld=refused). A served page is written as a success row (target inventory, detail cid=<cid> inventory rows=<n> limit=<n> offset=<n> has_more=<bool> standing=available), set-and-proceed: if the row cannot be written the page is still served, with Sec-Audit-Failed: true and audit_persisted: false in the body. The confinement check reporting itself unavailable is 503 + retry_after_ms: 5000 (access check unavailable, also written as a failure row), a store that cannot be read is 503

• retry_after_ms: 5000 (CA store unavailable, also a failure row), and a server built without the check is 503 with no retry_after_ms (certificate list unavailable).

Who is served. The list is served only to a caller whose Inventory:Read is granted without a management-group restriction (a global grant). A caller whose Inventory:Read is granted only for management groups is confined and is refused (403, a denied row ending withheld=confined). A caller holding Security:Read and no Inventory:Read grant at all is refused too (403, withheld=refused): holding no grant is not an affirmative admission to a fleet-wide list. Granting a global Inventory:Read removes the restriction, and removing a caller’s last scoped Inventory:Read grant never widens what it can see. With RBAC enforcement off nothing changes: every Security:Read session is served, as before.

A read failure inside the access check is a retryable 503, never the list. If a store behind the check (permissions, management groups) cannot be read, the route answers 503 access check unavailable with retry_after_ms: 5000 and writes a failure row. The same holds for the filtered list below and the /crypto drill (a banner with Retry). The audit row can be missing during the same outage (correlate with yuzu_server_audit_emit_failed_total).

meta.has_more is true when more rows exist beyond the current page; when it is, meta.next_offset carries the offset to pass for the next page. Iterate until has_more is false (do not infer end-of-list from count < limit).

meta also carries the revocation-list figures, so a client can judge revocation freshness without downloading the DER list: crl_version, crl_published_at and crl_next_update (epoch seconds), crl_revoked_count and crl_stale. The first four are null when no list is published, and crl_revoked_count is also null (never a fabricated 0) for a list published before entry counts were recorded; 0 means a published list with no revoked entries. crl_stale is true when the latest list was not built from the current revoked set (a revocation is missing from it, no list is published, or its entry count was not recorded), false when it covers every revocation, and null when the comparison read failed. It does not reflect expiry: compare crl_next_update with the current time. The MCP list_issued_certs tool returns the same five fields at the top level of its result.

{
  "items": [
    {
      "serial_hex": "3A4B5C6D...",
      "subject": "agent-prod-01",
      "san": "URI:yuzu://<ca-fp>/agent/agent-prod-01",
      "purpose": "agent",
      "status": "active",
      "not_after": 1780000000,
      "issued_at": 1710849600,
      "issued_by": "agent:agent-prod-01"
    }
  ],
  "count": 1,
  "meta": { "api_version": "v1", "limit": 200, "offset": 0, "has_more": false,
            "crl_version": 14, "crl_published_at": 1710849600, "crl_next_update": 1711454400,
            "crl_revoked_count": 2, "crl_stale": false }
}

The MCP list_issued_certs tool mirrors this contract (same has_more / next_offset).

Filtered: the certificates behind one /crypto count (ADR-0070 R2, R8). When any of kind, days, week, bucket, as_of or cursor is present, the route lists exactly the certificates behind one Yuzu-issued count of GET /api/v1/crypto/ca/stats, with the same predicate. Permission: Security:Read, and a caller whose view of the fleet is confined, or who holds no Inventory:Read grant, is refused 403 with no permission field (Yuzu-issued certificate figures are not available to this account: ...), whatever the parameters. The input is strict, and each malformed parameter is a 400 whose message names it:

A parameter repeated with differing values is a 400. offset is refused in this form (400 naming it): the filtered list pages by keyset cursor only. limit or offset alone does not select this form (the unfiltered list above keeps its offset paging).

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://yuzu.example.com/api/v1/ca/issued?kind=revoked&days=30&bucket=superseded"

{
  "items": [
    {
      "serial_hex": "3A4B5C6D...",
      "subject": "agent-prod-01",
      "san": "URI:yuzu://<ca-fp>/agent/agent-prod-01",
      "purpose": "agent",
      "status": "revoked",
      "not_after": 1821657600,
      "issued_at": 1790121600,
      "revoked_at": 1791590400,
      "revocation_reason": "superseded",
      "issued_by": "agent:agent-prod-01",
      "issuer_key_id": "ab12..."
    }
  ],
  "count": 1,
  "filter": {
    "kind": "revoked", "days": 30, "week": null, "week_start": null, "bucket": "superseded",
    "rule_id": "yuzu_ca_revoked_superseded",
    "criterion": "Revoked after as_of - 30 days and on or before as_of, reason recorded as superseded (replaced by a same-key successor)",
    "rule_set_version": "crypto_widget_windows_v1",
    "as_of": 1792396800, "as_of_iso": "2026-10-19T08:00:00Z", "total": 1,
    "scope_note": "Counts certificates Yuzu's own CA issued only (agent, server, gateway, HTTPS and code-signing); certificates on your devices are not covered."
  },
  "next_cursor": null,
  "meta": { "api_version": "v1", "limit": 100, "has_more": false }
}

filter.total counts every match at filter.as_of; when meta.has_more is true, next_cursor is set: request the next page with cursor=<next_cursor> (and the same kind, days, week, bucket). The cursor carries the position of the last certificate served and the walk’s as_of, so every page is measured against the same time and starts strictly after that certificate: a certificate revoked between pages never makes the walk skip another (an offset would). next_cursor is null on the last page. Order: expiring soonest first, expired and revoked most recent first, the rest newest-issued first. Every filtered call is audited crypto.ca.certificates.view, as is every unfiltered call (set-and-proceed: audit_persisted: false in the body and Sec-Audit-Failed: true when the row is lost; a confined refusal is a denied row, and an unavailable access check a failure row). Errors: 400 (each malformed parameter, named), 401, 403 (no Security:Read, a confined caller, or no Inventory:Read grant), 503 + retry_after_ms: 5000 (Yuzu CA read degraded, crypto read capacity in use; retry, or access check unavailable; never an empty list), and 503 without retry_after_ms (filtered certificate list unavailable: the server was built without the /crypto seam, a wiring fault that lasts until a restart). MCP twin: list_issued_certs with the same arguments.

POST /api/v1/ca/revoke

Revoke a certificate by serial. Permission: Security:Delete. Revocation takes effect server-side immediately (the mTLS accept gate reads ca_store, not the CRL); the CRL is then republished. Request body (max 64 KB):

{ "serial_hex": "3A4B5C6D...", "reason": "key compromise" }

serial_hex is required (1–64 hex digits, case-insensitive). Unknown JSON fields are rejected. A reason equal (trimmed, case-insensitive) to one of the system markers superseded or unpublished is stored as operator-supplied: <text> (the revoke still succeeds), so an operator-typed reason can never be mistaken for the bookkeeping revocations the server writes itself. Response:

{ "revoked": true, "serial_hex": "3A4B5C6D...", "crl_republished": true, "meta": { "api_version": "v1" } }

crl_republished: false means the revocation stands (the agent is refused on its next gRPC call) but the public CRL could not be rebuilt — external CRL consumers will not see it until the next successful publish. The server retries on its own: the leader’s freshness pass republishes on its next 15-second tick once the cause clears (up to about 5 minutes later if that attempt fails too). Repeating the POST is not a retry — it returns 404 because the serial is already revoked. Errors: 400 (missing/invalid serial, unknown field, bad JSON), 403 (missing Security:Delete), 404 (serial not found or already revoked), 413 (body too large), 503 (CA unavailable).

POST /api/v1/ca/issue-code-signing (gap-matrix #10)

Issue a code-signing leaf certificate via CSR custody — the operator holds the private key and submits only a PKCS#10 CSR; the server never sees the key. See docs/pki-architecture.md “Code-signing certificate issuance” and docs/user-manual/agent-plugins.md “Plugin Signing” for the full workflow. Permission: Security:Write. MCP twin: issue_code_signing_cert (same schema, supervised-tier + approval-gated like every other Security:Write MCP tool). Request body (max 64 KiB):

{
  "csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\n...",
  "label": "plugin-signer-2026",
  "validity_days": 365
}

csr_pem is required. label is required and becomes the leaf’s subject CN — must match ^[A-Za-z0-9._-]{1,64}$ (never an agent-style yuzu://…/agent/… URI SAN). validity_days is optional, [1, 730], default 365, refused outright (not silently clamped) if requested out of range; always further clamped so the leaf cannot outlive the issuing CA. Unknown JSON fields are rejected. Usage is hard-pinned to codeSigning only — never clientAuth/serverAuth — which is what makes this route safe to expose while the general POST /api/v1/ca/issue stays deferred (see pki-architecture.md). Response:

{
  "certificate_pem": "-----BEGIN CERTIFICATE-----\n...",
  "chain_pem": "-----BEGIN CERTIFICATE-----\n...",
  "serial_hex": "3A4B5C6D...",
  "not_after": "2027-09-10T00:00:00Z",
  "purpose": "code-signing",
  "meta": { "api_version": "v1" }
}

chain_pem is the issuing cert plus, in subordinate-CA mode, the parent chain above it — feed both certificate_pem and chain_pem to openssl cms -sign -certfile to build a signature an agent can chain to its trust anchor. Errors use the A4 envelope: 400 (missing/invalid csr_pem, invalid label, validity_days out of range, a signing key below the strength floor — the accepted set is RSA 2048-16384 bits or EC P-256/P-384/P-521; Ed25519 and Ed448 are rejected, since openssl cms -sign cannot use them — unknown field, bad JSON), 403 (missing Security:Write), 409 (no CA root — generate default certs first), 413 (body too large), 503 (CA unavailable). Audited as ca.cert.issued (target_type=CodeSigningCertificate, target_id=<label or serial>, detail carries purpose=code-signing) — the same action name an agent-leaf issuance uses, distinguished by target_type (CodeSigningCertificate vs AgentCertificate), with purpose as a secondary discriminator. Revoking the issued leaf uses the existing POST /api/v1/ca/revoke above; revocation does not yet reach the agent-side plugin-load verifier via the CRL — see docs/pki-architecture.md’s caveat before relying on this operationally.

Subordinate-CA (root your CA in an enterprise PKI)

By default Yuzu’s CA is a self-signed install root (trust mode: built-in). An enterprise can instead make Yuzu’s issuing CA a subordinate of its own root, so every Yuzu-issued certificate chains to the corporate trust anchor. The issuing key never changes — the enterprise signs Yuzu’s existing public key — so certificates already issued keep validating across the switch.

Workflow:

1. Export Yuzu’s CA signing request and have your enterprise root sign it as a subordinate CA (the signed cert must carry basicConstraints: CA:TRUE, keyUsage: keyCertSign, cRLSign).
2. Import the signed intermediate plus the parent chain (enterprise root and any intermediates above Yuzu’s).

This is also available in Settings → Internal CA → “Subordinate this CA…”.

GET /api/v1/ca/root-csr

Export the install CA’s PKCS#10 CSR (PEM), over its existing key, for an enterprise root to sign. Permission: Security:Read. The CSR carries only the CA’s public key (already public via GET /api/v1/ca/root) and subject — no secret. Audited (ca.root_csr.exported).

curl -H "Authorization: Bearer $TOKEN" \
  https://yuzu.example.com/api/v1/ca/root-csr -o yuzu-ca.csr
# → hand yuzu-ca.csr to your enterprise CA; it returns a signed intermediate.

Errors: 403 (missing Security:Read), 500 (CSR generation failed), 503 (CA unavailable).

POST /api/v1/ca/import-chain

Import the enterprise-signed intermediate + parent chain, switching the issuing identity to subordinate mode. Permission: Security:Write. Request body (max 256 KB):

{
  "intermediate_pem": "-----BEGIN CERTIFICATE-----\n... (Yuzu's key, signed by the enterprise) ...\n-----END CERTIFICATE-----\n",
  "chain_pem": "-----BEGIN CERTIFICATE-----\n... (enterprise root [+ intermediates]) ...\n-----END CERTIFICATE-----\n"
}

The server validates that the intermediate (a) is a CA certificate, (b) carries this install’s CA public key (proof the enterprise signed the CSR you exported), and (c) verifies up to the supplied parent chain — then swaps the issuing cert and re-publishes the CRL under the new issuer. Response:

{ "imported": true, "mode": "subordinate", "crl_republished": true, "meta": { "api_version": "v1" } }

Errors: 400 (bad JSON / missing field / unparseable intermediate), 403 (missing Security:Write), 409 (no existing CA to subordinate — generate default certs first), 422 (intermediate is not a CA / does not carry this CA’s key / does not verify to the chain), 413 (body too large), 500 (validated but persistence failed), 503 (CA unavailable). A rejected import is audited ca.subordinate.imported with result=denied; success with result=success.

Bring-your-own-leaf (orthogonal): any surface given an explicit --cert/--key/--ca-cert (or --https-cert/--https-key) flag bypasses the internal CA for that surface entirely — unchanged behaviour, supported and independent of subordinate mode.