Environment actions

The environment plane is everything inside one environment: its organizations, users, applications, APIs, keys, sign-in configuration and governance. It is served on the environment's own host.

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://<environment-host>/api/v1/… with Authorization: Bearer cbid_env_… (a secret key of that environment), or a token a person delegated. At the platform root, a team member's token names the environment in a Cbox-Environment header
MCP	/mcp on the environment's host. At the platform root's /mcp, every environment tool takes an environment argument (an id or slug from whoami)
CLI	cbox login, cbox id use <environment>, then the command below — or CBOX_ID_ENDPOINT + CBOX_ID_TOKEN=cbid_env_… for CI
OpenAPI	/api/v1/environment/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
Admin Portal	organizations.portal_links.create, organizations.portal_links.list, organizations.portal_links.revoke
API keys	api_keys.list, api_keys.revoke
APIs	apis.create, apis.delete, apis.get, apis.list, apis.scopes.define, apis.scopes.remove, apis.update
App audit logs	audit_logs.events.create, audit_logs.events.list, audit_logs.exports.create, audit_logs.exports.get, audit_logs.schemas.create, audit_logs.schemas.delete, audit_logs.schemas.get, audit_logs.schemas.list, audit_logs.schemas.update, audit_logs.settings.get, audit_logs.settings.update, audit_logs.verify
Applications	apps.blueprint, apps.copy, apps.create, apps.delete, apps.get, apps.list, apps.manifest.set, apps.manifest.sync, apps.scopes.set, apps.secrets.list, apps.secrets.revoke, apps.secrets.rotate, apps.settings.api_key_prefix, apps.settings.backchannel_logout, apps.settings.token_exchange, apps.settings.token_lifetime, apps.update
Approvals	approvals.deny, approvals.list
Audit log	audit.list
Branding	branding.appearance.get, branding.appearance.set, branding.whitelabel.get, branding.whitelabel.set
Directory Sync	directories.connect, directories.create, directories.delete, directories.get, directories.groups.list, directories.groups.map, directories.list, directories.status.set, directories.token.rotate, directories.update
Domains	domains.add, domains.get, domains.remove, domains.verify
Enterprise SSO	sso.connections.activate, sso.connections.certificates.activate, sso.connections.certificates.list, sso.connections.certificates.stage, sso.connections.create, sso.connections.delete, sso.connections.disable, sso.connections.get, sso.connections.list, sso.connections.require_sso, sso.connections.update, sso.domains.capture, sso.domains.create, sso.domains.delete, sso.domains.list, sso.domains.verify, sso.saml_metadata.import
Events	events.list
Governance	access_reviews.close, access_reviews.create, access_reviews.get, access_reviews.items.decide, access_reviews.items.list, access_reviews.list, sod_policies.create, sod_policies.delete, sod_policies.get, sod_policies.list, sod_policies.status.set
Hooks	hooks.create, hooks.delete, hooks.get, hooks.list, hooks.update
Invitations	invitations.list, invitations.resend, invitations.revoke, invitations.send
Legacy login	legacy_login.approve, legacy_login.get, legacy_login.probe, legacy_login.revoke
Log streams	log_streams.create, log_streams.delete, log_streams.get, log_streams.list, log_streams.test, log_streams.update
Members	members.add, members.list, members.remove, members.update
Organizations	organizations.create, organizations.delete, organizations.domains.add, organizations.domains.capture, organizations.domains.list, organizations.domains.remove, organizations.domains.verify, organizations.get, organizations.list, organizations.reactivate, organizations.suspend, organizations.transfer_ownership, organizations.update
Outbound provisioning	provisioning.targets.create, provisioning.targets.delete, provisioning.targets.get, provisioning.targets.list, provisioning.targets.status.set
Publishable keys	frontend_keys.create, frontend_keys.list, frontend_keys.revoke, frontend_keys.set_origins
Roles	members.roles.grant, members.roles.list, members.roles.revoke, permissions.create, permissions.delete, permissions.list, permissions.update, roles.create, roles.delete, roles.get, roles.list, roles.permissions.grant, roles.permissions.revoke, roles.update, users.environment_roles.get, users.environment_roles.grant, users.environment_roles.list, users.environment_roles.revoke
SAML apps	saml_apps.create, saml_apps.delete, saml_apps.get, saml_apps.list, saml_apps.update
Secret keys	keys.create, keys.list, keys.revoke, keys.rotate
Sign-in	signin.policy.get, signin.policy.inherit, signin.policy.update, signin.self_service_signup.set, signin.social.delete, signin.social.list, signin.social.set
Support sessions	support_sessions.end, support_sessions.start
Token vault	token_vault.grants.create, token_vault.grants.delete, token_vault.secrets.create, token_vault.secrets.get, token_vault.secrets.list, token_vault.secrets.revoke, token_vault.secrets.rotate
Users	users.create, users.deactivate, users.erase, users.get, users.list, users.mfa.reset, users.password.set, users.password_reset.send, users.reactivate, users.sessions.list, users.sessions.revoke, users.sessions.revoke_all, users.update, users.verification.send, users.verify
Webhooks	webhooks.create, webhooks.delete, webhooks.get, webhooks.list, webhooks.pause, webhooks.resume, webhooks.secret.rotate, webhooks.signature_scheme.change, webhooks.update

Admin Portal

organizations.portal_links.create

Create a one-time Admin Portal link an organization's IT administrator uses to set up SSO, directory sync, domain verification, log streams or SAML certificate renewal, or to read its audit logs, without an account. The URL is shown once.

REST	POST /api/v1/organizations/{organization_id}/portal-links → 201
Scope	portal_links:write — required of the key or token.
Danger	critical
MCP tool	organizations_portal_links_create
CLI	cbox id organizations portal_links create <organization_id>
Secret	data.url — shown once, never kept for an idempotent replay

Input	Type	Required	Description
organization_id	string (path)	yes	The organization the link sets up. At most 64 characters.
intents	list of string	yes	What the link may set up: sso (connection and email domains), dsync (directory sync over SCIM), domain_verification, log_streams, certificate_renewal (a SAML connection's signing certificate), audit_logs (the organization's audit events, read-only, with CSV export). At least 1 items.
expires_in_minutes	integer, nullable	no	How long the link may wait to be opened, in minutes — 5 to 10080 (a week). Left out, the deployment's default (30). At least 5. At most 10080.
email	string (email), nullable	no	Mail the link to this address — the customer's IT contact. Left out, nothing is sent. At most 254 characters.
locale	string, nullable	no	The language of that mail. Left out, the environment's default language. One of en, da, de, sv, nb, fr.

organizations.portal_links.list

List an organization's Admin Portal links from the last 30 days, newest first: what each opens, who minted it, whom it was mailed to, and whether it is pending, in use, completed, expired or revoked. Never the URL.

REST	GET /api/v1/organizations/{organization_id}/portal-links → 200
Scope	portal_links:read — required of the key or token.
Danger	read
MCP tool	organizations_portal_links_list
CLI	cbox id organizations portal_links list <organization_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.

organizations.portal_links.revoke

Withdraw an Admin Portal link: it can no longer be opened, and a setup session it already opened ends on its next request. What was already set up through it stays.

REST	DELETE /api/v1/organizations/{organization_id}/portal-links/{id} → 204
Scope	portal_links:write — required of the key or token.
Danger	destructive
MCP tool	organizations_portal_links_revoke
CLI	cbox id organizations portal_links revoke <organization_id> <id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
id	string (path)	yes	The portal link's id. At most 64 characters.

API keys

api_keys.list

List the API keys an organization's members created for your apps, a page at a time. Never the key material.

REST	GET /api/v1/organizations/{organization_id}/api-keys → 200
Scope	api_keys:read — required of the key or token.
Danger	read
MCP tool	api_keys_list
CLI	cbox id api_keys list <organization_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
client_id	string	no	Only the keys for this app's API. At most 255 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

api_keys.revoke

Revoke an API key an organization's member created for your app. Whatever uses it stops working at once.

REST	DELETE /api/v1/api-keys/{id} → 204
Scope	api_keys:write — required of the key or token.
Danger	destructive
MCP tool	api_keys_revoke
CLI	cbox id api_keys revoke <id>

Input	Type	Required	Description
id	string (path)	yes	The API key id. At most 64 characters.
organization_id	string, nullable	no	The organization it must belong to; a key elsewhere is not found. At most 64 characters.

APIs

apis.create

Register an API (resource server): its identifier becomes the access token audience, and it owns its scopes.

REST	POST /api/v1/apis → 201
Scope	apis:write — required of the key or token.
Danger	write
MCP tool	apis_create
CLI	cbox id apis create

Input	Type	Required	Description
identifier	string (uri)	yes	An absolute URI (RFC 8707), for example https://api.example.com. Becomes the token aud. At most 255 characters.
name	string	yes	At most 120 characters.
organization_id	string, nullable	no	Make it one organization's API. Left out, the environment owns it. At most 64 characters.
client_id	string, nullable	no	The app whose roles and permissions the API enforces. Must have the API's owner. At most 255 characters.
scopes	list of object	no	At most 200 items.
scopes[].key	string	yes	The scope key, unique across the environment: tax:assess. At most 128 characters.
scopes[].description	string, nullable	no	What the scope lets an app do, in plain words. At most 255 characters.
scopes[].tenant_requestable	boolean	no	Whether organizations' own apps may request it. Default true.

apis.delete

Delete an API and its scopes. Existing tokens keep their audience until they expire.

REST	DELETE /api/v1/apis/{id} → 204
Scope	apis:write — required of the key or token.
Danger	destructive
MCP tool	apis_delete
CLI	cbox id apis delete <id>

Input	Type	Required	Description
id	string (path)	yes	The API id.

apis.get

Get one registered API and its scopes.

REST	GET /api/v1/apis/{id} → 200
Scope	apis:read — required of the key or token.
Danger	read
MCP tool	apis_get
CLI	cbox id apis get <id>

Input	Type	Required	Description
id	string (path)	yes	The API id.

apis.list

List the APIs (resource servers) registered in this environment, with their scopes.

REST	GET /api/v1/apis → 200
Scope	apis:read — required of the key or token.
Danger	read
MCP tool	apis_list
CLI	cbox id apis list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

apis.scopes.define

Add a scope to an API, or change the description or tenant access of one it owns.

REST	PUT /api/v1/apis/{id}/scopes/{key} → 200
Scope	apis:write — required of the key or token.
Danger	write
MCP tool	apis_scopes_define
CLI	cbox id apis scopes define <id> <key>

Input	Type	Required	Description
id	string (path)	yes	The API id.
key	string (path)	yes	The scope key: tax:assess. At most 128 characters.
description	string, nullable	no	At most 255 characters.
tenant_requestable	boolean	no	Whether organizations' own apps may request it. Default true.

apis.scopes.remove

Remove a scope from an API. Apps holding it keep it as a plain scope that no longer reaches the API.

REST	DELETE /api/v1/apis/{id}/scopes/{key} → 204
Scope	apis:write — required of the key or token.
Danger	destructive
MCP tool	apis_scopes_remove
CLI	cbox id apis scopes remove <id> <key>

Input	Type	Required	Description
id	string (path)	yes	The API id.
key	string (path)	yes	The scope key. At most 128 characters.

apis.update

Rename an API, link or unlink its app, and optionally replace its complete scope set.

REST	PATCH /api/v1/apis/{id} → 200
Scope	apis:write — required of the key or token.
Danger	write
MCP tool	apis_update
CLI	cbox id apis update <id>

Input	Type	Required	Description
id	string (path)	yes	The API id.
name	string	no	At most 120 characters.
client_id	string, nullable	no	The app to link; null unlinks it. Left out, the link is unchanged. At most 255 characters.
scopes	list of object	no	The COMPLETE scope set afterwards. Left out, scopes are unchanged. At most 200 items.
scopes[].key	string	yes	The scope key, unique across the environment: tax:assess. At most 128 characters.
scopes[].description	string, nullable	no	What the scope lets an app do, in plain words. At most 255 characters.
scopes[].tenant_requestable	boolean	no	Whether organizations' own apps may request it. Default true.

App audit logs

audit_logs.events.create

Record 1–100 audit events your app's users caused, each for one of your organizations (customers); checked against the action's schema when it has one and appended to that organization's tamper-evident chain. Send an Idempotency-Key.

REST	POST /api/v1/audit-logs/events → 201
Scope	audit_logs:write — required of the key or token.
Danger	write
MCP tool	audit_logs_events_create
CLI	cbox id audit_logs events create

Input	Type	Required	Description
events	list of object	yes	1–100 events, recorded all together or not at all. At least 1 items. At most 100 items.
events[].organization_id	string	yes	The organization (your customer) the event happened in. At most 64 characters.
events[].action	string	yes	What happened, as dotted words: invoice.voided, user.signed_in. At most 190 characters.
events[].occurred_at	string (date-time)	yes	When it happened: ISO 8601 with a time zone, to the millisecond.
events[].actor	object	yes
events[].actor.id	string	yes	Your id for whoever did it. At most 190 characters.
events[].actor.type	string	yes	What kind of actor: user, api_key, system. At most 100 characters.
events[].actor.name	string, nullable	no	A name a person reads in the log. At most 190 characters.
events[].actor.metadata	object	no	Up to 50 names to strings, numbers, booleans or null.
events[].targets	list of object	no	What it was done to. At most 50 items.
events[].targets[].id	string	yes	At most 190 characters.
events[].targets[].type	string	yes	What kind of thing: invoice, user, report. At most 100 characters.
events[].targets[].name	string, nullable	no	At most 190 characters.
events[].targets[].metadata	object	no
events[].context	object	no
events[].context.location	string, nullable	no	Where it came from — usually the client's IP address. At most 64 characters.
events[].context.user_agent	string, nullable	no	At most 512 characters.
events[].metadata	object	no	Up to 50 names to strings, numbers, booleans or null; values up to 500 characters.

audit_logs.events.list

Read audit events newest first, for one organization or the whole environment, filtered by action, actor, target and time range; pass next_cursor as after to page.

REST	GET /api/v1/audit-logs/events → 200
Scope	audit_logs:read — required of the key or token.
Danger	read
MCP tool	audit_logs_events_list
CLI	cbox id audit_logs events list

Input	Type	Required	Description
organization_id	string	no	Only this organization's events. Required in effect for an organization's own administrator, whose events are the only ones they see. At most 64 characters.
actions	list of string	no	Only these actions, e.g. invoice.voided. At most 50 items.
actor_id	string	no	Only events this actor caused. At most 190 characters.
target_id	string	no	Only events naming this target. At most 190 characters.
range_start	string (date-time)	no	Only events that occurred at or after this time.
range_end	string (date-time)	no	Only events that occurred before this time.
order	string	no	desc (default) for newest first, asc for oldest first. One of desc, asc.
limit	integer	no	Events per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page. At most 200 characters.

audit_logs.exports.create

Start a CSV export of audit events (same filters as the list). It is written on the queue: poll audit_logs.exports.get until state is ready, then download from its short-lived url.

REST	POST /api/v1/audit-logs/exports → 201
Scope	audit_logs:export — required of the key or token.
Danger	write
MCP tool	audit_logs_exports_create
CLI	cbox id audit_logs exports create
Secret	data.url — shown once, never kept for an idempotent replay

Input	Type	Required	Description
organization_id	string	no	Only this organization's events. Required in effect for an organization's own administrator, whose events are the only ones they see. At most 64 characters.
actions	list of string	no	Only these actions, e.g. invoice.voided. At most 50 items.
actor_id	string	no	Only events this actor caused. At most 190 characters.
target_id	string	no	Only events naming this target. At most 190 characters.
range_start	string (date-time)	no	Only events that occurred at or after this time.
range_end	string (date-time)	no	Only events that occurred before this time.

audit_logs.exports.get

Read an audit-log export's state; once ready it carries a signed download url valid for a few minutes (read it again for a fresh one).

REST	GET /api/v1/audit-logs/exports/{id} → 200
Scope	audit_logs:read — required of the key or token.
Danger	read
MCP tool	audit_logs_exports_get
CLI	cbox id audit_logs exports get <id>

Input	Type	Required	Description
id	string (path)	yes	The export id. At most 64 characters.

audit_logs.schemas.create

Define the schema one audit-log action's events must match — allowed target types and metadata schemas (a subset of JSON Schema). Events of that action are then validated on arrival.

REST	POST /api/v1/audit-logs/schemas → 201
Scope	audit_logs:manage — required of the key or token.
Danger	write
MCP tool	audit_logs_schemas_create
CLI	cbox id audit_logs schemas create

Input	Type	Required	Description
action	string	yes	The action this schema is for, e.g. invoice.voided. At most 190 characters.
targets	list of object, nullable	no	The target types this action's events may name, each with an optional metadata schema. Leave out to allow any. At most 50 items.
targets[].type	string	yes	A target type events of this action may name. At most 100 characters.
targets[].metadata	object	no	A metadata schema for targets of this type.
actor_metadata	object	no	A metadata schema (a subset of JSON Schema) for the actor's metadata.
metadata	object	no	A metadata schema (a subset of JSON Schema) for the event's own metadata.

audit_logs.schemas.delete

Delete an audit-log action's schema. Its events are then accepted unchecked — or refused, if the environment is in strict mode.

REST	DELETE /api/v1/audit-logs/schemas/{action} → 204
Scope	audit_logs:manage — required of the key or token.
Danger	destructive
MCP tool	audit_logs_schemas_delete
CLI	cbox id audit_logs schemas delete <action>

Input	Type	Required	Description
action	string (path)	yes	The action whose schema to delete. At most 190 characters.

audit_logs.schemas.get

Read the schema one audit-log action's events are validated against.

REST	GET /api/v1/audit-logs/schemas/{action} → 200
Scope	audit_logs:read — required of the key or token.
Danger	read
MCP tool	audit_logs_schemas_get
CLI	cbox id audit_logs schemas get <action>

Input	Type	Required	Description
action	string (path)	yes	The action, e.g. invoice.voided. At most 190 characters.

audit_logs.schemas.list

List the audit-log schemas this environment validates events against, one per action.

REST	GET /api/v1/audit-logs/schemas → 200
Scope	audit_logs:read — required of the key or token.
Danger	read
MCP tool	audit_logs_schemas_list
CLI	cbox id audit_logs schemas list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

audit_logs.schemas.update

Replace an audit-log action's schema with a new version (omitted parts are removed). Recorded events keep the version they were checked against.

REST	PUT /api/v1/audit-logs/schemas/{action} → 200
Scope	audit_logs:manage — required of the key or token.
Danger	write
MCP tool	audit_logs_schemas_update
CLI	cbox id audit_logs schemas update <action>

Input	Type	Required	Description
action	string (path)	yes	The action whose schema to replace. At most 190 characters.
targets	list of object, nullable	no	The target types this action's events may name, each with an optional metadata schema. Leave out to allow any. At most 50 items.
targets[].type	string	yes	A target type events of this action may name. At most 100 characters.
targets[].metadata	object	no	A metadata schema for targets of this type.
actor_metadata	object	no	A metadata schema (a subset of JSON Schema) for the actor's metadata.
metadata	object	no	A metadata schema (a subset of JSON Schema) for the event's own metadata.

audit_logs.settings.get

Read this environment's audit-log settings: retention in days and whether strict schemas are on.

REST	GET /api/v1/audit-logs/settings → 200
Scope	audit_logs:read — required of the key or token.
Danger	read
MCP tool	audit_logs_settings_get
CLI	cbox id audit_logs settings get

Takes no input.

audit_logs.settings.update

Change this environment's audit-log retention (days, 1–3650) and strict mode. Shortening retention deletes older events at the next daily prune — irreversibly.

REST	PATCH /api/v1/audit-logs/settings → 200
Scope	audit_logs:manage — required of the key or token.
Danger	destructive
MCP tool	audit_logs_settings_update
CLI	cbox id audit_logs settings update

Input	Type	Required	Description
retention_days	integer	no	Keep events this many days after they arrive. At least 1. At most 3650.
strict_schemas	boolean	no	Refuse events whose action has no schema.

audit_logs.verify

Re-hash one organization's audit-event chain (from the oldest event retention kept, or from_sequence) and report whether every event is unchanged and in place.

REST	GET /api/v1/audit-logs/verify → 200
Scope	audit_logs:read — required of the key or token.
Danger	read
MCP tool	audit_logs_verify
CLI	cbox id audit_logs verify

Input	Type	Required	Description
organization_id	string	no	The organization whose chain to verify. An organization's own administrator may leave it out. At most 64 characters.
from_sequence	integer	no	Start here rather than at the oldest event kept. At least 1.
limit	integer	no	Verify at most this many events. Default 10,000. At least 1. At most 10000.

Applications

apps.blueprint

Export an app's configuration as a blueprint — no client id, secret, key set or owner — to register the same app in another environment.

REST	GET /api/v1/apps/{id}/blueprint → 200
Scope	apps:read — required of the key or token.
Danger	read
MCP tool	apps_blueprint
CLI	cbox id apps blueprint <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.

apps.copy

Copy an app into another environment of this project, with a new client id and secret there. A person on the environment console only; a key exports the blueprint instead.

REST	POST /api/v1/apps/{id}/copy → 201
Scope	apps:write — required of the key or token.
Danger	critical
MCP tool	apps_copy
CLI	cbox id apps copy <id>
Secret	data.client_secret — shown once, never kept for an idempotent replay

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.
environment_id	string	yes	The environment to copy into: another environment of this project. At most 64 characters.
name	string	yes	What to call the copy there. At least 1 characters. At most 190 characters.
redirect_uris	list of string	no	Its redirect URIs there — staging's callback is rarely production's. Left out, none. At most 50 items.

apps.create

Register an app (OAuth client) from a short form (name and type) or from another environment's blueprint. A confidential app's client_secret is returned once.

REST	POST /api/v1/apps → 201
Scope	apps:write — required of the key or token.
Danger	critical
MCP tool	apps_create
CLI	cbox id apps create
Secret	data.client_secret — shown once, never kept for an idempotent replay

Input	Type	Required	Description
blueprint	object	no	A blueprint document from GET /apps/{id}/blueprint. Left out, the short form below describes the app.
name	string	no	Required without a blueprint; beside one, it replaces the blueprint's. At most 190 characters.
type	string	no	The kind of app. Default web. One of web, spa, cli, service, agent, advanced.
client_type	string	no	Required for advanced. One of public, confidential.
grant_types	list of string	no	Required for advanced.
redirect_uris	list of string	no	At most 50 items.
post_logout_redirect_uris	list of string	no	At most 50 items.
scopes	list of string	no	Left out, the kind's default scopes. At most 100 items.
first_party	boolean	no	Skips the consent screen. Default false.
manifest_url	string (uri), nullable	no	Where the app publishes its roles-and-permissions manifest. At most 500 characters.
organization_id	string, nullable	no	The owning organization; null for the environment's own app. At most 64 characters.
jwks	object	no	A public JWK Set, for a private_key_jwt app. Never part of a blueprint.

apps.delete

Delete an app and every secret it holds. Anything signing in as it stops working immediately.

REST	DELETE /api/v1/apps/{id} → 204
Scope	apps:write — required of the key or token.
Danger	critical
MCP tool	apps_delete
CLI	cbox id apps delete <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.

apps.get

Get one app (OAuth client) by its id or its client_id: its kind, grants, redirect URIs, scopes and settings. Never a secret.

REST	GET /api/v1/apps/{id} → 200
Scope	apps:read — required of the key or token.
Danger	read
MCP tool	apps_get
CLI	cbox id apps get <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.

apps.list

List the apps (OAuth clients) registered in this environment. Never a secret.

REST	GET /api/v1/apps → 200
Scope	apps:read — required of the key or token.
Danger	read
MCP tool	apps_list
CLI	cbox id apps list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

apps.manifest.set

Set or clear the URL an app publishes its roles-and-permissions manifest at. Does not fetch it; apps.manifest.sync does.

REST	PUT /api/v1/apps/{id}/manifest → 200
Scope	apps:write — required of the key or token.
Danger	write
MCP tool	apps_manifest_set
CLI	cbox id apps manifest set <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.
manifest_url	string (uri), nullable	no	An absolute URL; null or left out clears it. At most 500 characters.

apps.manifest.sync

Fetch an app's published manifest now and sync the roles and permissions it declares.

REST	POST /api/v1/apps/{id}/manifest/sync → 200
Scope	apps:write — required of the key or token.
Danger	write
MCP tool	apps_manifest_sync
CLI	cbox id apps manifest sync <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.

apps.scopes.set

Replace an app's complete scope set — the ceiling of what it may request, applied from its next token.

REST	PUT /api/v1/apps/{id}/scopes → 200
Scope	apps:write — required of the key or token.
Danger	write
MCP tool	apps_scopes_set
CLI	cbox id apps scopes set <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.
scopes	list of string	no	Required. The COMPLETE scope set afterwards; an empty list removes every scope. At most 200 items.

apps.secrets.list

List an app's live client secrets — ids, last characters and dates, never the secrets themselves.

REST	GET /api/v1/apps/{id}/secrets → 200
Scope	apps:read — required of the key or token.
Danger	read
MCP tool	apps_secrets_list
CLI	cbox id apps secrets list <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.

apps.secrets.revoke

Revoke one of an app's client secrets immediately. Never its last live secret — rotate that instead.

REST	DELETE /api/v1/apps/{id}/secrets/{secret_id} → 204
Scope	apps:write — required of the key or token.
Danger	critical
MCP tool	apps_secrets_revoke
CLI	cbox id apps secrets revoke <id> <secret_id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.
secret_id	string (path)	yes	The secret's id, from GET /apps/{id}/secrets. At most 64 characters.

apps.secrets.rotate

Mint a new client secret for an app and retire the current ones after grace_seconds (0 = at once). The new secret is returned once.

REST	POST /api/v1/apps/{id}/secrets → 201
Scope	apps:write — required of the key or token.
Danger	critical
MCP tool	apps_secrets_rotate
CLI	cbox id apps secrets rotate <id>
Secret	data.client_secret — shown once, never kept for an idempotent replay

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.
grace_seconds	integer	yes	How long the current secrets keep working, in seconds. 0 stops them at once. At least 0. At most 2592000.

apps.settings.api_key_prefix

Set the prefix of an app's customer API keys (acme_live), which lets its users create keys for it, or null to stop new keys.

REST	PUT /api/v1/apps/{id}/settings/api-key-prefix → 200
Scope	apps:write — required of the key or token.
Danger	write
MCP tool	apps_settings_api_key_prefix
CLI	cbox id apps settings api_key_prefix <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.
prefix	string, nullable	no	2–16 lowercase letters or digits starting with a letter, then _live or _test. Null or left out: no new keys. At most 32 characters.

apps.settings.backchannel_logout

Set or clear the URI an app is sent a logout token at when somebody signs out (OIDC Back-Channel Logout).

REST	PUT /api/v1/apps/{id}/settings/backchannel-logout → 200
Scope	apps:write — required of the key or token.
Danger	write
MCP tool	apps_settings_backchannel_logout
CLI	cbox id apps settings backchannel_logout <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.
uri	string (uri), nullable	no	HTTPS (HTTP on localhost only). Null or left out: the app is not told. At most 2000 characters.
session_required	boolean	no	Every logout token carries sid. Default false.

apps.settings.token_exchange

Turn token exchange (RFC 8693) on or off for a confidential app.

REST	PUT /api/v1/apps/{id}/settings/token-exchange → 200
Scope	apps:write — required of the key or token.
Danger	write
MCP tool	apps_settings_token_exchange
CLI	cbox id apps settings token_exchange <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.
enabled	boolean	yes

apps.settings.token_lifetime

Set how long an app's access tokens live, in seconds, or null for the install's default.

REST	PUT /api/v1/apps/{id}/settings/token-lifetime → 200
Scope	apps:write — required of the key or token.
Danger	write
MCP tool	apps_settings_token_lifetime
CLI	cbox id apps settings token_lifetime <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.
access_token_ttl	integer, nullable	no	Seconds, from 60 to the install's ceiling. Null or left out: the install's default.

apps.update

Rename an app and replace its redirect URIs or sign-out redirect URIs. Fields left out are unchanged.

REST	PATCH /api/v1/apps/{id} → 200
Scope	apps:write — required of the key or token.
Danger	write
MCP tool	apps_update
CLI	cbox id apps update <id>

Input	Type	Required	Description
id	string (path)	yes	The app's id, or its client_id.
name	string	no	At least 1 characters. At most 190 characters.
redirect_uris	list of string	no	The COMPLETE list afterwards. At most 50 items.
post_logout_redirect_uris	list of string	no	The COMPLETE list afterwards. At most 50 items.

Approvals

approvals.deny

Deny a pending approval request (CIBA) for the person it was raised for: the agent gets access_denied and no token.

REST	POST /api/v1/agent-requests/{request_id}/deny → 204
Scope	approvals:write — required of the key or token.
Danger	destructive
MCP tool	approvals_deny
CLI	cbox id approvals deny <request_id>

Input	Type	Required	Description
request_id	string (path)	yes

approvals.list

List the pending requests from agents to act as one of this environment's people (CIBA): which app, for whom, and what it asks.

REST	GET /api/v1/agent-requests → 200
Scope	approvals:read — required of the key or token.
Danger	read
MCP tool	approvals_list
CLI	cbox id approvals list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

Audit log

audit.list

Read this environment's audit trail oldest first, optionally narrowed by action, actor type or organization; pass the last id as after to page.

REST	GET /api/v1/audit-log → 200
Scope	audit:read — required of the key or token.
Danger	read
MCP tool	audit_list
CLI	cbox id audit list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.
action	string	no	Only this action, e.g. webhook.created. At most 190 characters.
actor_type	string	no	Only entries by this kind of actor; service is a management key or an app. One of user, service, system, operator, organization_member.
organization_id	string	no	Only this organization's entries. At most 64 characters.

Branding

branding.appearance.get

Read the hosted sign-in theme: the environment default, or one organization's own.

REST	GET /api/v1/branding/appearance → 200
Scope	branding:read — required of the key or token.
Danger	read
MCP tool	branding_appearance_get
CLI	cbox id branding appearance get

Input	Type	Required	Description
organization_id	string	no	Read this organization's theme. Left out, the environment default. At most 64 characters.

branding.appearance.set

Set the hosted sign-in theme (preset, colours, corners, type, logo) for the environment default or one organization.

REST	PUT /api/v1/branding/appearance → 200
Scope	branding:write — required of the key or token.
Danger	write
MCP tool	branding_appearance_set
CLI	cbox id branding appearance set

Input	Type	Required	Description
organization_id	string, nullable	no	Theme this organization. Left out, the environment default. At most 64 characters.
theme	object	yes	The theme. Both modes must be readable: text needs 4.5:1 against the background, muted text 3:1.
theme.preset	string	no	A preset id: cbox, midnight, minimal, warm, contrast. At most 64 characters.
theme.radius	string	no	Corner radius: 0rem, 0.25rem, 0.375rem, 0.5rem, 0.75rem, 1rem. At most 32 characters.
theme.font	string	no	Type family: system, geometric, serif. At most 32 characters.
theme.light	object	no	Colours as #rrggbb. One left out takes the preset's.
theme.light.primary	string	no	At most 32 characters.
theme.light.background	string	no	At most 32 characters.
theme.light.foreground	string	no	At most 32 characters.
theme.light.muted	string	no	At most 32 characters.
theme.dark	object	no	Colours as #rrggbb. One left out takes the preset's.
theme.dark.primary	string	no	At most 32 characters.
theme.dark.background	string	no	At most 32 characters.
theme.dark.foreground	string	no	At most 32 characters.
theme.dark.muted	string	no	At most 32 characters.
logo	string (uri), nullable	no	An https URL for the logo; null removes it, left out keeps it. At most 2048 characters.

branding.whitelabel.get

Read the white-label branding (palette, app name, email sender, logo) of the environment default or one organization.

REST	GET /api/v1/branding/whitelabel → 200
Scope	branding:read — required of the key or token.
Danger	read
MCP tool	branding_whitelabel_get
CLI	cbox id branding whitelabel get

Input	Type	Required	Description
organization_id	string	no	Read this organization's branding. Left out, the environment default. At most 64 characters.

branding.whitelabel.set

Save the white-label branding (palette, app name, email sender, welcome email) of the environment default or one organization.

REST	PUT /api/v1/branding/whitelabel → 200
Scope	branding:write — required of the key or token.
Danger	write
MCP tool	branding_whitelabel_set
CLI	cbox id branding whitelabel set

Input	Type	Required	Description
organization_id	string, nullable	no	Brand this organization. Left out, the environment default. At most 64 characters.
palette	object	no	Colours as hex (#0a2540) or oklch(…), by token: primary, accent, ring, foreground, background. Sent, it is the complete palette; a token left out or blank is unset.
palette.primary	string, nullable	no	At most 100 characters.
palette.accent	string, nullable	no	At most 100 characters.
palette.ring	string, nullable	no	At most 100 characters.
palette.foreground	string, nullable	no	At most 100 characters.
palette.background	string, nullable	no	At most 100 characters.
app_name	string, nullable	no	The product name shown in place of Cbox ID; null to unset. At most 120 characters.
email_from_name	string, nullable	no	The sender name on mail; null to unset. At most 120 characters.
email_template	string, nullable	no	The welcome email body; blank or null to use the default. At most 5000 characters.

Directory Sync

directories.connect

Connect a Google Workspace or Microsoft Entra directory to sync an organization's people from, verifying the credentials first. Runs the first sync.

REST	POST /api/v1/directories/connect → 201
Scope	directory_sync:write — required of the key or token.
Danger	critical
MCP tool	directories_connect
CLI	cbox id directories connect

Input	Type	Required	Description
organization_id	string	yes	The organization whose people it provisions. At most 64 characters.
provider	string	yes	google_workspace or microsoft_entra. One of google_workspace, microsoft_entra.
credentials	object	yes	The provider's credentials. Write-only: sealed, never returned.
credentials.service_account_json	string	no	Google: the service account's JSON key, whole. At most 20000 characters.
credentials.admin_email	string	no	Google: the administrator the service account acts as. At most 190 characters.
credentials.tenant_id	string	no	Entra: the directory (tenant) id. At most 190 characters.
credentials.client_id	string	no	Entra: the app registration's client id. At most 190 characters.
credentials.client_secret	string	no	Entra: the app registration's client secret. At most 500 characters.

directories.create

Register a SCIM directory for an organization. Answers the SCIM base URL and a bearer token, shown once.

REST	POST /api/v1/directories → 201
Scope	directory_sync:write — required of the key or token.
Danger	critical
MCP tool	directories_create
CLI	cbox id directories create
Secret	data.bearer_token — shown once, never kept for an idempotent replay

Input	Type	Required	Description
organization_id	string	yes	The organization whose people it provisions. At most 64 characters.
name	string	yes	What administrators call it: "Okta SCIM". At most 120 characters.

directories.delete

Delete an inbound directory. Its token stops working; the people it provisioned keep their accounts.

REST	DELETE /api/v1/directories/{id} → 204
Scope	directory_sync:write — required of the key or token.
Danger	destructive
MCP tool	directories_delete
CLI	cbox id directories delete <id>

Input	Type	Required	Description
id	string (path)	yes	The directory's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

directories.get

Read one inbound directory: its provider, status, SCIM base URL and last sync error. Never its token or credentials.

REST	GET /api/v1/directories/{id} → 200
Scope	directory_sync:read — required of the key or token.
Danger	read
MCP tool	directories_get
CLI	cbox id directories get <id>

Input	Type	Required	Description
id	string (path)	yes	The directory's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

directories.groups.list

List the groups a directory has synced, with the role ids each group is mapped onto.

REST	GET /api/v1/directories/{id}/groups → 200
Scope	directory_sync:read — required of the key or token.
Danger	read
MCP tool	directories_groups_list
CLI	cbox id directories groups list <id>

Input	Type	Required	Description
id	string (path)	yes	The directory's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

directories.groups.map

Map a directory group onto a role (everyone in the group holds it as membership syncs), or unmap it.

REST	POST /api/v1/directories/{id}/group-roles → 200
Scope	directory_sync:write — required of the key or token.
Danger	write
MCP tool	directories_groups_map
CLI	cbox id directories groups map <id>

Input	Type	Required	Description
id	string (path)	yes	The directory's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.
group_id	string	yes	One of the directory's groups. At most 64 characters.
role_id	string	yes	A role the organization's own people may hold. At most 64 characters.
mapped	boolean	yes	true to map the group onto the role, false to unmap it.

directories.list

List the directories (SCIM, Google Workspace, Microsoft Entra) syncing people in, optionally for one organization, with their last sync error.

REST	GET /api/v1/directories → 200
Scope	directory_sync:read — required of the key or token.
Danger	read
MCP tool	directories_list
CLI	cbox id directories list

Input	Type	Required	Description
organization_id	string, nullable	no	Only this organization's. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

directories.status.set

Pause or resume an inbound directory's provisioning.

REST	POST /api/v1/directories/{id}/status → 200
Scope	directory_sync:write — required of the key or token.
Danger	write
MCP tool	directories_status_set
CLI	cbox id directories status set <id>

Input	Type	Required	Description
id	string (path)	yes	The directory's id.
active	boolean	yes	true to resume provisioning, false to pause it.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

directories.token.rotate

Issue a new bearer token for a SCIM directory, returned once. The old token stops working immediately.

REST	POST /api/v1/directories/{id}/rotate → 200
Scope	directory_sync:write — required of the key or token.
Danger	critical
MCP tool	directories_token_rotate
CLI	cbox id directories token rotate <id>
Secret	data.bearer_token — shown once, never kept for an idempotent replay

Input	Type	Required	Description
id	string (path)	yes	The directory's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

directories.update

Rename an inbound directory.

REST	PATCH /api/v1/directories/{id} → 200
Scope	directory_sync:write — required of the key or token.
Danger	write
MCP tool	directories_update
CLI	cbox id directories update <id>

Input	Type	Required	Description
id	string (path)	yes	The directory's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.
name	string	yes	The new name. At most 120 characters.

Domains

domains.add

Start serving this environment on a custom domain: returns the DNS TXT record that proves you control it.

REST	POST /api/v1/domains → 200
Scope	domains:write — required of the key or token.
Danger	write
MCP tool	domains_add
CLI	cbox id domains add

Input	Type	Required	Description
domain	string	yes	The domain, for example login.example.com. At most 253 characters.

domains.get

Read this environment's custom domain, and the DNS TXT record that proves a pending one.

REST	GET /api/v1/domains → 200
Scope	domains:read — required of the key or token.
Danger	read
MCP tool	domains_get
CLI	cbox id domains get

Takes no input.

domains.remove

Stop serving this environment on its custom domain. Anything using that domain stops reaching the environment.

REST	DELETE /api/v1/domains → 204
Scope	domains:write — required of the key or token.
Danger	destructive
MCP tool	domains_remove
CLI	cbox id domains remove

Takes no input.

domains.verify

Look for the pending domain's DNS TXT record and, once it is visible, serve this environment on that domain.

REST	POST /api/v1/domains/verify → 200
Scope	domains:write — required of the key or token.
Danger	write
MCP tool	domains_verify
CLI	cbox id domains verify

Takes no input.

Enterprise SSO

sso.connections.activate

Activate an SSO connection: people whose email domain routes to it start signing in through it.

REST	POST /api/v1/sso/connections/{id}/activate → 200
Scope	sso:write — required of the key or token.
Danger	critical
MCP tool	sso_connections_activate
CLI	cbox id sso connections activate <id>

Input	Type	Required	Description
id	string (path)	yes	The connection's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

sso.connections.certificates.activate

Make a staged SAML signing certificate the connection's primary. The certificate it replaces stops being trusted.

REST	POST /api/v1/sso/connections/{id}/certificates/activate → 200
Scope	sso:write — required of the key or token.
Danger	critical
MCP tool	sso_connections_certificates_activate
CLI	cbox id sso connections certificates activate <id>

Input	Type	Required	Description
id	string (path)	yes	The connection's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.
fingerprint_sha256	string	yes	The staged certificate's SHA-256 fingerprint, as the certificate list gives it. At most 200 characters.

sso.connections.certificates.list

List a SAML connection's signing certificates — primary and staged — with each one's fingerprint and expiry.

REST	GET /api/v1/sso/connections/{id}/certificates → 200
Scope	sso:read — required of the key or token.
Danger	read
MCP tool	sso_connections_certificates_list
CLI	cbox id sso connections certificates list <id>

Input	Type	Required	Description
id	string (path)	yes	The connection's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

sso.connections.certificates.stage

Stage a SAML connection's new IdP signing certificate (PEM or IdP metadata) beside the current one, so a renewal has no outage. Activate it once the IdP signs with it.

REST	POST /api/v1/sso/connections/{id}/certificates → 200
Scope	sso:write — required of the key or token.
Danger	critical
MCP tool	sso_connections_certificates_stage
CLI	cbox id sso connections certificates stage <id>

Input	Type	Required	Description
id	string (path)	yes	The connection's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.
certificate	string, nullable	no	The new signing certificate, PEM. Send this or metadata. At most 20000 characters.
metadata	string, nullable	no	The identity provider's metadata XML, or the https URL it is published at. Send this or certificate. At most 500000 characters.

sso.connections.create

Connect an organization's SAML or OIDC identity provider as a draft. Activate it to start signing people in through it.

REST	POST /api/v1/sso/connections → 201
Scope	sso:write — required of the key or token.
Danger	write
MCP tool	sso_connections_create
CLI	cbox id sso connections create

Input	Type	Required	Description
organization_id	string, nullable	no	The organization the connection belongs to. Send this or environment_wide. At most 64 characters.
environment_wide	boolean	no	True to make the connection the environment's own rather than one organization's. Send this or organization_id.
name	string	yes	What administrators call it: "Okta", "Entra ID". At most 120 characters.
type	string	yes	saml or oidc. The config fields of that type are required, unless pending_idp. One of saml, oidc.
pending_idp	boolean	no	True to create the draft before the identity provider's details are known: the answer's service_provider is what to paste into it. Complete it with update before activating.
idp_entity_id	string, nullable	no	SAML: the identity provider's entity id. At most 500 characters.
idp_sso_url	string (uri), nullable	no	SAML: the identity provider's single sign-on URL. At most 500 characters.
idp_x509cert	string, nullable	no	SAML: the identity provider's signing certificate (PEM). Write-only. At most 20000 characters.
sp_entity_id	string, nullable	no	SAML: the entity id this environment presents as the service provider. Left out on create, this connection's own. At most 500 characters.
sp_acs_url	string (uri), nullable	no	SAML: where the identity provider posts its assertions. Left out on create, this connection's own ACS URL. At most 500 characters.
issuer	string (uri), nullable	no	OIDC: the provider's issuer URL; its endpoints are discovered from it. At most 500 characters.
client_id	string, nullable	no	OIDC: the client id registered at the provider. At most 500 characters.
client_secret	string, nullable	no	OIDC: the client secret. Write-only. At most 500 characters.
signing_key	string, nullable	no	OIDC, optional: the provider's ID-token signing key (an RS256 public key, PEM). Leave it out for any provider whose discovery document publishes a jwks_uri — the keys are read from there and follow its rotations. Needed only when it does not. Write-only. At most 20000 characters.

sso.connections.delete

Delete an SSO connection and its settings. Where SSO is required, its people cannot sign in until another is activated.

REST	DELETE /api/v1/sso/connections/{id} → 204
Scope	sso:write — required of the key or token.
Danger	critical
MCP tool	sso_connections_delete
CLI	cbox id sso connections delete <id>

Input	Type	Required	Description
id	string (path)	yes	The connection's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

sso.connections.disable

Disable an SSO connection without deleting it. Where SSO is required, its people cannot sign in until it is re-activated.

REST	POST /api/v1/sso/connections/{id}/disable → 200
Scope	sso:write — required of the key or token.
Danger	critical
MCP tool	sso_connections_disable
CLI	cbox id sso connections disable <id>

Input	Type	Required	Description
id	string (path)	yes	The connection's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

sso.connections.get

Read one SSO connection: its type, status, entity ids, URLs, issuer and client id. Never a certificate or secret.

REST	GET /api/v1/sso/connections/{id} → 200
Scope	sso:read — required of the key or token.
Danger	read
MCP tool	sso_connections_get
CLI	cbox id sso connections get <id>

Input	Type	Required	Description
id	string (path)	yes	The connection's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

sso.connections.list

List the SAML and OIDC connections organizations sign in through, optionally for one organization. Never a certificate or secret.

REST	GET /api/v1/sso/connections → 200
Scope	sso:read — required of the key or token.
Danger	read
MCP tool	sso_connections_list
CLI	cbox id sso connections list

Input	Type	Required	Description
organization_id	string, nullable	no	Only this organization's. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

sso.connections.require_sso

Require single sign-on for the organization an SSO connection belongs to. Ends every password session there.

REST	POST /api/v1/sso/connections/{id}/require-sso → 200
Scope	sso:write — required of the key or token.
Danger	critical
MCP tool	sso_connections_require_sso
CLI	cbox id sso connections require_sso <id>

Input	Type	Required	Description
id	string (path)	yes	The connection's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

sso.connections.update

Change an SSO connection's name or identity-provider settings. Secrets left out keep the ones on file.

REST	PATCH /api/v1/sso/connections/{id} → 200
Scope	sso:write — required of the key or token.
Danger	critical
MCP tool	sso_connections_update
CLI	cbox id sso connections update <id>

Input	Type	Required	Description
id	string (path)	yes	The connection's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.
name	string	no	A new name. At most 120 characters.
idp_entity_id	string, nullable	no	SAML: the identity provider's entity id. At most 500 characters.
idp_sso_url	string (uri), nullable	no	SAML: the identity provider's single sign-on URL. At most 500 characters.
idp_x509cert	string, nullable	no	SAML: the identity provider's signing certificate (PEM). Write-only. At most 20000 characters.
sp_entity_id	string, nullable	no	SAML: the entity id this environment presents as the service provider. Left out on create, this connection's own. At most 500 characters.
sp_acs_url	string (uri), nullable	no	SAML: where the identity provider posts its assertions. Left out on create, this connection's own ACS URL. At most 500 characters.
issuer	string (uri), nullable	no	OIDC: the provider's issuer URL; its endpoints are discovered from it. At most 500 characters.
client_id	string, nullable	no	OIDC: the client id registered at the provider. At most 500 characters.
client_secret	string, nullable	no	OIDC: the client secret. Write-only. At most 500 characters.
signing_key	string, nullable	no	OIDC, optional: the provider's ID-token signing key (an RS256 public key, PEM). Leave it out for any provider whose discovery document publishes a jwks_uri — the keys are read from there and follow its rotations. Needed only when it does not. Write-only. At most 20000 characters.

sso.domains.capture

Turn capture on or off for a verified domain: captured, everyone with an address at it must sign in through the organization's SSO.

REST	POST /api/v1/sso/domains/{id}/capture → 200
Scope	sso:write — required of the key or token.
Danger	critical
MCP tool	sso_domains_capture
CLI	cbox id sso domains capture <id>

Input	Type	Required	Description
id	string (path)	yes	The domain's id.
capture	boolean	yes	true to capture the domain, false to release it.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

sso.domains.create

Claim an email domain for an organization's single sign-on, and get the DNS TXT record to publish to prove it.

REST	POST /api/v1/sso/domains → 201
Scope	sso:write — required of the key or token.
Danger	write
MCP tool	sso_domains_create
CLI	cbox id sso domains create

Input	Type	Required	Description
organization_id	string	yes	The organization claiming it. At most 64 characters.
domain	string	yes	The email domain, e.g. acme.com. At most 253 characters.

sso.domains.delete

Remove a claimed email domain. Its people stop being routed to the organization's SSO connection.

REST	DELETE /api/v1/sso/domains/{id} → 204
Scope	sso:write — required of the key or token.
Danger	destructive
MCP tool	sso_domains_delete
CLI	cbox id sso domains delete <id>

Input	Type	Required	Description
id	string (path)	yes	The domain's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

sso.domains.list

List the email domains organizations claimed for single sign-on, whether each is verified and captured, and the DNS record that proves an unverified one.

REST	GET /api/v1/sso/domains → 200
Scope	sso:read — required of the key or token.
Danger	read
MCP tool	sso_domains_list
CLI	cbox id sso domains list

Input	Type	Required	Description
organization_id	string, nullable	no	Only this organization's. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

sso.domains.verify

Check a claimed domain's DNS TXT record now. Answers the domain, with verified true once the record is found.

REST	POST /api/v1/sso/domains/{id}/verify → 200
Scope	sso:write — required of the key or token.
Danger	write
MCP tool	sso_domains_verify
CLI	cbox id sso domains verify <id>

Input	Type	Required	Description
id	string (path)	yes	The domain's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

sso.saml_metadata.import

Parse an identity provider's SAML metadata (XML or a metadata URL) into the entity id, SSO URL and certificate a SAML connection needs. Stores nothing.

REST	POST /api/v1/sso/saml-metadata → 200
Scope	sso:write — required of the key or token.
Danger	write
MCP tool	sso_saml_metadata_import
CLI	cbox id sso saml_metadata import

Input	Type	Required	Description
metadata	string	yes	The IdP metadata XML, or an https URL it is published at. At most 500000 characters.

Events

events.list

Read this environment's domain events (the facts webhooks deliver) oldest first; pass the last id as after to poll for new ones.

REST	GET /api/v1/events → 200
Scope	events:read — required of the key or token.
Danger	read
MCP tool	events_list
CLI	cbox id events list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.
types	list of string	no	Only these event types, e.g. user.created. At most 50 items.
organization_id	string	no	Only this organization's events. At most 64 characters.

Governance

access_reviews.close

Close an access review and apply it: every revoke is carried out, and undecided items get the review's pending policy (revoke by default).

REST	POST /api/v1/access-reviews/{id}/close → 200
Scope	governance:write — required of the key or token.
Danger	destructive
MCP tool	access_reviews_close
CLI	cbox id access_reviews close <id>

Input	Type	Required	Description
id	string (path)	yes	The review's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

access_reviews.create

Open an access review of one organization's roles and memberships — or of staff roles — for someone to certify or revoke.

REST	POST /api/v1/access-reviews → 201
Scope	governance:write — required of the key or token.
Danger	write
MCP tool	access_reviews_create
CLI	cbox id access_reviews create

Input	Type	Required	Description
name	string	yes	What the review is: "Q3 finance access". At most 190 characters.
covers	string	no	organization (default): one organization's access, named by organization_id. staff: every environment-wide staff grant. One of organization, staff.
organization_id	string, nullable	no	The organization to review. Required unless covers is staff. At most 64 characters.
due_in_days	integer	no	Days until it is due. Default 7. At least 1. At most 365.

access_reviews.get

Read one access review: its status, due date, pending-item policy and item count.

REST	GET /api/v1/access-reviews/{id} → 200
Scope	governance:read — required of the key or token.
Danger	read
MCP tool	access_reviews_get
CLI	cbox id access_reviews get <id>

Input	Type	Required	Description
id	string (path)	yes	The review's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

access_reviews.items.decide

Certify or revoke one item of an open access review. Revokes are applied when the review closes.

REST	POST /api/v1/access-reviews/{id}/items/{item_id} → 200
Scope	governance:write — required of the key or token.
Danger	write
MCP tool	access_reviews_items_decide
CLI	cbox id access_reviews items decide <id> <item_id>

Input	Type	Required	Description
id	string (path)	yes	The review's id.
item_id	string (path)	yes	The item's id.
decision	string	yes	certified keeps the access; revoked takes it away when the review closes. One of certified, revoked.
note	string, nullable	no	Why, for whoever audits the review. At most 1000 characters.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

access_reviews.items.list

List the items an access review asks someone to certify or revoke: who holds what, and the decision on each.

REST	GET /api/v1/access-reviews/{id}/items → 200
Scope	governance:read — required of the key or token.
Danger	read
MCP tool	access_reviews_items_list
CLI	cbox id access_reviews items list <id>

Input	Type	Required	Description
id	string (path)	yes	The review's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

access_reviews.list

List access reviews (certification campaigns), open and closed, optionally those covering one organization.

REST	GET /api/v1/access-reviews → 200
Scope	governance:read — required of the key or token.
Danger	read
MCP tool	access_reviews_list
CLI	cbox id access_reviews list

Input	Type	Required	Description
organization_id	string, nullable	no	Only reviews covering this organization: its own and the staff reviews. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

sod_policies.create

Define a role-conflict rule: two or more roles no one person may hold together. Enforced on every grant from now on.

REST	POST /api/v1/sod-policies → 201
Scope	governance:write — required of the key or token.
Danger	write
MCP tool	sod_policies_create
CLI	cbox id sod_policies create

Input	Type	Required	Description
organization_id	string, nullable	no	The organization the rule belongs to. Send this or environment_wide. At most 64 characters.
environment_wide	boolean	no	True to make the rule the environment's own rather than one organization's. Send this or organization_id.
name	string	yes	What the rule is for: "Payments maker/checker". At most 190 characters.
description	string, nullable	no	Why the roles conflict. At most 500 characters.
role_ids	list of string	yes	The roles no one person may hold together; at least two. At least 2 items. At most 50 items.

sod_policies.delete

Remove a role-conflict rule. Grants it refused are allowed from then on.

REST	DELETE /api/v1/sod-policies/{id} → 204
Scope	governance:write — required of the key or token.
Danger	critical
MCP tool	sod_policies_delete
CLI	cbox id sod_policies delete <id>

Input	Type	Required	Description
id	string (path)	yes	The rule's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

sod_policies.get

Read one role-conflict rule: the roles no one person may hold together, and whether it is enforced.

REST	GET /api/v1/sod-policies/{id} → 200
Scope	governance:read — required of the key or token.
Danger	read
MCP tool	sod_policies_get
CLI	cbox id sod_policies get <id>

Input	Type	Required	Description
id	string (path)	yes	The rule's id.
organization_id	string, nullable	no	Only if it binds this organization (its own, or environment-wide); anything else is a 404. At most 64 characters.

sod_policies.list

List role-conflict (segregation of duties) rules: sets of roles no one person may hold together. Optionally those binding one organization.

REST	GET /api/v1/sod-policies → 200
Scope	governance:read — required of the key or token.
Danger	read
MCP tool	sod_policies_list
CLI	cbox id sod_policies list

Input	Type	Required	Description
organization_id	string, nullable	no	Only the rules binding this organization: its own and the environment-wide ones. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

sod_policies.status.set

Enforce a role-conflict rule, or stop enforcing it — switched off, grants that break it are allowed again.

REST	POST /api/v1/sod-policies/{id}/status → 200
Scope	governance:write — required of the key or token.
Danger	critical
MCP tool	sod_policies_status_set
CLI	cbox id sod_policies status set <id>

Input	Type	Required	Description
id	string (path)	yes	The rule's id.
active	boolean	yes	true to enforce the rule, false to stop enforcing it.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

Hooks

hooks.create

Register a hook at a hook point (token minting, login, registration, password change). Returns its signing secret once.

REST	POST /api/v1/hooks → 201
Scope	hooks:write — required of the key or token.
Danger	critical
MCP tool	hooks_create
CLI	cbox id hooks create
Secret	data.secret — shown once, never kept for an idempotent replay

Input	Type	Required	Description
hook_point	string	yes	When it is called. One of token_minting, post_login, pre_registration, post_registration, pre_password_change, post_password_change.
url	string (uri)	yes	A public HTTPS URL, called in the middle of the operation. At most 500 characters.
organization_id	string, nullable	no	The organization it belongs to; it carries that organization's traffic only. Send this or environment_wide. At most 64 characters.
environment_wide	boolean	no	True to make it the environment's own, carrying EVERY organization's traffic. Send this or organization_id.

hooks.delete

Remove a hook. It is no longer called at its hook point.

REST	DELETE /api/v1/hooks/{id} → 204
Scope	hooks:write — required of the key or token.
Danger	destructive
MCP tool	hooks_delete
CLI	cbox id hooks delete <id>

Input	Type	Required	Description
id	string (path)	yes	The hook id.

hooks.get

Get one hook: its URL, hook point, owner and whether it is active. Never its signing secret.

REST	GET /api/v1/hooks/{id} → 200
Scope	hooks:read — required of the key or token.
Danger	read
MCP tool	hooks_get
CLI	cbox id hooks get <id>

Input	Type	Required	Description
id	string (path)	yes	The hook id.

hooks.list

List the hooks — endpoints called during sign-in and token issuance — with their hook point, owner and whether each is active.

REST	GET /api/v1/hooks → 200
Scope	hooks:read — required of the key or token.
Danger	read
MCP tool	hooks_list
CLI	cbox id hooks list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

hooks.update

Pause (active: false) or activate (active: true) a hook.

REST	PATCH /api/v1/hooks/{id} → 200
Scope	hooks:write — required of the key or token.
Danger	critical
MCP tool	hooks_update
CLI	cbox id hooks update <id>

Input	Type	Required	Description
id	string (path)	yes	The hook id.
active	boolean	yes	True to call it at its hook point; false to pause it.

Invitations

invitations.list

List an organization's pending invitations, a page at a time, with the roles each will grant and the app it leads back to.

REST	GET /api/v1/organizations/{organization_id}/invitations → 200
Scope	invitations:read — required of the key or token.
Danger	read
MCP tool	invitations_list
CLI	cbox id invitations list <organization_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

invitations.resend

Re-send a pending invitation on a fresh link. The answer is the new invitation; the old id and link stop working.

REST	POST /api/v1/organizations/{organization_id}/invitations/{invitation_id}/resend → 200
Scope	invitations:write — required of the key or token.
Danger	write
MCP tool	invitations_resend
CLI	cbox id invitations resend <organization_id> <invitation_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
invitation_id	string (path)	yes	The invitation id. At most 64 characters.

invitations.revoke

Withdraw a pending invitation: its link stops working and the roles parked for it are dropped.

REST	DELETE /api/v1/organizations/{organization_id}/invitations/{invitation_id} → 204
Scope	invitations:write — required of the key or token.
Danger	destructive
MCP tool	invitations_revoke
CLI	cbox id invitations revoke <organization_id> <invitation_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
invitation_id	string (path)	yes	The invitation id. At most 64 characters.

invitations.send

Invite someone into an organization by email, on a tier and with access roles (by id, or manifest key with client_id), optionally leading back to an app.

REST	POST /api/v1/organizations/{organization_id}/invitations → 201
Scope	invitations:write — required of the key or token.
Danger	write
MCP tool	invitations_send
CLI	cbox id invitations send <organization_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
email	string (email)	yes	At most 190 characters.
role	string	no	The tier. Default member; ownership is never given by invitation. One of admin, member.
roles	list of string	no	Access roles granted on acceptance: ids, or manifest keys of client_id's app. Never a staff role. At most 50 items.
client_id	string, nullable	no	The app the invitation comes from, and leads back to. At most 255 characters.
return_to	string, nullable	no	Where the person lands after accepting — on one of that app's registered redirect-URI origins. At most 2048 characters.
inviter_name	string, nullable	no	Who the mail says it is from. Default: the app's name, else the environment's. At most 120 characters.

Legacy login

legacy_login.approve

Approve the declared legacy login endpoint: sign-ins for people not yet migrated, with their passwords, go to that URL.

REST	POST /api/v1/legacy-login/approve → 200
Scope	signin:write — required of the key or token.
Danger	critical
MCP tool	legacy_login_approve
CLI	cbox id legacy_login approve

Takes no input.

legacy_login.get

Read the legacy login endpoint an app declared for migration, and whether it is approved to receive sign-ins.

REST	GET /api/v1/legacy-login → 200
Scope	signin:read — required of the key or token.
Danger	read
MCP tool	legacy_login_get
CLI	cbox id legacy_login get

Takes no input.

legacy_login.probe

Ask the declared legacy login endpoint whether it knows an address — your own — to test it before approving. Sends no password.

REST	POST /api/v1/legacy-login/probe → 200
Scope	signin:write — required of the key or token.
Danger	write
MCP tool	legacy_login_probe
CLI	cbox id legacy_login probe

Input	Type	Required	Description
email	string (email)	yes	An address that exists in your old system — your own. At most 254 characters.

legacy_login.revoke

Withdraw the legacy login approval. People not yet migrated can no longer sign in; the declaration stays on file.

REST	POST /api/v1/legacy-login/revoke → 200
Scope	signin:write — required of the key or token.
Danger	critical
MCP tool	legacy_login_revoke
CLI	cbox id legacy_login revoke

Takes no input.

Log streams

log_streams.create

Stream the audit trail to a SIEM (Splunk, Elastic, Graylog, CEF, JSON), Datadog, or an S3 or GCS bucket. A generated HMAC key is returned once.

REST	POST /api/v1/log-streams → 201
Scope	log_streams:write — required of the key or token.
Danger	critical
MCP tool	log_streams_create
CLI	cbox id log_streams create
Secret	data.secret — shown once, never kept for an idempotent replay

Input	Type	Required	Description
name	string	yes	At most 190 characters.
destination	string	yes	One of splunk_hec, elastic_ecs, graylog_gelf, cef_http, generic_json, datadog, s3, gcs.
endpoint_url	string (uri), nullable	no	An HTTP collector: the public URL entries are POSTed to (required). Datadog, S3 and GCS: leave out for the destination's own endpoint, or an https URL of an S3-compatible store (MinIO, R2). At most 2048 characters.
auth	string	no	An HTTP collector: how the endpoint is authenticated. Left out, the destination's default. The cloud destinations authenticate their own way. One of none, bearer, splunk, hmac.
secret	string, nullable	no	The credential, never echoed: the bearer or Splunk token (HTTP collectors; left out with hmac, a key is generated and returned once), the Datadog API key, the S3 secret access key (none with role_arn), or the GCS service-account JSON key. At most 8192 characters.
options	object	no	Datadog, S3 and GCS only: the destination's settings. An HTTP collector takes none.
options.site	string, nullable	no	Datadog: the site your account lives on — the domain you sign in at, e.g. datadoghq.eu for EU1. Default datadoghq.com (US1). An API key only works on its own site. One of datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, ddog-gov.com.
options.service	string, nullable	no	Datadog: the service attribute on every entry. Default: this platform's name. At most 100 characters.
options.source	string, nullable	no	Datadog: the ddsource attribute. Default cbox. At most 100 characters.
options.tags	list of string, nullable	no	Datadog: key:value tags (ddtags) on every entry, e.g. env:prod. At most 100 items.
options.hostname	string, nullable	no	Datadog: the hostname attribute. Default: this platform's host. At most 255 characters.
options.bucket	string, nullable	no	S3 and GCS: the bucket objects are written to. At most 222 characters.
options.region	string, nullable	no	S3: the bucket's AWS Region, e.g. eu-west-1 (auto for Cloudflare R2). At most 32 characters.
options.prefix	string, nullable	no	S3 and GCS: the object key prefix, e.g. cbox/audit. Objects are written to {prefix}/{yyyy}/{mm}/{dd}/{hh}/{batch}.ndjson.gz. At most 512 characters.
options.access_key_id	string, nullable	no	S3 with an access key: the IAM access key ID. Its secret access key is the stream's secret. At most 128 characters.
options.role_arn	string, nullable	no	S3 with an assumed role: the IAM role the platform assumes. No secret is stored; the role's trust policy must require the stream's external_id. At most 2048 characters.
options.sse	string, nullable	no	S3: server-side encryption requested on every object. Left out, the bucket's default. One of AES256, aws:kms.
options.kms_key_id	string, nullable	no	S3 with aws:kms: the KMS key ID, alias or ARN. At most 2048 characters.
options.path_style	boolean, nullable	no	S3: path-style addressing. Default: virtual-hosted on AWS, path-style on a custom endpoint (MinIO, R2).
options.gzip	boolean, nullable	no	S3 and GCS: gzip each object (.ndjson.gz). Default true.
organization_id	string, nullable	no	The organization it belongs to; it carries that organization's traffic only. Send this or environment_wide. At most 64 characters.
environment_wide	boolean	no	True to make it the environment's own, carrying EVERY organization's traffic. Send this or organization_id.

log_streams.delete

Delete an audit log stream. Nothing more is delivered to its endpoint.

REST	DELETE /api/v1/log-streams/{id} → 204
Scope	log_streams:write — required of the key or token.
Danger	destructive
MCP tool	log_streams_delete
CLI	cbox id log_streams delete <id>

Input	Type	Required	Description
id	string (path)	yes	The log stream id.

log_streams.get

Get one audit log stream: destination, endpoint, auth scheme, owner and health. Never its secret.

REST	GET /api/v1/log-streams/{id} → 200
Scope	log_streams:read — required of the key or token.
Danger	read
MCP tool	log_streams_get
CLI	cbox id log_streams get <id>

Input	Type	Required	Description
id	string (path)	yes	The log stream id.

log_streams.list

List the SIEM destinations this environment's audit trail is streamed to, and whether each is enabled. Never a secret.

REST	GET /api/v1/log-streams → 200
Scope	log_streams:read — required of the key or token.
Danger	read
MCP tool	log_streams_list
CLI	cbox id log_streams list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

log_streams.test

Send one test event to a log stream now and report whether the destination accepted it, and if not, why.

REST	POST /api/v1/log-streams/{id}/test → 200
Scope	log_streams:write — required of the key or token.
Danger	write
MCP tool	log_streams_test
CLI	cbox id log_streams test <id>

Input	Type	Required	Description
id	string (path)	yes	The log stream's id.

log_streams.update

Change an audit log stream's name, destination, endpoint, options or credential (re-validated; resets its circuit breaker), or disable (enabled: false) / resume (enabled: true) it.

REST	PATCH /api/v1/log-streams/{id} → 200
Scope	log_streams:write — required of the key or token.
Danger	critical
MCP tool	log_streams_update
CLI	cbox id log_streams update <id>
Secret	data.secret — shown once, never kept for an idempotent replay

Input	Type	Required	Description
id	string (path)	yes	The log stream id.
name	string	no	At most 190 characters.
destination	string	no	Changing it starts the stream's options and credential afresh. One of splunk_hec, elastic_ecs, graylog_gelf, cef_http, generic_json, datadog, s3, gcs.
endpoint_url	string (uri), nullable	no	An HTTP collector's URL; for Datadog, S3 and GCS empty means the destination's own endpoint. At most 2048 characters.
auth	string	no	An HTTP collector only. One of none, bearer, splunk, hmac.
secret	string, nullable	no	A new credential (token, API key, secret access key or service-account JSON key). Left out, the current one is kept. Never echoed. At most 8192 characters.
options	object	no	Datadog, S3 and GCS only: the destination's settings. An HTTP collector takes none.
options.site	string, nullable	no	Datadog: the site your account lives on — the domain you sign in at, e.g. datadoghq.eu for EU1. Default datadoghq.com (US1). An API key only works on its own site. One of datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, ddog-gov.com.
options.service	string, nullable	no	Datadog: the service attribute on every entry. Default: this platform's name. At most 100 characters.
options.source	string, nullable	no	Datadog: the ddsource attribute. Default cbox. At most 100 characters.
options.tags	list of string, nullable	no	Datadog: key:value tags (ddtags) on every entry, e.g. env:prod. At most 100 items.
options.hostname	string, nullable	no	Datadog: the hostname attribute. Default: this platform's host. At most 255 characters.
options.bucket	string, nullable	no	S3 and GCS: the bucket objects are written to. At most 222 characters.
options.region	string, nullable	no	S3: the bucket's AWS Region, e.g. eu-west-1 (auto for Cloudflare R2). At most 32 characters.
options.prefix	string, nullable	no	S3 and GCS: the object key prefix, e.g. cbox/audit. Objects are written to {prefix}/{yyyy}/{mm}/{dd}/{hh}/{batch}.ndjson.gz. At most 512 characters.
options.access_key_id	string, nullable	no	S3 with an access key: the IAM access key ID. Its secret access key is the stream's secret. At most 128 characters.
options.role_arn	string, nullable	no	S3 with an assumed role: the IAM role the platform assumes. No secret is stored; the role's trust policy must require the stream's external_id. At most 2048 characters.
options.sse	string, nullable	no	S3: server-side encryption requested on every object. Left out, the bucket's default. One of AES256, aws:kms.
options.kms_key_id	string, nullable	no	S3 with aws:kms: the KMS key ID, alias or ARN. At most 2048 characters.
options.path_style	boolean, nullable	no	S3: path-style addressing. Default: virtual-hosted on AWS, path-style on a custom endpoint (MinIO, R2).
options.gzip	boolean, nullable	no	S3 and GCS: gzip each object (.ndjson.gz). Default true.
enabled	boolean	no	True to deliver; false to stop, keeping what is pending.

Members

members.add

Add an existing user to an organization on a tier (admin or member), optionally with access roles. Name them by user_id or email.

REST	POST /api/v1/organizations/{organization_id}/members → 201
Scope	members:write — required of the key or token.
Danger	write
MCP tool	members_add
CLI	cbox id members add <organization_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
user_id	string	no	The user to add. Or name them by email. At most 64 characters.
email	string (email)	no	The address of the user to add, instead of user_id. At most 190 characters.
role	string	no	The tier. Default member; ownership moves with transfer-ownership. One of admin, member.
roles	list of string	no	Access roles to grant in the organization: ids, or manifest keys of client_id's app. At most 50 items.
client_id	string, nullable	no	The app whose manifest keys roles are. At most 255 characters.

members.list

List an organization's members, a page at a time, with each one's tier, status, name and email.

REST	GET /api/v1/organizations/{organization_id}/members → 200
Scope	members:read — required of the key or token.
Danger	read
MCP tool	members_list
CLI	cbox id members list <organization_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

members.remove

Remove a member from an organization, with every role they held there. The last owner cannot be removed.

REST	DELETE /api/v1/organizations/{organization_id}/members/{user_id} → 204
Scope	members:write — required of the key or token.
Danger	destructive
MCP tool	members_remove
CLI	cbox id members remove <organization_id> <user_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
user_id	string (path)	yes	The member's user id. At most 64 characters.

members.update

Change a member's tier to admin or member. Ownership moves with transfer-ownership; the last owner cannot be demoted.

REST	PATCH /api/v1/organizations/{organization_id}/members/{user_id} → 200
Scope	members:write — required of the key or token.
Danger	write
MCP tool	members_update
CLI	cbox id members update <organization_id> <user_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
user_id	string (path)	yes	The member's user id. At most 64 characters.
role	string	yes	One of admin, member.

Organizations

organizations.create

Create an organization in this environment, optionally with an existing user as its owner, a parent and metadata.

REST	POST /api/v1/organizations → 201
Scope	organizations:write — required of the key or token.
Danger	write
MCP tool	organizations_create
CLI	cbox id organizations create

Input	Type	Required	Description
name	string	yes	At most 190 characters.
slug	string, nullable	no	Letters, digits, dashes and underscores. Send your own to make a retry fail with slug_taken instead of creating a second one. At most 190 characters.
type	string	no	Default customer. One of customer, reseller.
parent_id	string, nullable	no	An organization of this environment to nest it under. At most 64 characters.
owner_user_id	string, nullable	no	An existing user of this environment, who becomes its owner. At most 64 characters.
metadata	object	no	Free-form text values the integrator keeps on the organization.

organizations.delete

Archive an organization: everyone in it loses access at once. The records are kept for the audit trail.

REST	DELETE /api/v1/organizations/{id} → 200
Scope	organizations:write — required of the key or token.
Danger	destructive
MCP tool	organizations_delete
CLI	cbox id organizations delete <id>

Input	Type	Required	Description
id	string (path)	yes	The organization id. At most 64 characters.

organizations.domains.add

Claim an email domain (acme.com) for an organization. Returns the DNS TXT record to publish before verifying it.

REST	POST /api/v1/organizations/{organization_id}/domains → 201
Scope	organizations:write — required of the key or token.
Danger	write
MCP tool	organizations_domains_add
CLI	cbox id organizations domains add <organization_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
domain	string	yes	A domain name — acme.com, not an address or a URL. At most 190 characters.

organizations.domains.capture

Turn capture on or off for a verified domain: with it on, everyone with an address there signs in through the organization's SSO.

REST	PUT /api/v1/organizations/{organization_id}/domains/{domain_id}/capture → 200
Scope	organizations:write — required of the key or token.
Danger	critical
MCP tool	organizations_domains_capture
CLI	cbox id organizations domains capture <organization_id> <domain_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
domain_id	string (path)	yes	The claimed domain's id. At most 64 characters.
enabled	boolean	yes	Whether the domain captures sign-ins.

organizations.domains.list

List the email domains an organization claims, whether each is verified and captured, and the DNS TXT record that proves it.

REST	GET /api/v1/organizations/{organization_id}/domains → 200
Scope	organizations:read — required of the key or token.
Danger	read
MCP tool	organizations_domains_list
CLI	cbox id organizations domains list <organization_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.

organizations.domains.remove

Remove a claimed email domain from an organization. Capture on it ends.

REST	DELETE /api/v1/organizations/{organization_id}/domains/{domain_id} → 204
Scope	organizations:write — required of the key or token.
Danger	destructive
MCP tool	organizations_domains_remove
CLI	cbox id organizations domains remove <organization_id> <domain_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
domain_id	string (path)	yes	The claimed domain's id. At most 64 characters.

organizations.domains.verify

Check a claimed domain's DNS TXT record and mark the domain verified if it is published.

REST	POST /api/v1/organizations/{organization_id}/domains/{domain_id}/verify → 200
Scope	organizations:write — required of the key or token.
Danger	write
MCP tool	organizations_domains_verify
CLI	cbox id organizations domains verify <organization_id> <domain_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
domain_id	string (path)	yes	The claimed domain's id. At most 64 characters.

organizations.get

Get one organization of this environment by id.

REST	GET /api/v1/organizations/{id} → 200
Scope	organizations:read — required of the key or token.
Danger	read
MCP tool	organizations_get
CLI	cbox id organizations get <id>

Input	Type	Required	Description
id	string (path)	yes	The organization id. At most 64 characters.

organizations.list

List the organizations in this environment, a page at a time. Narrow by a q fragment of the name or slug, or by status.

REST	GET /api/v1/organizations → 200
Scope	organizations:read — required of the key or token.
Danger	read
MCP tool	organizations_list
CLI	cbox id organizations list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.
q	string	no	Only organizations whose name or slug contains this. At most 190 characters.
status	string	no	Only organizations in this state. One of active, suspended, deleted.

organizations.reactivate

Lift an organization's suspension so its members can sign in again.

REST	POST /api/v1/organizations/{id}/reactivate → 200
Scope	organizations:write — required of the key or token.
Danger	write
MCP tool	organizations_reactivate
CLI	cbox id organizations reactivate <id>

Input	Type	Required	Description
id	string (path)	yes	The organization id. At most 64 characters.

organizations.suspend

Suspend an organization: its members cannot sign in to it until it is reactivated.

REST	POST /api/v1/organizations/{id}/suspend → 200
Scope	organizations:write — required of the key or token.
Danger	write
MCP tool	organizations_suspend
CLI	cbox id organizations suspend <id>

Input	Type	Required	Description
id	string (path)	yes	The organization id. At most 64 characters.

organizations.transfer_ownership

Make a member the owner of an organization. Every current owner stays on as an admin; from inside the organization, only its owner may hand it over.

REST	POST /api/v1/organizations/{id}/transfer-ownership → 200
Scope	organizations:write — required of the key or token.
Danger	critical
MCP tool	organizations_transfer_ownership
CLI	cbox id organizations transfer_ownership <id>

Input	Type	Required	Description
id	string (path)	yes	The organization id. At most 64 characters.
user_id	string	yes	The member who becomes the owner — an active member already. At most 64 characters.

organizations.update

Rename an organization, change its slug, or replace its metadata. Only what is sent changes.

REST	PATCH /api/v1/organizations/{id} → 200
Scope	organizations:write — required of the key or token.
Danger	write
MCP tool	organizations_update
CLI	cbox id organizations update <id>

Input	Type	Required	Description
id	string (path)	yes	The organization id. At most 64 characters.
name	string	no	At least 1 characters. At most 190 characters.
slug	string	no	Letters, digits, dashes and underscores. At least 1 characters. At most 190 characters.
metadata	object	no	Replaces the metadata as a whole; null or {} clears it.

Outbound provisioning

provisioning.targets.create

Register a downstream app this platform pushes an organization's people to over SCIM, or every organization's with environment_wide.

REST	POST /api/v1/provisioning-targets → 201
Scope	provisioning:write — required of the key or token.
Danger	critical
MCP tool	provisioning_targets_create
CLI	cbox id provisioning targets create

Input	Type	Required	Description
organization_id	string, nullable	no	The organization the target belongs to. Send this or environment_wide. At most 64 characters.
environment_wide	boolean	no	True to make the target the environment's own rather than one organization's. Send this or organization_id.
name	string	yes	What administrators call it: "Slack", "Salesforce". At most 190 characters.
base_url	string (uri)	yes	The target's SCIM base URL. Must be a public address. At most 500 characters.
auth_scheme	string	yes	bearer (a long-lived token the app issued you) or oauth2_client_credentials (a token fetched before each batch). One of bearer, oauth2_client_credentials.
secret	string	yes	The bearer token, or the OAuth client secret. Write-only. At most 4096 characters.
token_url	string (uri), nullable	no	oauth2_client_credentials: the token endpoint. At most 2048 characters.
client_id	string, nullable	no	oauth2_client_credentials: the client id. At most 400 characters.
scope	string, nullable	no	oauth2_client_credentials: the scope to ask for, if the app wants one. At most 400 characters.

provisioning.targets.delete

Delete a downstream SCIM target. Nothing more is pushed to it.

REST	DELETE /api/v1/provisioning-targets/{id} → 204
Scope	provisioning:write — required of the key or token.
Danger	destructive
MCP tool	provisioning_targets_delete
CLI	cbox id provisioning targets delete <id>

Input	Type	Required	Description
id	string (path)	yes	The target's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

provisioning.targets.get

Read one downstream SCIM target: its URL, auth scheme, status and last error. Never its credential.

REST	GET /api/v1/provisioning-targets/{id} → 200
Scope	provisioning:read — required of the key or token.
Danger	read
MCP tool	provisioning_targets_get
CLI	cbox id provisioning targets get <id>

Input	Type	Required	Description
id	string (path)	yes	The target's id.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

provisioning.targets.list

List the downstream SCIM targets people are provisioned to, optionally for one organization, with their failures. Never their credentials.

REST	GET /api/v1/provisioning-targets → 200
Scope	provisioning:read — required of the key or token.
Danger	read
MCP tool	provisioning_targets_list
CLI	cbox id provisioning targets list

Input	Type	Required	Description
organization_id	string, nullable	no	Only this organization's. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

provisioning.targets.status.set

Pause or resume pushing people to a downstream SCIM target.

REST	POST /api/v1/provisioning-targets/{id}/status → 200
Scope	provisioning:write — required of the key or token.
Danger	write
MCP tool	provisioning_targets_status_set
CLI	cbox id provisioning targets status set <id>

Input	Type	Required	Description
id	string (path)	yes	The target's id.
active	boolean	yes	true to resume pushing, false to pause.
organization_id	string, nullable	no	Only if it is this organization's; anything else is a 404. At most 64 characters.

Publishable keys

frontend_keys.create

Create a publishable frontend key for a browser app, usable only from the origins listed. The key is public by design.

REST	POST /api/v1/frontend-keys → 201
Scope	frontend_keys:write — required of the key or token.
Danger	write
MCP tool	frontend_keys_create
CLI	cbox id frontend_keys create

Input	Type	Required	Description
name	string	yes	What the key is for, so a person recognises it later. At most 120 characters.
mode	string	yes	test or live; it is in the key's prefix. One of test, live.
origins	list of string	yes	The exact origins (scheme, host, port) allowed to present the key, for example https://app.example.com. At least one. At least 1 items. At most 50 items.

frontend_keys.list

List the publishable frontend keys browser apps present to the Frontend API, in full, with their allowed origins.

REST	GET /api/v1/frontend-keys → 200
Scope	frontend_keys:read — required of the key or token.
Danger	read
MCP tool	frontend_keys_list
CLI	cbox id frontend_keys list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

frontend_keys.revoke

Revoke a publishable frontend key. Pages still holding it stop working immediately.

REST	DELETE /api/v1/frontend-keys/{id} → 204
Scope	frontend_keys:write — required of the key or token.
Danger	destructive
MCP tool	frontend_keys_revoke
CLI	cbox id frontend_keys revoke <id>

Input	Type	Required	Description
id	string (path)	yes	The key's id.

frontend_keys.set_origins

Replace the exact list of origins allowed to present a publishable frontend key. Live on the next request.

REST	PUT /api/v1/frontend-keys/{id}/origins → 200
Scope	frontend_keys:write — required of the key or token.
Danger	write
MCP tool	frontend_keys_set_origins
CLI	cbox id frontend_keys set_origins <id>

Input	Type	Required	Description
id	string (path)	yes	The key's id.
origins	list of string	yes	The exact origins (scheme, host, port) allowed to present the key, for example https://app.example.com. At least one. At least 1 items. At most 50 items.

Roles

members.roles.grant

Grant a member an access role inside one organization, with the environment's authority (staff-only roles included) — or, from inside the organization, one its administrators may hand out. Name the role by id, or by manifest key with client_id.

REST	PUT /api/v1/organizations/{organization_id}/members/{user_id}/roles/{role_id} → 200
Scope	roles:write — required of the key or token.
Danger	write
MCP tool	members_roles_grant
CLI	cbox id members roles grant <organization_id> <user_id> <role_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
user_id	string (path)	yes	The member's user id. At most 64 characters.
role_id	string (path)	yes	The role id, or its manifest key with client_id. At most 190 characters.
client_id	string	no	The app whose manifest key role_id is. At most 255 characters.

members.roles.list

List the access roles a member holds inside one organization (staff roles held everywhere are listed under the user).

REST	GET /api/v1/organizations/{organization_id}/members/{user_id}/roles → 200
Scope	roles:read — required of the key or token.
Danger	read
MCP tool	members_roles_list
CLI	cbox id members roles list <organization_id> <user_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
user_id	string (path)	yes	The member's user id. At most 64 characters.

members.roles.revoke

Take an access role back from a member inside one organization. Name the role by id, or by manifest key with client_id.

REST	DELETE /api/v1/organizations/{organization_id}/members/{user_id}/roles/{role_id} → 204
Scope	roles:write — required of the key or token.
Danger	destructive
MCP tool	members_roles_revoke
CLI	cbox id members roles revoke <organization_id> <user_id> <role_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization id. At most 64 characters.
user_id	string (path)	yes	The member's user id. At most 64 characters.
role_id	string (path)	yes	The role id, or its manifest key with client_id. At most 190 characters.
client_id	string	no	The app whose manifest key role_id is. At most 255 characters.

permissions.create

Author a manual feature:action permission, shared with the environment (organization_id null) or one organization's own.

REST	POST /api/v1/permissions → 201
Scope	role_definitions:write — required of the key or token.
Danger	write
MCP tool	permissions_create
CLI	cbox id permissions create

Input	Type	Required	Description
name	string	yes	The key: a feature and an action joined by a colon, like invoices:create. At most 120 characters.
description	string, nullable	no	At most 500 characters.
organization_id	string, nullable	no	The organization it belongs to; null for the environment's shared tier. At most 64 characters.
tenant_assignable	boolean	no	Shared tier only: whether organizations may compose it into their own roles. Default false; always true on an organization's own.

permissions.delete

Delete a manual permission: every role carrying it loses it first.

REST	DELETE /api/v1/permissions/{id} → 204
Scope	role_definitions:write — required of the key or token.
Danger	destructive
MCP tool	permissions_delete
CLI	cbox id permissions delete <id>

Input	Type	Required	Description
id	string (path)	yes	The permission id. At most 64 characters.

permissions.list

List the permission catalogue roles are composed from, a page at a time. Narrow by client_id (one app's), organization_id (what it can see) or a q fragment.

REST	GET /api/v1/permissions → 200
Scope	roles:read — required of the key or token.
Danger	read
MCP tool	permissions_list
CLI	cbox id permissions list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.
organization_id	string	no	Also the permissions this organization authored for itself. At most 64 characters.
client_id	string	no	Only the permissions this app declared. At most 255 characters.
q	string	no	Only permissions whose key or description contains this. At most 120 characters.

permissions.update

Change a manual permission's description, and on the shared tier whether organizations may use it. The key itself never changes.

REST	PATCH /api/v1/permissions/{id} → 200
Scope	role_definitions:write — required of the key or token.
Danger	write
MCP tool	permissions_update
CLI	cbox id permissions update <id>

Input	Type	Required	Description
id	string (path)	yes	The permission id. At most 64 characters.
description	string, nullable	no	At most 500 characters.
tenant_assignable	boolean	no	Shared tier only: whether organizations may compose it into their own roles.

roles.create

Define a role for one organization, or (organization_id null) for the whole environment, optionally scoped to one app, with its opening permissions.

REST	POST /api/v1/roles → 201
Scope	role_definitions:write — required of the key or token.
Danger	write
MCP tool	roles_create
CLI	cbox id roles create

Input	Type	Required	Description
name	string	yes	At most 120 characters.
description	string, nullable	no	At most 500 characters.
organization_id	string, nullable	no	The organization it belongs to; null defines it for every organization in the environment. At most 64 characters.
client_id	string, nullable	no	The app whose tokens it is stamped into; null for every app. At most 190 characters.
permissions	list of string	no	Permission ids to grant it from the start. At most 200 items.

roles.delete

Delete a role: everyone who holds it loses it. An app-declared role is removed from the app's manifest instead.

REST	DELETE /api/v1/roles/{id} → 204
Scope	role_definitions:write — required of the key or token.
Danger	destructive
MCP tool	roles_delete
CLI	cbox id roles delete <id>

Input	Type	Required	Description
id	string (path)	yes	The role id. At most 64 characters.

roles.get

Get one role and the permissions it carries. Name it by id, or by manifest key with client_id.

REST	GET /api/v1/roles/{id} → 200
Scope	roles:read — required of the key or token.
Danger	read
MCP tool	roles_get
CLI	cbox id roles get <id>

Input	Type	Required	Description
id	string (path)	yes	The role id, or its manifest key with client_id. At most 190 characters.
client_id	string	no	The app whose manifest key id is. At most 255 characters.

roles.list

List the roles that can be granted in this environment, with their permissions. Narrow by client_id (one app's) or organization_id (grantable there).

REST	GET /api/v1/roles → 200
Scope	roles:read — required of the key or token.
Danger	read
MCP tool	roles_list
CLI	cbox id roles list

Input	Type	Required	Description
client_id	string	no	Only the roles this app declared. At most 255 characters.
organization_id	string	no	Only the roles that can be granted in this organization. At most 64 characters.

roles.permissions.grant

Add a permission to a role: everyone holding the role gains it. The permission must be unscoped or declared by the role's own app.

REST	PUT /api/v1/roles/{id}/permissions/{permission_id} → 200
Scope	role_definitions:write — required of the key or token.
Danger	write
MCP tool	roles_permissions_grant
CLI	cbox id roles permissions grant <id> <permission_id>

Input	Type	Required	Description
id	string (path)	yes	The role id. At most 64 characters.
permission_id	string (path)	yes	The permission id. At most 64 characters.

roles.permissions.revoke

Remove a permission from a role: everyone holding the role loses it.

REST	DELETE /api/v1/roles/{id}/permissions/{permission_id} → 200
Scope	role_definitions:write — required of the key or token.
Danger	destructive
MCP tool	roles_permissions_revoke
CLI	cbox id roles permissions revoke <id> <permission_id>

Input	Type	Required	Description
id	string (path)	yes	The role id. At most 64 characters.
permission_id	string (path)	yes	The permission id. At most 64 characters.

roles.update

Rename a role or change its description. An app-declared role is changed in the app's manifest instead.

REST	PATCH /api/v1/roles/{id} → 200
Scope	role_definitions:write — required of the key or token.
Danger	write
MCP tool	roles_update
CLI	cbox id roles update <id>

Input	Type	Required	Description
id	string (path)	yes	The role id. At most 64 characters.
name	string	no	At least 1 characters. At most 120 characters.
description	string, nullable	no	At most 500 characters.

users.environment_roles.get

Whether a user holds a role everywhere in this environment: the grant, or 404. Name the role by id, or by manifest key with client_id.

REST	GET /api/v1/users/{id}/environment-roles/{role_id} → 200
Scope	roles:read — required of the key or token.
Danger	read
MCP tool	users_environment_roles_get
CLI	cbox id users environment_roles get <id> <role_id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.
role_id	string (path)	yes	The role id, or its manifest key with client_id. At most 190 characters.
client_id	string	no	The app whose manifest key role_id is. At most 255 characters.

users.environment_roles.grant

Grant a user a staff role: held everywhere in this environment, in every organization. Name the role by id, or by manifest key with client_id.

REST	PUT /api/v1/users/{id}/environment-roles/{role_id} → 200
Scope	roles:write — required of the key or token.
Danger	critical
MCP tool	users_environment_roles_grant
CLI	cbox id users environment_roles grant <id> <role_id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.
role_id	string (path)	yes	The role id, or its manifest key with client_id. At most 190 characters.
client_id	string	no	The app whose manifest key role_id is. At most 255 characters.

users.environment_roles.list

List the staff roles a user holds everywhere in this environment (not those held inside one organization).

REST	GET /api/v1/users/{id}/environment-roles → 200
Scope	roles:read — required of the key or token.
Danger	read
MCP tool	users_environment_roles_list
CLI	cbox id users environment_roles list <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.

users.environment_roles.revoke

Take a staff role (held everywhere in this environment) back from a user.

REST	DELETE /api/v1/users/{id}/environment-roles/{role_id} → 204
Scope	roles:write — required of the key or token.
Danger	destructive
MCP tool	users_environment_roles_revoke
CLI	cbox id users environment_roles revoke <id> <role_id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.
role_id	string (path)	yes	The role id, or its manifest key with client_id. At most 190 characters.
client_id	string	no	The app whose manifest key role_id is. At most 255 characters.

SAML apps

saml_apps.create

Register a SAML app that signs people in with their account here. Decides where assertions — and their attributes — are sent.

REST	POST /api/v1/saml-apps → 201
Scope	saml_apps:write — required of the key or token.
Danger	critical
MCP tool	saml_apps_create
CLI	cbox id saml_apps create

Input	Type	Required	Description
entity_id	string	yes	The application's SAML EntityID, unique in this environment. At most 500 characters.
acs_url	string (uri)	yes	Where assertions are posted: https (http only on localhost), absolute, no fragment. At most 1000 characters.
name_id_format	string	no	The NameID format URN. Default emailAddress. One of urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, urn:oasis:names:tc:SAML:2.0:nameid-format:transient, urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
name_id_attribute	string	no	The person's field the NameID is read from. Default email. At most 120 characters.
attribute_mappings	list of object	no	The attributes the assertion carries. Sent, it is the COMPLETE list afterwards. At most 100 items.
attribute_mappings[].attribute	string	yes	The attribute name the assertion emits: email, displayName. At most 190 characters.
attribute_mappings[].field	string	yes	The person's field it is read from: email, name. At most 190 characters.
want_authn_requests_signed	boolean	no	Verify the application's signature on every AuthnRequest. Needs a certificate.
certificate	string, nullable	no	The application's signing certificate (PEM). Write-only; left out or null keeps the one on file. At most 20000 characters.
organization_id	string, nullable	no	The organization that owns the application: only its active members are signed in to it, and the assertion names it. Null makes it environment-wide — every person in the environment may sign in to it. At most 64 characters.

saml_apps.delete

Remove a SAML app. People can no longer sign in to it with their account here.

REST	DELETE /api/v1/saml-apps/{id} → 204
Scope	saml_apps:write — required of the key or token.
Danger	critical
MCP tool	saml_apps_delete
CLI	cbox id saml_apps delete <id>

Input	Type	Required	Description
id	string (path)	yes	The SAML app's id.

saml_apps.get

Read one SAML app: its entity id, ACS URL, NameID and attribute mappings. Never its certificate.

REST	GET /api/v1/saml-apps/{id} → 200
Scope	saml_apps:read — required of the key or token.
Danger	read
MCP tool	saml_apps_get
CLI	cbox id saml_apps get <id>

Input	Type	Required	Description
id	string (path)	yes	The SAML app's id.

saml_apps.list

List the SAML apps that trust this environment as their identity provider.

REST	GET /api/v1/saml-apps → 200
Scope	saml_apps:read — required of the key or token.
Danger	read
MCP tool	saml_apps_list
CLI	cbox id saml_apps list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

saml_apps.update

Change a SAML app's entity id, ACS URL, NameID, attribute mappings, signing certificate or owning organization.

REST	PATCH /api/v1/saml-apps/{id} → 200
Scope	saml_apps:write — required of the key or token.
Danger	critical
MCP tool	saml_apps_update
CLI	cbox id saml_apps update <id>

Input	Type	Required	Description
id	string (path)	yes	The SAML app's id.
entity_id	string	no	The application's SAML EntityID, unique in this environment. At most 500 characters.
acs_url	string (uri)	no	Where assertions are posted: https (http only on localhost), absolute, no fragment. At most 1000 characters.
name_id_format	string	no	The NameID format URN. Default emailAddress. One of urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, urn:oasis:names:tc:SAML:2.0:nameid-format:transient, urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
name_id_attribute	string	no	The person's field the NameID is read from. Default email. At most 120 characters.
attribute_mappings	list of object	no	The attributes the assertion carries. Sent, it is the COMPLETE list afterwards. At most 100 items.
attribute_mappings[].attribute	string	yes	The attribute name the assertion emits: email, displayName. At most 190 characters.
attribute_mappings[].field	string	yes	The person's field it is read from: email, name. At most 190 characters.
want_authn_requests_signed	boolean	no	Verify the application's signature on every AuthnRequest. Needs a certificate.
certificate	string, nullable	no	The application's signing certificate (PEM). Write-only; left out or null keeps the one on file. At most 20000 characters.
organization_id	string, nullable	no	The organization that owns the application: only its active members are signed in to it, and the assertion names it. Null makes it environment-wide — every person in the environment may sign in to it. At most 64 characters.

Secret keys

keys.create

Mint a management key for this environment, at most as wide as the caller. The value is returned once, as token.

REST	POST /api/v1/keys → 201
Scope	keys:write — required of the key or token.
Danger	critical
MCP tool	keys_create
CLI	cbox id keys create
Secret	data.token — shown once, never kept for an idempotent replay

Input	Type	Required	Description
name	string	yes	At most 120 characters.
scopes	list of string	yes	The scopes the key carries. From a key: a subset of its own. At least 1 items. At most 64 items.
expires_at	string (date-time), nullable	no	When it stops working. From a key: required to be no later than the parent; defaults to the latest allowed.
description	string, nullable	no	What it is for — shown beside it in the console. At most 500 characters.
require_approval	object	no	Which of this key's actions need its owner's approval on their device first. From a key: never weaker than its own.
require_approval.min_danger	string, nullable	no	Every action at or above this danger waits for a person's approval. One of write, destructive, critical.
require_approval.actions	list of string	no	These actions wait for approval whatever their danger. At most 100 items.

keys.list

List this environment's management keys (names, scopes, parents, expiry, last use — never their values).

REST	GET /api/v1/keys → 200
Scope	keys:read — required of the key or token.
Danger	read
MCP tool	keys_list
CLI	cbox id keys list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

keys.revoke

Revoke a management key and every key it minted, immediately.

REST	DELETE /api/v1/keys/{id} → 204
Scope	keys:write — required of the key or token.
Danger	destructive
MCP tool	keys_revoke
CLI	cbox id keys revoke <id>

Input	Type	Required	Description
id	string (path)	yes	The key to revoke.

keys.rotate

Rotate a management key: mint a successor with the same scopes and retire the old one after a grace period.

REST	POST /api/v1/keys/{id}/rotate → 201
Scope	keys:write — required of the key or token.
Danger	critical
MCP tool	keys_rotate
CLI	cbox id keys rotate <id>
Secret	data.token — shown once, never kept for an idempotent replay

Input	Type	Required	Description
id	string (path)	yes	The key to rotate.
grace_hours	integer	no	How long the old key keeps working. Default 24. At least 0. At most 168.

Sign-in

signin.policy.get

Read the authentication policy (password, MFA, SSO, lockout): the environment baseline, or one organization's effective rules and override.

REST	GET /api/v1/sign-in/policy → 200
Scope	signin:read — required of the key or token.
Danger	read
MCP tool	signin_policy_get
CLI	cbox id signin policy get

Input	Type	Required	Description
organization_id	string	no	Read one organization's rules. Left out, the environment baseline. At most 64 characters.

signin.policy.inherit

Drop one organization's authentication policy override, so it inherits the environment baseline again.

REST	DELETE /api/v1/sign-in/policy/organizations/{organization_id} → 204
Scope	signin:write — required of the key or token.
Danger	critical
MCP tool	signin_policy_inherit
CLI	cbox id signin policy inherit <organization_id>

Input	Type	Required	Description
organization_id	string (path)	yes	The organization whose override to drop. At most 64 characters.

signin.policy.update

Change the authentication policy of the environment baseline, or tighten one organization's override. Requiring SSO signs out password sessions.

REST	PATCH /api/v1/sign-in/policy → 200
Scope	signin:write — required of the key or token.
Danger	critical
MCP tool	signin_policy_update
CLI	cbox id signin policy update

Input	Type	Required	Description
organization_id	string, nullable	no	Write this organization's override. Left out, the environment baseline. At most 64 characters.
min_length	integer	no	Minimum password length. At least 8. At most 128.
require_breach_check	boolean	no	Refuse passwords that appear in known breaches.
max_age_days	integer, nullable	no	Days before a password must be changed; null for no limit. At least 1. At most 3650.
reuse_history	integer	no	How many previous passwords may not be reused. At least 0. At most 24.
mfa	string	no	Whether a second factor is off, optional or required. One of off, optional, required.
sso	string	no	Whether SSO is off, preferred, or required — required refuses every other way in and signs out password sessions. One of off, preferred, required.
lockout_threshold	integer, nullable	no	Failed attempts before an account is locked; null for the deployment default (10 inside 15 minutes unless CBOX_ID_LOCKOUT_THRESHOLD says otherwise). At least 3. At most 100.

signin.self_service_signup.set

Switch self-service sign-up on or off: whether people can create an account and their own organization in this environment.

REST	PUT /api/v1/sign-in/self-service-signup → 200
Scope	signin:write — required of the key or token.
Danger	critical
MCP tool	signin_self_service_signup_set
CLI	cbox id signin self_service_signup set

Input	Type	Required	Description
enabled	boolean	yes	On: anyone may create an account and their own organization. Off: people join by invitation.

signin.social.delete

Stop offering a social login provider. People who used it keep their accounts.

REST	DELETE /api/v1/sign-in/social-providers/{id} → 204
Scope	signin:write — required of the key or token.
Danger	critical
MCP tool	signin_social_delete
CLI	cbox id signin social delete <id>

Input	Type	Required	Description
id	string (path)	yes	The provider's id.
organization_id	string, nullable	no	Only remove it if it is this organization's. At most 64 characters.

signin.social.list

List the social login providers (Google, GitHub, Apple…) enabled in this environment, optionally for one organization.

REST	GET /api/v1/sign-in/social-providers → 200
Scope	signin:read — required of the key or token.
Danger	read
MCP tool	signin_social_list
CLI	cbox id signin social list

Input	Type	Required	Description
organization_id	string	no	Only this organization's providers. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

signin.social.set

Enable a social login provider (Google, GitHub, Apple…) for one organization with its client credentials. The secret is never returned.

REST	POST /api/v1/sign-in/social-providers → 201
Scope	signin:write — required of the key or token.
Danger	critical
MCP tool	signin_social_set
CLI	cbox id signin social set

Input	Type	Required	Description
organization_id	string	yes	The organization whose sign-in page offers it. At most 64 characters.
provider	string	yes	The catalogue key: google, microsoft, okta, auth0, keycloak, gitlab, slack, github, discord, apple, facebook, linkedin, bitbucket, xero, intuit. At most 100 characters.
client_id	string	yes	The client id from your own account with the provider. For Apple, the Services ID. At most 400 characters.
client_secret	string, nullable	no	The client secret. Write-only. Not used by Apple, which signs its own. At most 5000 characters.
parameters	object	no	What the chosen provider needs besides its client credentials — Microsoft's directory, Okta's domain, Apple's team id, key id and private key.
parameters.directory	string, nullable	no	Directory (tenant) ID (Microsoft Entra ID). At most 5000 characters.
parameters.domain	string, nullable	no	Okta domain (Okta). At most 5000 characters.
parameters.host	string, nullable	no	Keycloak host (Keycloak). At most 5000 characters.
parameters.key_id	string, nullable	no	Key ID (Apple). At most 5000 characters.
parameters.private_key	string, nullable	no	Private key (.p8) (Apple). At most 5000 characters.
parameters.realm	string, nullable	no	Realm (Keycloak). At most 5000 characters.
parameters.team_id	string, nullable	no	Team ID (Apple). At most 5000 characters.

Support sessions

support_sessions.end

End a support session now: every token it issued is revoked.

REST	DELETE /api/v1/support-sessions/{id} → 204
Scope	support:write — required of the key or token.
Danger	destructive
MCP tool	support_sessions_end
CLI	cbox id support_sessions end <id>

Input	Type	Required	Description
id	string (path)	yes	The support session id. At most 64 characters.

support_sessions.start

Start a support session: a staff member holding the app's support:impersonate acts as a customer's user in that app, for a reason and at most an hour. Optionally returns the first authorization code.

REST	POST /api/v1/support-sessions → 201
Scope	support:write — required of the key or token.
Danger	critical
MCP tool	support_sessions_start
CLI	cbox id support_sessions start
Secret	data.code — shown once, never kept for an idempotent replay

Input	Type	Required	Description
user_id	string	yes	The customer's user to act as. At most 64 characters.
organization_id	string	yes	The organization they are acted as in — one they are an active member of. At most 64 characters.
client_id	string	yes	The first-party app the session signs in to. At most 255 characters.
actor_user_id	string	yes	The staff member acting. They must hold the app's support:impersonate everywhere. At most 64 characters.
reason	string	yes	Why — on both audit trails and shown to the customer. At most 500 characters.
ttl_minutes	integer	no	How long it lasts. Default and maximum: the configured limit. At least 1. At most 60.
scopes	list of string	no	The scopes its tokens carry; settled to what one API can be audienced. At most 50 items.
redirect_uri	string	no	With code_challenge: return the session's first authorization code for this redirect URI. At most 2048 characters.
code_challenge	string	no	An S256 PKCE challenge: 43 base64url characters. At most 43 characters.
nonce	string, nullable	no	At most 255 characters.

Token vault

token_vault.grants.create

Grant an app (by OAuth client id) the right to lease a stored credential.

REST	POST /api/v1/token-vault/secrets/{id}/grants → 200
Scope	token_vault:write — required of the key or token.
Danger	critical
MCP tool	token_vault_grants_create
CLI	cbox id token_vault grants create <id>

Input	Type	Required	Description
id	string (path)	yes	The secret's id.
organization_id	string, nullable	no	The organization whose vault this is. Left out: the environment's own secrets, a separate collection. At most 64 characters.
client_id	string	yes	The OAuth client id of the app that may lease it. At most 190 characters.

token_vault.grants.delete

Withdraw an app's right to lease a stored credential.

REST	DELETE /api/v1/token-vault/secrets/{id}/grants/{client_id} → 204
Scope	token_vault:write — required of the key or token.
Danger	destructive
MCP tool	token_vault_grants_delete
CLI	cbox id token_vault grants delete <id> <client_id>

Input	Type	Required	Description
id	string (path)	yes	The secret's id.
client_id	string (path)	yes	The OAuth client id whose grant is withdrawn. At most 190 characters.
organization_id	string, nullable	no	The organization whose vault this is. Left out: the environment's own secrets, a separate collection. At most 64 characters.

token_vault.secrets.create

Store a downstream credential (a third-party API key) in an organization's token vault, or the environment's own. The value is sealed and never returned.

REST	POST /api/v1/token-vault/secrets → 201
Scope	token_vault:write — required of the key or token.
Danger	write
MCP tool	token_vault_secrets_create
CLI	cbox id token_vault secrets create

Input	Type	Required	Description
organization_id	string, nullable	no	The organization whose vault this is. Left out: the environment's own secrets, a separate collection. At most 64 characters.
name	string	yes	What it is: "Stripe live key". At most 190 characters.
provider	string	yes	Whose credential it is: "stripe", "openai". At most 190 characters.
secret	string	yes	The credential. Write-only: sealed, never returned. At most 20000 characters.

token_vault.secrets.get

Read one stored credential and the client ids granted to lease it. Never its value.

REST	GET /api/v1/token-vault/secrets/{id} → 200
Scope	token_vault:read — required of the key or token.
Danger	read
MCP tool	token_vault_secrets_get
CLI	cbox id token_vault secrets get <id>

Input	Type	Required	Description
id	string (path)	yes	The secret's id.
organization_id	string, nullable	no	The organization whose vault this is. Left out: the environment's own secrets, a separate collection. At most 64 characters.

token_vault.secrets.list

List the downstream credentials stored in an organization's token vault (or the environment's own): names, providers, status. Never a value.

REST	GET /api/v1/token-vault/secrets → 200
Scope	token_vault:read — required of the key or token.
Danger	read
MCP tool	token_vault_secrets_list
CLI	cbox id token_vault secrets list

Input	Type	Required	Description
organization_id	string, nullable	no	The organization whose vault this is. Left out: the environment's own secrets, a separate collection. At most 64 characters.
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

token_vault.secrets.revoke

Revoke a stored credential permanently. No app can lease it again.

REST	POST /api/v1/token-vault/secrets/{id}/revoke → 200
Scope	token_vault:write — required of the key or token.
Danger	destructive
MCP tool	token_vault_secrets_revoke
CLI	cbox id token_vault secrets revoke <id>

Input	Type	Required	Description
id	string (path)	yes	The secret's id.
organization_id	string, nullable	no	The organization whose vault this is. Left out: the environment's own secrets, a separate collection. At most 64 characters.

token_vault.secrets.rotate

Replace a stored credential's value. Every later lease hands out the new one. The value is never returned.

REST	POST /api/v1/token-vault/secrets/{id}/rotate → 200
Scope	token_vault:write — required of the key or token.
Danger	critical
MCP tool	token_vault_secrets_rotate
CLI	cbox id token_vault secrets rotate <id>

Input	Type	Required	Description
id	string (path)	yes	The secret's id.
organization_id	string, nullable	no	The organization whose vault this is. Left out: the environment's own secrets, a separate collection. At most 64 characters.
secret	string	yes	The new value. Write-only: sealed, never returned. At most 20000 characters.

Users

users.create

Create a user in this environment, optionally with a password, and optionally mail them a one-click sign-in link.

REST	POST /api/v1/users → 201
Scope	users:write — required of the key or token.
Danger	write
MCP tool	users_create
CLI	cbox id users create

Input	Type	Required	Description
email	string (email)	yes	At most 190 characters.
name	string, nullable	no	At most 190 characters.
password	string, nullable	no	Checked against this environment's password policy. Leave out for a user who signs in another way. At least 8 characters. At most 255 characters.
send_sign_in_link	boolean	no	Mail the new user a one-click sign-in link. Default false.

users.deactivate

Deactivate a user: they can no longer sign in, and every OAuth grant they hold is revoked. Never deletes them.

REST	DELETE /api/v1/users/{id} → 200
Scope	users:write — required of the key or token.
Danger	destructive
MCP tool	users_deactivate
CLI	cbox id users deactivate <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.

users.erase

Erase a person (GDPR Art. 17): revoke their sessions and tokens, delete their credentials, memberships and personal data, and pseudonymise their account. Cannot be undone.

REST	POST /api/v1/users/{id}/erase → 200
Scope	users:erase — required of the key or token.
Danger	critical
MCP tool	users_erase
CLI	cbox id users erase <id>

Input	Type	Required	Description
id	string (path)	yes	The user's id.

users.get

Get one user of this environment by id.

REST	GET /api/v1/users/{id} → 200
Scope	users:read — required of the key or token.
Danger	read
MCP tool	users_get
CLI	cbox id users get <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.

users.list

List the users in this environment, a page at a time. Narrow by exact email, a q fragment of the address or name, or status.

REST	GET /api/v1/users → 200
Scope	users:read — required of the key or token.
Danger	read
MCP tool	users_list
CLI	cbox id users list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.
email	string	no	Only the user with exactly this address (case-insensitive). At most 190 characters.
q	string	no	Only users whose address or name contains this. At most 190 characters.
status	string	no	Only users in this state. One of active, disabled, locked.

users.mfa.reset

Reset a user's two-factor authentication: their authenticator and recovery codes are removed and they must enrol again.

REST	DELETE /api/v1/users/{id}/mfa → 204
Scope	users:write — required of the key or token.
Danger	critical
MCP tool	users_mfa_reset
CLI	cbox id users mfa reset <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.

users.password.set

Set a user's password, temporary by default, and mail it to them unless told not to. Signs them out according to revoke.

REST	POST /api/v1/users/{id}/password → 200
Scope	users:write — required of the key or token.
Danger	critical
MCP tool	users_password_set
CLI	cbox id users password set <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.
password	string	yes	The new password. Checked against this environment's password policy. At most 200 characters.
reason	string	yes	Why — recorded on the audit trail. At most 200 characters.
temporary	boolean	no	The user must choose a new password at their next sign-in. Default true.
expires_in_hours	integer	no	A temporary password stops working after this many hours. 0 or absent: until changed. At least 0. At most 8760.
revoke	string	no	How much existing access to end. Default sessions_and_tokens. One of sessions_and_tokens, sessions_only, nothing.
send_email	boolean	no	Mail the password to the user. Default true.

users.password_reset.send

Mail a user a password-reset link at their own address.

REST	POST /api/v1/users/{id}/password-reset → 204
Scope	users:write — required of the key or token.
Danger	write
MCP tool	users_password_reset_send
CLI	cbox id users password_reset send <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.

users.reactivate

Reactivate a deactivated user so they can sign in again. Grants revoked on deactivation stay revoked.

REST	POST /api/v1/users/{id}/reactivate → 200
Scope	users:write — required of the key or token.
Danger	write
MCP tool	users_reactivate
CLI	cbox id users reactivate <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.

users.sessions.list

List a user's live sign-in sessions, most recently active first: device, IP and whether somebody else opened it as them.

REST	GET /api/v1/users/{id}/sessions → 200
Scope	users:read — required of the key or token.
Danger	read
MCP tool	users_sessions_list
CLI	cbox id users sessions list <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.

users.sessions.revoke

End one of a user's sign-in sessions.

REST	DELETE /api/v1/users/{id}/sessions/{session_id} → 204
Scope	users:write — required of the key or token.
Danger	destructive
MCP tool	users_sessions_revoke
CLI	cbox id users sessions revoke <id> <session_id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.
session_id	string (path)	yes	The session id, from GET /users/{id}/sessions. At most 64 characters.

users.sessions.revoke_all

Sign a user out everywhere: end every session and revoke every OAuth grant they hold.

REST	DELETE /api/v1/users/{id}/sessions → 204
Scope	users:write — required of the key or token.
Danger	destructive
MCP tool	users_sessions_revoke_all
CLI	cbox id users sessions revoke_all <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.

users.update

Change a user's name and/or email address. A changed address must be verified again.

REST	PATCH /api/v1/users/{id} → 200
Scope	users:write — required of the key or token.
Danger	critical
MCP tool	users_update
CLI	cbox id users update <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.
name	string, nullable	no	At most 190 characters.
email	string (email)	no	The new address. Its verification is cleared. At most 190 characters.

users.verification.send

Mail a user the link that verifies their email address. Does nothing for an address already verified.

REST	POST /api/v1/users/{id}/verification → 204
Scope	users:write — required of the key or token.
Danger	write
MCP tool	users_verification_send
CLI	cbox id users verification send <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.

users.verify

Mark a user's email address verified without the emailed link. It can then be used to recover the account.

REST	POST /api/v1/users/{id}/verify → 200
Scope	users:write — required of the key or token.
Danger	critical
MCP tool	users_verify
CLI	cbox id users verify <id>

Input	Type	Required	Description
id	string (path)	yes	The user id. At most 64 characters.

Webhooks

webhooks.create

Register a webhook endpoint for one organization or the whole environment. Returns its signing secret once.

REST	POST /api/v1/webhooks → 201
Scope	webhooks:write — required of the key or token.
Danger	critical
MCP tool	webhooks_create
CLI	cbox id webhooks create
Secret	data.secret — shown once, never kept for an idempotent replay

Input	Type	Required	Description
url	string (uri)	yes	A public HTTPS URL. Signed deliveries are POSTed here. At most 500 characters.
event_types	list of string	yes	The events it receives. At least 1 items.
signature_scheme	string	no	How deliveries are signed: cbox (X-Cbox-Signature, the default) or standard_webhooks (webhook-id / webhook-timestamp / webhook-signature, verifiable with any Standard Webhooks library; the secret is a whsec_ secret). One of cbox, standard_webhooks.
organization_id	string, nullable	no	The organization it belongs to; it carries that organization's traffic only. Send this or environment_wide. At most 64 characters.
environment_wide	boolean	no	True to make it the environment's own, carrying EVERY organization's traffic. Send this or organization_id.

webhooks.delete

Delete a webhook endpoint. It stops receiving events at once.

REST	DELETE /api/v1/webhooks/{id} → 204
Scope	webhooks:write — required of the key or token.
Danger	destructive
MCP tool	webhooks_delete
CLI	cbox id webhooks delete <id>

Input	Type	Required	Description
id	string (path)	yes	The webhook endpoint id.

webhooks.get

Get one webhook endpoint: URL, owner, subscribed events, health. Never its signing secret.

REST	GET /api/v1/webhooks/{id} → 200
Scope	webhooks:read — required of the key or token.
Danger	read
MCP tool	webhooks_get
CLI	cbox id webhooks get <id>

Input	Type	Required	Description
id	string (path)	yes	The webhook endpoint id.

webhooks.list

List the webhook endpoints registered in this environment: URL, owner, subscribed events and whether each is active.

REST	GET /api/v1/webhooks → 200
Scope	webhooks:read — required of the key or token.
Danger	read
MCP tool	webhooks_list
CLI	cbox id webhooks list

Input	Type	Required	Description
limit	integer	no	Items per page, 1–100. Default 50.
after	string	no	The next_cursor of the previous page.

webhooks.pause

Pause a webhook endpoint: it stops receiving events until resumed.

REST	POST /api/v1/webhooks/{id}/pause → 200
Scope	webhooks:write — required of the key or token.
Danger	write
MCP tool	webhooks_pause
CLI	cbox id webhooks pause <id>

Input	Type	Required	Description
id	string (path)	yes	The webhook endpoint id.

webhooks.resume

Resume a paused webhook endpoint: it receives events again.

REST	POST /api/v1/webhooks/{id}/resume → 200
Scope	webhooks:write — required of the key or token.
Danger	write
MCP tool	webhooks_resume
CLI	cbox id webhooks resume <id>

Input	Type	Required	Description
id	string (path)	yes	The webhook endpoint id.

webhooks.secret.rotate

Issue a new signing secret for a webhook endpoint, returned once. The old secret stops verifying immediately.

REST	POST /api/v1/webhooks/{id}/rotate → 200
Scope	webhooks:write — required of the key or token.
Danger	critical
MCP tool	webhooks_secret_rotate
CLI	cbox id webhooks secret rotate <id>
Secret	data.secret — shown once, never kept for an idempotent replay

Input	Type	Required	Description
id	string (path)	yes	The webhook endpoint id.

webhooks.signature_scheme.change

Change how a webhook endpoint's deliveries are signed (cbox or standard_webhooks). No new secret is issued: a hex secret is used as whsec_ + base64 of itself. Update the receiver first.

REST	POST /api/v1/webhooks/{id}/signature-scheme → 200
Scope	webhooks:write — required of the key or token.
Danger	destructive
MCP tool	webhooks_signature_scheme_change
CLI	cbox id webhooks signature_scheme change <id>

Input	Type	Required	Description
id	string (path)	yes	The webhook endpoint id.
signature_scheme	string	yes	The scheme deliveries are signed with from the next attempt. The secret is unchanged: under standard_webhooks a 64-hex secret is used as whsec_ + base64 of the hex string. Update the receiver before you switch. One of cbox, standard_webhooks.

webhooks.update

Change a webhook endpoint's URL and/or the events it subscribes to.

REST	PATCH /api/v1/webhooks/{id} → 200
Scope	webhooks:write — required of the key or token.
Danger	write
MCP tool	webhooks_update
CLI	cbox id webhooks update <id>

Input	Type	Required	Description
id	string (path)	yes	The webhook endpoint id.
url	string (uri)	no	A public HTTPS URL. Left out, unchanged. At most 500 characters.
event_types	list of string	no	The COMPLETE set of events afterwards. Left out, unchanged. At least 1 items.