Skip to content
← Cbox ID 2.0.0 View on GitHub

Workspace actions

Workspace actions

The workspace plane is the customer's own Cbox account, above every environment it owns: projects, environments (and their custom domains), the team, workspace keys and the keys of each environment. It is served on the platform root and resolves no environment.

Every row below is one action, reached through four doors that run the same code, with the same authorization, validation, approvals and Audit log entry: the console, the REST API, the MCP server and the cbox CLI. See Actions for how that works and Planes and hosts for where each plane is served.
REST https://<root-host>/api/v1/workspace/… with Authorization: Bearer cbid_ws_… (a workspace key, whose role must also allow the action), or a team member's token from the root
MCP /mcp on the platform root, signed in as a member of the workspace's team, or with a workspace key
CLI cbox login at the root, then the command below
OpenAPI /api/v1/workspace/openapi.yaml on the host above — public, no key needed (source); every operation carries x-action, x-scope and x-danger

Danger is how much harm the action can do in the wrong hands: read only reads; write changes something another write can undo; destructive removes or revokes; critical mints credentials, takes over access or changes how people sign in. MCP clients are told a destructive or critical tool is destructive, the CLI asks before running one, and an approval policy keys on it.

Contents

Area Actions
Environments environments.create, environments.domain.remove, environments.domain.request, environments.domain.verify, environments.list
Keys keys.environment.create, keys.environment.revoke, keys.workspace.create, keys.workspace.list, keys.workspace.revoke
Projects projects.create, projects.list, projects.reactivate, projects.rename, projects.suspend, projects.verification.resend
Team team.environment_access, team.invitations.list, team.invitations.resend, team.invitations.revoke, team.invite, team.list, team.remove, team.role, team.transfer_ownership
Workspace workspace.get, workspace.settings.update

Environments

environments.create

Create an environment under one of the workspace's projects; with initial_key, also mint its first management key, returned once as initial_key.token.
REST POST /api/v1/workspace/environments → 201
Scope environments:write — and a role that may manage-environments.
Danger critical
MCP tool environments_create
CLI cbox id environments create
Secret data.initial_key.token — shown once, never kept for an idempotent replay
Input Type Required Description
name string yes At most 120 characters.
type string no Default production. One of production, sandbox.
project_id string no The project (billing anchor) to create it under. Defaults to the workspace's first project. At most 64 characters.
initial_key object no Mint the environment's first management key in the same call. Its value is returned once, as initial_key.token.
initial_key.name string yes At most 120 characters.
initial_key.scopes list of string yes The environment-key scopes it carries, for example apis:write. At least 1 items. At most 64 items.
initial_key.expires_at string (date-time), nullable no When it stops working. Left out, it does not expire.

environments.domain.remove

Stop serving one of the workspace's environments on its custom domain. Anything using that domain stops reaching it.
REST DELETE /api/v1/workspace/environments/{environment_id}/domain → 204
Scope environments:write — and a role that may manage-environments.
Danger destructive
MCP tool environments_domain_remove
CLI cbox id environments domain remove <environment_id>
Input Type Required Description
environment_id string (path) yes

environments.domain.request

Start serving one of the workspace's environments on a custom domain: returns the DNS TXT record that proves you control it.
REST POST /api/v1/workspace/environments/{environment_id}/domain → 200
Scope environments:write — and a role that may manage-environments.
Danger write
MCP tool environments_domain_request
CLI cbox id environments domain request <environment_id>
Input Type Required Description
environment_id string (path) yes
domain string yes The domain, for example login.example.com. At most 253 characters.

environments.domain.verify

Look for the pending domain's DNS TXT record and, once it is visible, serve the environment on that domain.
REST POST /api/v1/workspace/environments/{environment_id}/domain/verify → 200
Scope environments:write — and a role that may manage-environments.
Danger write
MCP tool environments_domain_verify
CLI cbox id environments domain verify <environment_id>
Input Type Required Description
environment_id string (path) yes

environments.list

List every environment the workspace owns, across its projects, with each one's issuer.
REST GET /api/v1/workspace/environments → 200
Scope workspace:read — (any role).
Danger read
MCP tool environments_list
CLI cbox id environments list
Input Type Required Description
limit integer no Items per page, 1–100. Default 50.
page integer no The page to read, from 1. A list says next_page when there is one.

Keys

keys.environment.create

Mint a management key for one of the workspace's environments, with the scopes it needs. The value is returned once, as token.
REST POST /api/v1/workspace/environments/{environment_id}/keys → 201
Scope keys:write — and a role that may manage-environments.
Danger critical
MCP tool keys_environment_create
CLI cbox id keys environment create <environment_id>
Secret data.token — shown once, never kept for an idempotent replay
Input Type Required Description
environment_id string (path) yes
name string yes At most 120 characters.
scopes list of string yes The environment-key scopes it carries, for example apis:write. At least 1 items. At most 64 items.
expires_at string (date-time), nullable no When it stops working. Left out, it does not expire.

keys.environment.revoke

Revoke one of an environment's management keys; whatever uses it stops immediately.
REST DELETE /api/v1/workspace/environments/{environment_id}/keys/{id} → 204
Scope keys:write — and a role that may manage-environments.
Danger destructive
MCP tool keys_environment_revoke
CLI cbox id keys environment revoke <environment_id> <id>
Input Type Required Description
environment_id string (path) yes
id string (path) yes

keys.workspace.create

Mint a workspace key with a role and optional scopes, never wider than the caller. The value is returned once, as token.
REST POST /api/v1/workspace/keys → 201
Scope keys:write — and a role that may manage-environments and manage-members.
Danger critical
MCP tool keys_workspace_create
CLI cbox id keys workspace create
Secret data.token — shown once, never kept for an idempotent replay
Input Type Required Description
name string yes At most 120 characters.
role string yes One of admin, developer, member, viewer.
scopes list of string, nullable no Narrow the key below its role. Left out, the role alone bounds it — or, minted by a key with scopes, that key's scopes. At least 1 items.
expires_at string (date-time), nullable no When it stops working. Left out, it does not expire — or, minted by a key that does, expires with it.

keys.workspace.list

List the workspace's keys, newest first, revoked ones included — names, roles, scopes and expiry, never their values.
REST GET /api/v1/workspace/keys → 200
Scope workspace:read — and a role that may manage-members.
Danger read
MCP tool keys_workspace_list
CLI cbox id keys workspace list
Input Type Required Description
limit integer no Items per page, 1–100. Default 50.
page integer no The page to read, from 1. A list says next_page when there is one.

keys.workspace.revoke

Revoke a workspace key, and every key it minted on either plane (workspace keys and environment management keys, all the way down); whatever uses them stops immediately.
REST DELETE /api/v1/workspace/keys/{id} → 204
Scope keys:write — and a role that may manage-environments and manage-members.
Danger destructive
MCP tool keys_workspace_revoke
CLI cbox id keys workspace revoke <id>
Input Type Required Description
id string (path) yes

Projects

projects.create

Create a project: another independently-billed IdP product, with its own environment allowance.
REST POST /api/v1/workspace/projects → 201
Scope projects:write — and a role that may manage-environments.
Danger write
MCP tool projects_create
CLI cbox id projects create
Input Type Required Description
name string yes At most 120 characters.
environment_limit integer no This project's plan environment allowance (default 2). At least 1. At most 100.

projects.list

List the workspace's projects (IdP products), each with its environment allowance and how much of it is used.
REST GET /api/v1/workspace/projects → 200
Scope workspace:read — (any role).
Danger read
MCP tool projects_list
CLI cbox id projects list

Takes no input.

projects.reactivate

Reactivate a suspended project, so environments can be added to it again.
REST POST /api/v1/workspace/projects/{id}/reactivate → 200
Scope projects:write — and a role that may manage-environments.
Danger write
MCP tool projects_reactivate
CLI cbox id projects reactivate <id>
Input Type Required Description
id string (path) yes

projects.rename

Rename a project.
REST PATCH /api/v1/workspace/projects/{id} → 200
Scope projects:write — and a role that may manage-environments.
Danger write
MCP tool projects_rename
CLI cbox id projects rename <id>
Input Type Required Description
id string (path) yes
name string yes At most 120 characters.

projects.suspend

Suspend a project: its environments stay live, but no new ones can be added until it is reactivated.
REST POST /api/v1/workspace/projects/{id}/suspend → 200
Scope projects:write — and a role that may manage-environments.
Danger write
MCP tool projects_suspend
CLI cbox id projects suspend <id>
Input Type Required Description
id string (path) yes

projects.verification.resend

Re-send the signup confirmation the workspace's first environment is waiting on, to the owner's address on file.
REST POST /api/v1/workspace/projects/verification/resend → 200
Scope projects:write — and a role that may manage-environments.
Danger write
MCP tool projects_verification_resend
CLI cbox id projects verification resend

Takes no input.

Team

team.environment_access

Set which of the workspace's environments a team member reaches: all of them, or the listed ones.
REST PUT /api/v1/workspace/members/{id}/access → 200
Scope team:write — and a role that may manage-members.
Danger write
MCP tool team_environment_access
CLI cbox id team environment_access <id>
Input Type Required Description
id string (path) yes
all_environments boolean yes True: every environment, including ones created later.
environment_ids list of string no With all_environments false: the environments they reach.

team.invitations.list

List the team's pending invitations, newest first.
REST GET /api/v1/workspace/invitations → 200
Scope team:read — and a role that may read-members.
Danger read
MCP tool team_invitations_list
CLI cbox id team invitations list

Takes no input.

team.invitations.resend

Re-send a pending team invitation with a fresh link; the earlier link stops working and the invitation gets a new id.
REST POST /api/v1/workspace/invitations/{id}/resend → 200
Scope team:write — and a role that may manage-members.
Danger write
MCP tool team_invitations_resend
CLI cbox id team invitations resend <id>
Input Type Required Description
id string (path) yes

team.invitations.revoke

Withdraw a pending team invitation; its link stops working.
REST DELETE /api/v1/workspace/invitations/{id} → 204
Scope team:write — and a role that may manage-members.
Danger destructive
MCP tool team_invitations_revoke
CLI cbox id team invitations revoke <id>
Input Type Required Description
id string (path) yes

team.invite

Invite somebody onto the workspace's team with a role; they get a mail with a link to set a password.
REST POST /api/v1/workspace/members → 201
Scope team:write — and a role that may manage-members.
Danger write
MCP tool team_invite
CLI cbox id team invite
Input Type Required Description
email string (email) yes At most 190 characters.
name string, nullable no At most 120 characters.
role string yes One of admin, developer, member, viewer.

team.list

List the workspace's team: each member's name, address, role and whether they reach every environment.
REST GET /api/v1/workspace/members → 200
Scope team:read — and a role that may read-members.
Danger read
MCP tool team_list
CLI cbox id team list
Input Type Required Description
limit integer no Items per page, 1–100. Default 50.
page integer no The page to read, from 1. A list says next_page when there is one.

team.remove

Remove a member from the workspace's team. The owner is never removed; transfer ownership first.
REST DELETE /api/v1/workspace/members/{id} → 204
Scope team:write — and a role that may manage-members.
Danger destructive
MCP tool team_remove
CLI cbox id team remove <id>
Input Type Required Description
id string (path) yes

team.role

Change a team member's role (admin, developer, member or viewer). The owner's role changes only by transferring ownership.
REST PATCH /api/v1/workspace/members/{id}/role → 200
Scope team:write — and a role that may manage-members.
Danger write
MCP tool team_role
CLI cbox id team role <id>
Input Type Required Description
id string (path) yes
role string yes One of admin, developer, member, viewer.

team.transfer_ownership

Make another member the workspace's owner; the current owner stays on as an admin. Only the owner, signed in, may do this.
REST POST /api/v1/workspace/members/{id}/transfer-ownership → 204
Scope team:write — and a role that may manage-members.
Danger critical
MCP tool team_transfer_ownership
CLI cbox id team transfer_ownership <id>
Input Type Required Description
id string (path) yes

Workspace

workspace.get

Get the workspace: its name and status, and each project's plan for a role that may read billing.
REST GET /api/v1/workspace → 200
Scope workspace:read — (any role).
Danger read
MCP tool workspace_get
CLI cbox id workspace get

Takes no input.

workspace.settings.update

Rename the workspace.
REST PATCH /api/v1/workspace → 200
Scope settings:write — and a role that may manage-members.
Danger write
MCP tool workspace_settings_update
CLI cbox id workspace settings update
Input Type Required Description
name string yes At most 120 characters.
← Previous Environment actions Next → Account actions