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
Billing
billing.account.update
Update the workspace billing contact and invoice address.
| REST | PATCH /api/v1/workspace/billing/account → 204 |
| Scope | billing:write — and a role that may manage-billing. |
| Danger | write |
| MCP tool | billing_account_update |
| CLI | cbox id billing account update |
| Input | Type | Required | Description |
|---|---|---|---|
billing_email |
string (email) | yes | At most 254 characters. |
invoice_name |
string | yes | At most 255 characters. |
address_line1 |
string | yes | At most 255 characters. |
address_line2 |
string, nullable | no | At most 255 characters. |
postal_code |
string | yes | At most 32 characters. |
city |
string | yes | At most 255 characters. |
country |
string | yes | One of AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW. |
tax_id |
string, nullable | no | At most 64 characters. |
billing.payment_method.default
Choose the workspace default payment card.
| REST | PATCH /api/v1/workspace/billing/payment-methods/{id}/default → 204 |
| Scope | billing:write — and a role that may manage-billing. |
| Danger | write |
| MCP tool | billing_payment_method_default |
| CLI | cbox id billing payment_method default <id> |
| Input | Type | Required | Description |
|---|---|---|---|
id |
string (path) | yes | At most 255 characters. |
billing.payment_method.remove
Remove an unneeded payment card from this workspace.
| REST | DELETE /api/v1/workspace/billing/payment-methods/{id} → 204 |
| Scope | billing:write — and a role that may manage-billing. |
| Danger | write |
| MCP tool | billing_payment_method_remove |
| CLI | cbox id billing payment_method remove <id> |
| Input | Type | Required | Description |
|---|---|---|---|
id |
string (path) | yes | At most 255 characters. |
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 — and a role that may read-environments. |
| 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 | Optional lower allowance; it cannot exceed your account access. 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 — and a role that may read-environments. |
| 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 | |
environment_access_version |
string | 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. |
roles |
list of string | yes |
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 native ID app roles while preserving shared organization membership and other apps. The current owner cannot be removed.
| 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 | |
roles_version |
string | yes |
team.role
Replace native ID app roles atomically. Shared organization membership is preserved.
| 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 | |
roles |
list of string | yes | |
roles_version |
string | yes |
team.transfer_ownership
Transfer shared organization ownership. Existing app roles are preserved; the previous owner may lose native ID access. Only the current 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 current workspace identity: its id, name and status. No operational or financial records.
| 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 own-organization and 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. |