Admin API

GET/api/admin/agents

admin access

Returns a list of all registered agents with their most recent jobs.

Requires admin permission — enforced in-handler as defense-in-depth regardless of RBAC middleware method handling.

Secret hygiene

token_hash and the raw public_key are NEVER included in the response. The immutable enrollment id and a SHA-256 public-key fingerprint are included so an approval can bind to the exact row/key the administrator reviewed. cryptographically_admitted is derived from the complete consumed-challenge linkage rather than from a nullable id alone.

Bounds

Agents are capped at 500 (newest first); jobs are capped at 5 000 total across all agents, then further limited to the 10 most recent per agent in Rust. capped: true in the response signals the agent list was truncated.

Permissions

HTTP request

GET https://<your-host>/api/admin/agents

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/agents'

GET/api/admin/agents/dead-lettered-jobs

admin access

Lists every terminal DeadLettered agent job (poison jobs that exhausted the redispatch cap, #23) so an operator can SEE them — otherwise they are an operational black hole.

Admin-only (re-checked in-handler as defense-in-depth). Newest first, capped at 500. spec/live_context are excluded (secret hygiene).

Permissions

HTTP request

GET https://<your-host>/api/admin/agents/dead-lettered-jobs

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/agents/dead-lettered-jobs'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "dead_lettered_jobs": null,
  "count": null
}

POST/api/admin/agents/dead-lettered-jobs/{job_id}/requeue

admin access

Recovers a DeadLettered job: returns it to Pending with a fresh redispatch budget (delivery_attempts = 0) + cleared lease state, so the agent fleet can pick it up again.

Admin-only + audited. Guards (in the project lock order requests -> agent_jobs, which cannot deadlock since no path locks job -> request): - the job must still be DeadLettered (idempotent: a second requeue 409s); - the PARENT REQUEST must still be ACTIVE — a job whose request has concluded (failed/cancelled/rejected/completed/...) or is orphaned/unknown is REFUSED (409), so requeue can never re-dispatch stale work for a closed request.

Permissions

HTTP request

POST https://<your-host>/api/admin/agents/dead-lettered-jobs/{job_id}/requeue

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  'https://<your-host>/api/admin/agents/dead-lettered-jobs/<job_id>/requeue'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "job_id": null,
  "status": "<string>",
  "requeued": false
}

POST/api/admin/agents/enrollment-challenges

admin access

Preprovisions one short-lived bootstrap grant for an exact agent identity and existing Ed25519 workload key.

The plaintext challenge is returned only in this response; the database retains its hash. Delivery to the intended workload remains a trusted, provider-neutral provisioning responsibility.

Permissions

HTTP request

POST https://<your-host>/api/admin/agents/enrollment-challenges

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: CreateEnrollmentChallengeBody.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

200 response headers

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"agent_id":"<string>","platform":"<string>","public_key":"<string>"}' \
  'https://<your-host>/api/admin/agents/enrollment-challenges'

POST/api/admin/agents/jobs/{job_id}/cancel

admin access

Cancels a PENDING (not-yet-leased) agent job — one created in error or no longer wanted — instead of letting an agent lease and run it.

CASes on status = 'Pending': once Leased/Running an agent owns the job (cancelling CP-side would split-brain), and a terminal job is already done — both → 409. Admin-only, audited; emits a NON-alerting job.cancelled event. JOB-SCOPED: the parent request stays Executing, and the operator concludes it with POST /api/requests/{id}/fail (identical to the reconcile-resolve contract). A cancelled LiveApply still consumes the request's permanent LiveApply slot — there is no in-place retry; re-attempting needs a fresh request (see create_live_apply_job).

Permissions

HTTP request

POST https://<your-host>/api/admin/agents/jobs/{job_id}/cancel

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: CancelJobBody.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"reason":"<string>"}' \
  'https://<your-host>/api/admin/agents/jobs/<job_id>/cancel'

POST/api/admin/agents/jobs/{job_id}/force-fail

admin access

Terminally fails a STUCK Leased agent job (leased to an agent that died / never acked) without waiting out the lease-expiry + dead-letter cycles.

Scoped to Leased jobs whose mode is OfflineDryRun / LivePlan — modes that NEVER touch real infrastructure, so Failed is safe and a late ack/result is rejected by the result CAS (status IN ('Leased','Running')). A Leased LiveApply is EXCLUDED (409): with out-of-order delivery the agent may have started applying real infra, so it must go through the lease-expiry path → ReconcileRequired (this endpoint never sets ReconcileRequired). Pending uses cancel; a Running job belongs on the lease-expiry/reconcile path. Admin-only, audited; emits a NON-alerting job.force_failed event. JOB-SCOPED: the parent request is left for the operator's POST /api/requests/{id}/fail (identical to the cancel/reconcile contract).

Permissions

HTTP request

POST https://<your-host>/api/admin/agents/jobs/{job_id}/force-fail

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: ForceFailJobBody.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"reason":"<string>"}' \
  'https://<your-host>/api/admin/agents/jobs/<job_id>/force-fail'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "job_id": null,
  "request_id": null,
  "status": "<string>",
  "force_failed": false,
  "note": "<string>"
}

POST/api/admin/agents/jobs/{job_id}/priority

admin access

Re-prioritize a PENDING agent job (#15).

Admin-tier. Only a Pending (not-yet-leased) job is reprioritizable — a leased/running/ terminal job's queue priority is moot, so the UPDATE CASes on status = 'Pending'. Higher = more urgent (0..=9). Audited.

Permissions

HTTP request

POST https://<your-host>/api/admin/agents/jobs/{job_id}/priority

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: SetJobPriorityBody.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"priority":0}' \
  'https://<your-host>/api/admin/agents/jobs/<job_id>/priority'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "job_id": null,
  "status": null,
  "priority": null
}

POST/api/admin/agents/jobs/{job_id}/reconcile

admin access

Resolves a terminal-dead-end ReconcileRequired live-mutation job to terminal Failed once an operator has reconciled provider and state out-of-band.

Failed is the conservative truth: the CP cannot verify that an interrupted mutation reached its intended state. The operator's reconciliation is captured in the audited reason. Admin-only. A non-alerting job.reconcile_resolved domain event closes the reconcile-required alert lifecycle (it does NOT page). A LiveApply parent stays Executing for explicit operator conclusion through POST /api/requests/{id}/fail; resolving a LiveDestroy also fails its TearingDown step and parent request so rollback cannot remain wedged. There is NO in-place LiveApply retry: its request slot is permanently consumed (the no-double-apply index is all-statuses), so re-attempting requires a fresh request (see create_live_apply_job).

Permissions

HTTP request

POST https://<your-host>/api/admin/agents/jobs/{job_id}/reconcile

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: ReconcileBody.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"reason":"<string>"}' \
  'https://<your-host>/api/admin/agents/jobs/<job_id>/reconcile'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "job_id": null,
  "request_id": null,
  "status": "<string>",
  "resolved": false,
  "note": null
}

GET/api/admin/agents/jobs/{job_id}/result

admin access

Retrieve one agent job's SIGNED result attestation + metadata (#agent-job-result).

Admin-only. The signed_envelope is a pure cryptographic attestation (digests + signature + ids, NO raw evidence); the raw agent-submitted evidence_json is NEVER exposed. For a successful Terraform LivePlan, plan_review is reparsed server-side from the exact bytes whose digest is carried by the signed envelope and contains only an allowlisted action/placement projection. 404 if the job is unknown OR has no result yet (signed_envelope IS NULL). Scoped principals see only jobs whose parent request falls within their site/environment scope (run-5 A0).

Permissions

HTTP request

GET https://<your-host>/api/admin/agents/jobs/{job_id}/result

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/agents/jobs/<job_id>/result'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "job_id": null,
  "result_status": null,
  "completed_at": null,
  "result_id": null,
  "evidence_digest": null,
  "raw_plan_digest": null,
  "signed_envelope": null,
  "plan_review": null
}

GET/api/admin/agents/jobs/{job_id}/state

admin access

An operator's read-only view of ONE agent job's LIFECYCLE state (status, mode, the holding agent, lease deadline, redispatch attempts), so an operator can SEE a stuck Leased/Running job before deciding to force-fail / cancel / reconcile it.

Admin-only. SECRET-SAFE: never returns spec / fencing_token / cp_nonce / live_context / raw evidence / the signed envelope (the attestation is GET .../result). The 5-segment …/state path (vs a bare 4-segment …/jobs/{job_id}) avoids shadowing …/agents/{agent_id}/approve|revoke for an agent literally named "jobs" — a bare GET there would 405 the agent's approve/revoke.

Permissions

HTTP request

GET https://<your-host>/api/admin/agents/jobs/{job_id}/state

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/agents/jobs/<job_id>/state'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "job_id": null,
  "request_id": null,
  "platform": null,
  "mode": null,
  "status": null,
  "result_status": null,
  "agent_id": null,
  "lease_deadline": null,
  "delivery_attempts": null,
  "evidence_digest": null,
  "created_at": null,
  "updated_at": null,
  "completed_at": null
}

POST/api/admin/agents/live-apply-jobs

admin access

Disabled legacy endpoint.

Its caller-supplied platform, spec, and plan digest could bypass the request-scoped safe plan-review derivation. Live apply approval is available only through POST /api/requests/{id}/approve-live-apply, which derives every mutation-authorizing field from a successful stored LivePlan.

Auth posture

The route sits under /api/admin/ so the human RBAC middleware already enforces verified-human admin permission at the routing layer. The typed actor check below is defense-in-depth if the handler is ever re-mounted.

Returns 410 Gone for every authorized caller. No request body is accepted and no database or signing-key state is consulted.

Permissions

HTTP request

POST https://<your-host>/api/admin/agents/live-apply-jobs

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  'https://<your-host>/api/admin/agents/live-apply-jobs'

GET/api/admin/agents/liveness

admin access

?offline_after_secs=N — operational liveness of approved agents (#44).

Admin-gated; 503 with no DB. Read-only: this surfaces which approved agents have gone silent (offline detection) WITHOUT mutating the enrollment status, so it can never accidentally revoke an agent.

Permissions

HTTP request

GET https://<your-host>/api/admin/agents/liveness

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/agents/liveness'

GET/api/admin/agents/queue-depth

admin access

The pending (queued) agent-job backlog per platform (#6 read slice; the pending-jobs view #15 deferred).

For each platform with pending work: the pending count, the oldest pending job's age, and the highest priority waiting. Admin-only (explicit re-check — GET routes under /api/admin/ may not be gated by the RBAC middleware). Only Pending jobs are "queued" (leased/running/terminal are excluded). Exposes ONLY aggregates + the platform name — no spec/live_context/request_id/agent ids.

Permissions

HTTP request

GET https://<your-host>/api/admin/agents/queue-depth

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/agents/queue-depth'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "queues": null
}

POST/api/admin/agents/{agent_id}/approve

admin access

Sets an agent's status to 'approved'.

The platform must match the consumed trusted challenge; capabilities remain administrator-authoritative and the agent's self-declared capability document is only a hint.

The request must carry enrollment_id and public_key_fingerprint from the current admin roster together with platform. Binding approval to the immutable row and reviewed key prevents a stale page from approving a later enrollment that reused the same human-readable agent id. This endpoint sits under /api/admin/ so the human RBAC middleware enforces the admin permission. The in-handler human-session gate additionally keeps agent and API-token credentials from minting a transitive workload identity.

Permissions

HTTP request

POST https://<your-host>/api/admin/agents/{agent_id}/approve

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: ApproveBody.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"enrollment_id":"<uuid>","public_key_fingerprint":"<string>","platform":"<string>"}' \
  'https://<your-host>/api/admin/agents/<agent_id>/approve'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "agent_id": null,
  "enrollment_id": null,
  "public_key_fingerprint": null,
  "status": "<string>",
  "platform": null,
  "capabilities_digest": null
}

POST/api/admin/agents/{agent_id}/revoke

admin access

Sets an agent's status to 'revoked' (from pending or approved).

Revocation is TERMINAL: authenticate_agent rejects any status other than 'approved', so the agent's token is refused on its next call, and admin_approve_agent cannot move it back. Already-leased jobs are NOT force-cancelled here — they wind down via the lease/fencing/reconcile path; this closes the door to NEW work. Admin- tier (the /api/admin/ middleware blocks agent-token auth). Idempotent: re- revoking an already-revoked agent returns 200 without a duplicate audit row. The request must carry the immutable enrollment id and reviewed public-key fingerprint from the current admin roster. A stale snapshot returns 409 and cannot revoke a replacement enrollment that reused the same agent id. 404 if the agent is unknown.

Permissions

HTTP request

POST https://<your-host>/api/admin/agents/{agent_id}/revoke

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: RevokeBody.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"enrollment_id":"<uuid>","public_key_fingerprint":"<string>"}' \
  'https://<your-host>/api/admin/agents/<agent_id>/revoke'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "agent_id": null,
  "enrollment_id": null,
  "public_key_fingerprint": null,
  "status": "<string>",
  "already_revoked": false
}

GET/api/admin/approval-groups-contract

admin access

Admin approval groups.

Permissions

HTTP request

GET https://<your-host>/api/admin/approval-groups-contract

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/approval-groups-contract'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "source": "<string>",
  "approvalGroupsMode": "<string>",
  "groupMappingReadOnly": false,
  "datacenterFallbackRequired": false,
  "delegationReviewRequired": false,
  "separationOfDutiesReviewRequired": false,
  "liveIdentityLookupAllowed": false,
  "graphCallsAllowed": false,
  "roleAssignmentMutationAllowed": false,
  "groupMembershipMutationAllowed": false,
  "approvalMutationAllowed": false,
  "policyMutationAllowed": false,
  "workflowMutationAllowed": false,
  "providerCallsAllowed": false,
  "notificationDispatchAllowed": false,
  "rawUserDataAllowed": false,
  "rawGroupDataAllowed": false,
  "rawMembershipRowsAllowed": false,
  "rawApprovalPayloadsAllowed": false,
  "rawProviderPayloadsAllowed": false,
  "rawRecipientDataAllowed": false,
  "tenantIdentifiersAllowed": false,
  "objectIdentifiersAllowed": false,
  "principalIdentifiersAllowed": false,
  "groupIdentifiersAllowed": false,
  "credentialValuesAllowed": false,
  "tokenValuesAllowed": false,
  "privateNetworkValuesAllowed": false,
  "groupScopes": [],
  "groupStates": [],
  "mappingDimensions": [],
  "requiredGuards": [],
  "blockedReasons": [],
  "requiredEvidence": [],
  "rules": []
}

GET/api/admin/delegation-boundary-contract

admin access

Admin delegation boundary.

Permissions

HTTP request

GET https://<your-host>/api/admin/delegation-boundary-contract

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/delegation-boundary-contract'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "source": "<string>",
  "delegationBoundaryMode": "<string>",
  "siteDelegationReadOnly": false,
  "roleScopeReadOnly": false,
  "approvalRouteReadOnly": false,
  "breakGlassReviewOnly": false,
  "liveDelegationChangeAllowed": false,
  "roleAssignmentMutationAllowed": false,
  "approvalMutationAllowed": false,
  "policyMutationAllowed": false,
  "workflowMutationAllowed": false,
  "graphCallsAllowed": false,
  "providerCallsAllowed": false,
  "notificationDispatchAllowed": false,
  "rawUserDataAllowed": false,
  "rawGroupDataAllowed": false,
  "rawDelegationRowsAllowed": false,
  "rawApprovalPayloadsAllowed": false,
  "rawProviderPayloadsAllowed": false,
  "rawRecipientDataAllowed": false,
  "tenantIdentifiersAllowed": false,
  "objectIdentifiersAllowed": false,
  "principalIdentifiersAllowed": false,
  "groupIdentifiersAllowed": false,
  "credentialValuesAllowed": false,
  "tokenValuesAllowed": false,
  "privateNetworkValuesAllowed": false,
  "delegationDomains": [],
  "delegationScopes": [],
  "delegationStates": [],
  "requiredGuards": [],
  "blockedReasons": [],
  "requiredEvidence": [],
  "rules": []
}

GET/api/admin/delegation-boundary-readiness

admin access

Dry-run admin delegation-boundary readiness.

Turns the static admin/delegation-boundary descriptor into a real decision: evaluate the boundary-review guards over a proposed delegation and return boundary-recorded (all criteria met; the live delegation change is a separately-approved step) or block. Never changes live delegation; evidence is referenced by summary only.

Permissions

HTTP request

GET https://<your-host>/api/admin/delegation-boundary-readiness

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/delegation-boundary-readiness'

GET/api/admin/feature-flag-governance-contract

admin access

Admin feature flag.

Permissions

HTTP request

GET https://<your-host>/api/admin/feature-flag-governance-contract

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/feature-flag-governance-contract'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "source": "<string>",
  "featureFlagGovernanceMode": "<string>",
  "flagCatalogReadOnly": false,
  "rolloutPlanReadOnly": false,
  "approvalRouteReadOnly": false,
  "auditSummaryOnly": false,
  "liveToggleAllowed": false,
  "rolloutMutationAllowed": false,
  "targetingMutationAllowed": false,
  "policyMutationAllowed": false,
  "workflowMutationAllowed": false,
  "providerCallsAllowed": false,
  "notificationDispatchAllowed": false,
  "rawFlagRowsAllowed": false,
  "rawTargetingRowsAllowed": false,
  "rawUserRowsAllowed": false,
  "rawGroupRowsAllowed": false,
  "rawAuditLogsAllowed": false,
  "rawProviderPayloadsAllowed": false,
  "rawRecipientDataAllowed": false,
  "credentialValuesAllowed": false,
  "tokenValuesAllowed": false,
  "tenantIdentifiersAllowed": false,
  "objectIdentifiersAllowed": false,
  "principalIdentifiersAllowed": false,
  "groupIdentifiersAllowed": false,
  "privateNetworkValuesAllowed": false,
  "flagScopes": [],
  "flagStates": [],
  "rolloutStrategies": [],
  "requiredGuards": [],
  "blockedReasons": [],
  "requiredEvidence": [],
  "rules": []
}

GET/api/admin/feature-flag-governance-readiness

admin access

Dry-run admin feature-flag governance readiness.

Turns the static admin/feature-flag-governance descriptor into a real decision: evaluate the governance guards over a proposed feature-flag change and return governance-recorded (all criteria met; the live toggle is a separately- approved step) or block. Never toggles a flag or mutates rollout/targeting.

Permissions

HTTP request

GET https://<your-host>/api/admin/feature-flag-governance-readiness

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/feature-flag-governance-readiness'

GET/api/admin/notifications/dispatch-outbox

admin access

Admin telemetry: the dry-run notification-dispatch outbox, newest first.

Optional ?status= (validated) and ?limit= (clamped 1..=200). Returns ONLY dispatch metadata — never a notification body/recipient/target. Admin-gated by the central /api/admin prefix; an explicit check is kept as defense-in-depth. Degrades to {"source":"no-db","dispatches":[]} without a DB.

Permissions

HTTP request

GET https://<your-host>/api/admin/notifications/dispatch-outbox

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/notifications/dispatch-outbox'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "source": null,
  "dispatches": null
}

GET/api/admin/platform-settings

admin access

Admin platform settings.

Permissions

HTTP request

GET https://<your-host>/api/admin/platform-settings

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Error responses use the platform ApiError body (error, message, optional detail).

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/platform-settings'

PUT/api/admin/platform-settings

admin access

Update admin platform settings.

Permissions

HTTP request

PUT https://<your-host>/api/admin/platform-settings

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: PlatformConfig.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Error responses use the platform ApiError body (error, message, optional detail).

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request PUT \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}' \
  'https://<your-host>/api/admin/platform-settings'

GET/api/admin/platform-settings/history

admin access

The change history of platform settings (#28).

The update/reset handlers (#6) write durable, hash-chained audit_log rows (platform-settings-update / platform-settings-reset); this surfaces them as a queryable history (who changed it, when, and the recorded NON-secret detail) without needing a separate config_history table — the append-only audit_log IS the history. Admin-tier read, newest first, bounded pagination. Empty + durable:false with no DB. (Active-vs-DB drift detection — flagging when the in-memory config diverges from the persisted row — remains a separate follow-up; this closes the change-history gap.)

Permissions

HTTP request

GET https://<your-host>/api/admin/platform-settings/history

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/platform-settings/history'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "history": null,
  "durable": false
}

POST/api/admin/platform-settings/reset

admin access

Reset admin platform settings.

Permissions

HTTP request

POST https://<your-host>/api/admin/platform-settings/reset

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Error responses use the platform ApiError body (error, message, optional detail).

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  'https://<your-host>/api/admin/platform-settings/reset'

GET/api/admin/rbac-roles

admin access

Admin rbac roles.

Permissions

HTTP request

GET https://<your-host>/api/admin/rbac-roles

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/rbac-roles'

GET/api/admin/sessions

admin access

List active (non-expired) browser sessions.

Permissions

HTTP request

GET https://<your-host>/api/admin/sessions

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Returns a paginated JSON object with total/limit/offset keys. Error responses use the platform ApiError body (error, message, optional detail).

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/sessions'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "sessions": null,
  "count": null,
  "total": null,
  "limit": null,
  "offset": null
}

DELETE/api/admin/sessions/{id}

admin access

Admin revoke of ANY session (closes the self-only gap in auth_logout).

Sessions are ephemeral, so a hard DELETE is acceptable here (unlike tokens, which are soft-revoked as evidence). 404 when absent.

Permissions

HTTP request

DELETE https://<your-host>/api/admin/sessions/{id}

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Error responses use the platform ApiError body (error, message, optional detail).

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request DELETE \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  'https://<your-host>/api/admin/sessions/<id>'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "status": "<string>",
  "id": null
}

GET/api/admin/sessions/{id}

admin access

Fetch a single browser session by id for inspection (#38).

Unlike the list (which shows only active sessions), this returns the row regardless of expiry so an operator can also inspect an expired session; expires_at reports its state. 404 when absent, 503 no DB.

Permissions

HTTP request

GET https://<your-host>/api/admin/sessions/{id}

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Error responses use the platform ApiError body (error, message, optional detail).

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/sessions/<id>'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "id": null,
  "user_id": null,
  "display_name": null,
  "roles": null,
  "provider": null,
  "created_at": null,
  "expires_at": null
}

GET/api/admin/site-registry-contract

admin access

Site registry contract.

Permissions

HTTP request

GET https://<your-host>/api/admin/site-registry-contract

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/site-registry-contract'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "source": "<string>",
  "providerCallsEnabled": false,
  "liveExecutionEnabled": false,
  "description": "<string>",
  "recommendedCodeSystem": "<string>",
  "supportedCodeSystems": [],
  "customCodeFormat": "<string>",
  "referenceData": "<string>",
  "endpoints": [],
  "activeSites": null,
  "referenceCountryExamples": []
}

GET/api/admin/sites

admin access

List site registry.

Permissions

HTTP request

GET https://<your-host>/api/admin/sites

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/sites'

POST/api/admin/sites

admin access

Create site registry.

Permissions

HTTP request

POST https://<your-host>/api/admin/sites

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: SiteRegistryCreateRequest.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"code":"<string>","codeSystem":{},"name":"<string>","country":"<string>","countryCode":"<string>","timezone":"<string>"}' \
  'https://<your-host>/api/admin/sites'

GET/api/admin/sites/countries

admin access

Site registry countries.

Permissions

HTTP request

GET https://<your-host>/api/admin/sites/countries

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/sites/countries'

GET/api/admin/sites/countries/{code}/cities

admin access

Site registry cities by country.

Permissions

HTTP request

GET https://<your-host>/api/admin/sites/countries/{code}/cities

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/sites/countries/<code>/cities'

GET/api/admin/sites/search

admin access

Site registry search.

Permissions

HTTP request

GET https://<your-host>/api/admin/sites/search

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/sites/search?q=<q>'

GET/api/admin/sites/{code}

admin access

Get site registry.

Permissions

HTTP request

GET https://<your-host>/api/admin/sites/{code}

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/sites/<code>'

POST/api/admin/sites/{code}/activate

admin access

Site registry activate.

Permissions

HTTP request

POST https://<your-host>/api/admin/sites/{code}/activate

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  'https://<your-host>/api/admin/sites/<code>/activate'

POST/api/admin/sites/{code}/deactivate

admin access

Site registry deactivate.

Permissions

HTTP request

POST https://<your-host>/api/admin/sites/{code}/deactivate

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  'https://<your-host>/api/admin/sites/<code>/deactivate'

GET/api/admin/tokens

admin access

List token metadata with the hash REDACTED.

Reads are not gated by the central ROUTE_PERMISSIONS table this wave, so the handler enforces the admin gate explicitly (these reads expose token metadata).

Permissions

HTTP request

GET https://<your-host>/api/admin/tokens

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Returns a paginated JSON object with total/limit/offset keys. Error responses use the platform ApiError body (error, message, optional detail).

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/admin/tokens'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "tokens": null,
  "count": null,
  "total": null,
  "limit": null,
  "offset": null
}

POST/api/admin/tokens

admin access

Mint a service-account credential.

The plaintext ryk_... token is returned EXACTLY ONCE in this response and is never persisted (only its SHA-256 hash) or logged.

Permissions

HTTP request

POST https://<your-host>/api/admin/tokens

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: CreateTokenRequest.

Response

201 response body

Structure: Value.

201 response headers

Error responses use the platform ApiError body (error, message, optional detail).

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Ryuki-Session-Id: <session-id>' \
  --data '{"name":"<string>","owner_principal":"<string>"}' \
  'https://<your-host>/api/admin/tokens'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 201

{
  "id": null,
  "name": null,
  "owner_principal": null,
  "roles": null,
  "site_scope": null,
  "environment_scope": null,
  "token_valid": null,
  "expires_at": null,
  "created_at": null,
  "token": null
}

DELETE/api/admin/tokens/{id}

admin access

Soft-revoke (sets revoked_at).

404 when no active token by that id (already-revoked or absent are indistinguishable to the caller). Never a hard DELETE: the row survives as evidence.

Permissions

HTTP request

DELETE https://<your-host>/api/admin/tokens/{id}

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.