API reference
This interactive reference is generated directly from the control plane's OpenAPI 3.1 specification (apps/control-plane/openapi.json) — the same spec served at runtime from GET /api/v1/openapi.json and published as a release asset. It is always in sync with the implementation (a CI drift gate enforces it).
For authentication, error envelopes, and pagination conventions, read the API overview first.
Multi-tenant AI agent platform management API.
Authentication
- Human operators — OIDC browser flow via
GET /auth/login→/auth/callback. Session cookie is set server-side. - CLI operators — Device authorization grant via
POST /auth/device. The CLI opens the returnedverificationUriin the operator's browser, pollsGET /auth/device/token, and persists the issued token in~/.config/opencrane/credentials.json. - Automation / CI — Bearer token via the
OPENCRANE_TOKENenvironment variable, validated against theOPENCRANE_API_TOKENserver-side env var. - Endpoints tagged Auth and Meta (
/auth/*,/openapi.json) require no credentials.
Servers
Show the configured platform DNS-01 issuer (ClusterIssuer or namespaced Issuer)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Query Parameters
Responses
Current issuer status.
Configure the platform DNS-01 issuer for wildcard TLS (ClusterIssuer or namespaced Issuer)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Request Body
Responses
Issuer configured.
Show the fleet awareness contract rollout state
Authorizations
Static bearer token. Pass as Authorization: Bearer
Responses
Current rollout state.
Define (or redefine) the awareness rollout; resets the frontier
Authorizations
Static bearer token. Pass as Authorization: Bearer
Request Body
Responses
Rollout defined.
Advance the rollout frontier (one wave, or up to a named wave)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Request Body
Responses
Frontier advanced.
One-step rollback: return every wave to the stable version
Authorizations
Static bearer token. Pass as Authorization: Bearer
Responses
Rolled back.
Resolve the awareness contract version a tenant runs
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Resolved version.
Fleet participation, drift, and policy-violation monitoring
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Query Parameters
"critical""warning"Responses
Fleet participation report.
Inspect a chat-window session's awareness scope binding
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Current session scope binding.
Bind a session scope (CP intersects with the principal's entitlements)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Request Body
Responses
Authorised binding; rejected lists any over-scope dropped.
Clear a session's scope binding
List all tenants
Authorizations
Static bearer token. Pass as Authorization: Bearer
Responses
Tenant list.
Create a new tenant (dual-write: K8s CRD + database)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Request Body
Responses
Tenant created.
Detect drift between Tenant CRDs and PostgreSQL projection rows
Repair Tenant projection rows from CRD source of truth
Get a single tenant by name
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Tenant detail.
Update a tenant (dual-write: K8s CRD + database)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Request Body
Responses
Tenant updated.
Delete a tenant (dual-write: K8s CRD + database)
Suspend a tenant (scale deployment to zero)
Resume a suspended tenant
Get dataset memberships for a tenant
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Dataset memberships.
Update dataset memberships for a tenant
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Request Body
Responses
Dataset memberships updated.
Compile the effective awareness, MCP, and skill contract for a tenant
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Effective contract.
List all access policies
Authorizations
Static bearer token. Pass as Authorization: Bearer
Responses
Policy list.
Create an access policy (dual-write: K8s CRD + database)
Detect drift between AccessPolicy CRDs and PostgreSQL projection rows
Repair AccessPolicy projection rows from CRD source of truth
Get a single access policy by name
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Policy detail.
Update an access policy
Delete an access policy
List all cluster tenants
Authorizations
Static bearer token. Pass as Authorization: Bearer
Responses
Cluster tenant list.
Create a cluster tenant (rejects an isolation tier no provisioner can serve)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Request Body
Responses
Cluster tenant created.
Get a single cluster tenant by name
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Cluster tenant detail.
Update a cluster tenant (re-gates the isolation tier when it changes)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Request Body
Responses
Cluster tenant updated.
Delete a cluster tenant
Get the observed status of a cluster tenant
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Cluster tenant status.
List all MCP servers with grants and credentials
Authorizations
Static bearer token. Pass as Authorization: Bearer
Responses
MCP server list.
Create a new MCP server
Authorizations
Static bearer token. Pass as Authorization: Bearer
Request Body
Responses
MCP server created.
Get a single MCP server by identifier
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
MCP server detail.
Update an MCP server and fully replace grants and credentials
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Request Body
Responses
MCP server updated.
Delete an MCP server and its linked grant rows
List the brokered credentials of an MCP server
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Credential list.
Add a brokered credential to an MCP server (does not touch grants)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Request Body
Responses
Credential added.
Remove a single brokered credential from an MCP server
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Credential deleted.
List all groups with member counts and awareness grants
Create a new group and optional awareness grants
Authorizations
Static bearer token. Pass as Authorization: Bearer
Request Body
Responses
Group created.
Get a single group by identifier
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Group detail.
Update a group and replace awareness grants
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Request Body
Responses
Group updated.
Delete a group and its awareness grants
List all skill bundles with entitlements and promotion history
Authorizations
Static bearer token. Pass as Authorization: Bearer
Responses
Skill bundle list.
Create a new skill bundle
Backfill all published bundles' content into the OCI store (P4D.2)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Responses
Backfill summary with per-bundle outcomes.
Get a single skill bundle by identifier
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Skill bundle detail.
Update a skill bundle and fully replace entitlements and promotions
Delete a skill bundle and its linked entitlement grants
List all third-party sources
Register a new third-party source
Get a single third-party source
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Responses
Source detail.
Update a third-party source
Delete a third-party source and its linked items
List all issued access tokens (hashes only, never plaintext)
Create a new access token. Returns plaintext token once — store it securely.
Authorizations
Static bearer token. Pass as Authorization: Bearer
Request Body
Responses
Token created. The plainTextToken field will not be returned again.
Revoke and delete an access token
Provider Keys
List configured provider API keys (configured status only, never the key value)
Create or update a provider API key
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Request Body
Responses
Key updated.
Delete a configured provider API key
Get global monthly spend ceiling
Update the global monthly spend ceiling
List all per-account monthly spend ceilings
Create or update the budget ceiling for a specific account
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Path Parameters
Request Body
Responses
Account budget updated.
Remove the per-account budget ceiling
Get current spend and budget state for a tenant
Get LiteLLM virtual key metadata for a tenant (never the key value)
Revoke the LiteLLM virtual key for a tenant
Query audit log entries with optional tenant filter and cursor pagination
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Query Parameters
Filter to a specific tenant.
Maximum entries to return.
10011000Opaque cursor from a previous response for keyset pagination.
Responses
Paginated audit entries.
List token usage records
Authorizations
Static bearer token. Pass as Authorization: Bearer
Parameters
Query Parameters
100Responses
Token usage records.
Get latest server utilisation snapshot (CPU, memory, storage, active tenants)
Authorizations
Static bearer token. Pass as Authorization: Bearer
Responses
Server utilisation snapshot.
Get projection drift metrics with threshold evaluation and alert state
Return current auth mode and authenticated user identity (if any)
No authentication required. Returns 200 with the current session or an anonymous identity when no session is established.
Responses
Auth status.
Exchange the current OIDC session for a short-lived token to the caller's OpenClaw pod
Single sign-on across the control plane and the tenant pod: requires an established OIDC session (cookie) and returns a short-lived, audience-bound token minted via the Kubernetes TokenRequest API for the caller's tenant. The token targets the OpenClaw pod's session audience (reachable at ingressHost) — it is NOT an obot-gateway token; Obot is called only from inside the pod. The tenant is resolved solely from the session's verified email, so a caller cannot obtain a token for another user's pod. Re-call before expiresAt; re-login only when the session itself expires. Returns 401 without a session, 403 when no tenant matches the session email, 409 when the pod has no ingress host yet or when the email maps to more than one tenant.
Responses
Short-lived pod access token.
Redirect the browser to the configured OIDC identity provider to start login
OIDC authorization callback — validates the response and establishes a session
Destroy the current session
Initiate a CLI device authorization grant
Returns a device code and short user code. The CLI prints the verificationUri for the operator to open in a browser. No credentials required.
Responses
Device grant created.
Activate a device grant in the browser (requires OIDC session)
The operator opens this URL after a CLI login prompt. If no OIDC session is present the user is redirected to the identity provider first. On success an access token is created and the CLI poll endpoint unblocks.
Parameters
Query Parameters
Short user code from the CLI prompt (e.g. ABCD-1234).
Responses
Grant activated. HTML confirmation page returned.
Poll for the access token after browser activation
Returns 202 while pending, 200 with token when authorized, 410 when the grant has expired. The token is delivered exactly once.
Parameters
Query Parameters
Secret device code returned by POST /auth/device.
Responses
Grant authorized — token ready.