Skip to main content
The control-plane admin API is for authorized self-host operators who need break-glass or support workflows. It is disabled by default and is served under:
Replace example.com with your deployment domain. Only enable it when you have a process for storing admin tokens and auditing their use. Only the API host routes /admin. The management console host must not proxy admin endpoints, and ordinary workspace sessions are not admin credentials. The platform admin console uses its internal BFF credential together with a separately authenticated platform-admin session.

​
Enablement

For Kubernetes, enable the chart value and load token descriptors from the platform Secret:
For VM Compose:
CONTROL_PLANE_ADMIN_TOKENS_JSON contains hash descriptors, not raw tokens. Generate raw tokens out of band, store only the SHA-256 hash in the descriptor, and deliver the raw token through your operator secret channel. Production startup rejects enabled admin API configuration with no enabled token descriptors, invalid hashes, duplicate ids, unsupported scopes, or placeholder hash values.

​
Auth and scopes

Every request uses:
Machine requests use named admin bearer tokens. Ordinary workspace cookies, internal service tokens, run-scoped JWTs and agent keys do not grant admin access. Human platform-admin requests retain their role, CSRF and recent-authentication checks through the admin console BFF. Scopes are separate from workspace roles. Use the narrowest descriptor scopes possible:

​
Mutations and audit

Mutating admin requests require a reason:
Each mutation writes an admin audit event. Workspace-scoped mutations also write workspace audit events with actor.type=admin_token and the admin token id. Audit metadata is sanitized and must not contain raw tokens, prompts, message bodies, authorization headers, full tool arguments, or agent keys. The target credential endpoint is the only admin response that returns target bootstrap secret material:
For Kubernetes targets, the replacement AgentK key is returned once. For VM targets, the same administrative action returns a 15-minute one-use AgentV replacement enrollment command and never returns the durable AgentV credential. Both responses use Cache-Control: no-store.

​
Workspace plans and quotas

Configure deployment-wide workspace plans in Kubernetes:
For VM Compose, set the equivalent WORKSPACE_PLANS_CONFIG_JSON. Admins can change a workspace plan or set nullable quota overrides through PATCH /admin/v1/workspaces/{workspaceId}/plan and PATCH /admin/v1/workspaces/{workspaceId}/quotas. The control plane rejects changes that would place current workspace usage over the resulting effective limit unless you explicitly select overLimitBehavior: "retain_existing". Plan changes preserve explicit resource overrides. Execution limits are configured per plan, with five independent pools; see Workspace execution capacity.

​
Workspace suspension holds

A workspace can have one administrative hold and one external hold. Either hold suspends access. Clearing your hold does not clear the other, and the original suspension time remains while access stays blocked. Suspension cancels queued work and requests cancellation of executing work; restore never replays cancelled attempts. Private administrative reasons remain in administrative records. Members receive only the public suspension message and minimal workspace identity. Narrow external controllers must explicitly use source: "external"; the admin console manages source: "admin". Machine policy changes require requestId and expectedPolicyVersion. Any caller supplying a request ID must also supply a version. Legacy broad callers may omit both. Retrying an unchanged request returns its original outcome for 30 days. After a version conflict, read current policy before submitting a new request.