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 |
| App catalog |
app_catalog.delete, app_catalog.list, app_catalog.save, app_catalog.show |
| 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.client_credentials, 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.credentials.replace, directories.delete, directories.get, directories.groups.list, directories.groups.map, directories.hris.connect, directories.list, directories.status.set, directories.sync, directories.sync_settings.update, 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 |
| Feature flags |
feature_flags.create, feature_flags.delete, feature_flags.evaluate, feature_flags.get, feature_flags.list, feature_flags.update |
| Fine-grained authorization |
fga.check, fga.check_batch, fga.resources.list, fga.schema.get, fga.schema.update, fga.schema.validate, fga.subjects.list, fga.tuples.delete, fga.tuples.list, fga.tuples.write |
| 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.get, 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 |
| Onboarding |
onboarding.get |
| 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 |
| Pipes |
pipes.connections.delete, pipes.connections.list, pipes.create, pipes.delete, pipes.get, pipes.grants.create, pipes.grants.delete, pipes.list, pipes.update |
| Publishable keys |
frontend_keys.create, frontend_keys.list, frontend_keys.revoke, frontend_keys.set_origins |
| Radar |
radar.decisions.get, radar.decisions.list, radar.lists.add, radar.lists.list, radar.lists.remove, radar.mode.set, radar.rules.create, radar.rules.delete, radar.rules.get, radar.rules.list, radar.rules.reorder, radar.rules.update, radar.settings.get, radar.settings.update |
| Roles |
members.apps.roles.replace, members.roles.grant, members.roles.list, members.roles.revoke, permissions.create, permissions.delete, permissions.list, permissions.update, roles.create, roles.definition.activate, 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.sms.get, signin.sms.update, signin.social.delete, signin.social.disable, signin.social.enable, signin.social.inherit, signin.social.list, signin.social.offered, signin.social.set, signin.social.update |
| 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 |
| User properties |
user_property_namespaces.configure, user_property_namespaces.show |
| Users |
users.create, users.deactivate, users.erase, users.get, users.list, users.mfa.reset, users.mfa.sms.remove, 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, fi, es, it, nl, pt, pl, ro, cs, hu, el, bg, hr, sk, tr, uk. |
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. |
App catalog
app_catalog.delete
Remove a catalog app without deleting its OAuth clients or user data.
|
|
| REST |
DELETE /api/v1/app-catalog/{key} → 204 |
| Scope |
app_catalog:write — required of the key or token. |
| Danger |
destructive |
| MCP tool |
app_catalog_delete |
| CLI |
cbox id app_catalog delete <key> |
| Input |
Type |
Required |
Description |
key |
string (path) |
yes |
At most 64 characters. |
version |
integer |
yes |
At least 1. |
app_catalog.list
List catalog apps, including drafts and visibility settings.
|
|
| REST |
GET /api/v1/app-catalog → 200 |
| Scope |
app_catalog:read — required of the key or token. |
| Danger |
read |
| MCP tool |
app_catalog_list |
| CLI |
cbox id app_catalog list |
Takes no input.
app_catalog.save
Create or replace a catalog app, its icon and visibility. Version zero creates; a stale version conflicts.
|
|
| REST |
PUT /api/v1/app-catalog/{key} → 200 |
| Scope |
app_catalog:write — required of the key or token. |
| Danger |
write |
| MCP tool |
app_catalog_save |
| CLI |
cbox id app_catalog save <key> |
| Input |
Type |
Required |
Description |
key |
string (path) |
yes |
At most 64 characters. |
version |
integer |
yes |
At least 0. |
name |
string |
yes |
At most 120 characters. |
description |
string, nullable |
no |
At most 300 characters. |
launch_url |
string |
yes |
Explicit HTTPS entry point. Never inferred from OAuth redirects. At most 2048 characters. |
enabled |
boolean |
yes |
|
position |
integer |
yes |
At least 0. At most 10000. |
audience |
string |
yes |
One of everyone, organizations, users. |
organization_ids |
list of string |
no |
At most 100 items. |
user_ids |
list of string |
no |
At most 100 items. |
client_ids |
list of string |
no |
Environment-wide OAuth client ids associated with this app. Does not grant access. At most 100 items. |
required_feature |
string, nullable |
no |
Optional feature-flag key. Hidden when off for this person and organization. At most 64 characters. |
icon |
string, nullable |
no |
PNG, JPEG or WebP data URI, up to 128 KiB and 512 pixels. Omit to retain; null clears. SVG and remote URLs are refused. At most 180000 characters. |
app_catalog.show
Read a catalog app and its publication settings.
|
|
| REST |
GET /api/v1/app-catalog/{key} → 200 |
| Scope |
app_catalog:read — required of the key or token. |
| Danger |
read |
| MCP tool |
app_catalog_show |
| CLI |
cbox id app_catalog show <key> |
| Input |
Type |
Required |
Description |
key |
string (path) |
yes |
At most 64 characters. |
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.client_credentials
Turn client-credentials authentication on or off for a confidential app; other grants and scopes stay unchanged.
|
|
| REST |
PUT /api/v1/apps/{id}/settings/client-credentials → 200 |
| Scope |
apps:write — required of the key or token. |
| Danger |
write |
| MCP tool |
apps_settings_client_credentials |
| CLI |
cbox id apps settings client_credentials <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The app's id, or its client_id. |
enabled |
boolean |
yes |
|
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, uploaded logo and favicon) 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, inter, geometric, rounded, 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, nullable |
no |
The logo as a base64 data: URI (data:image/png;base64,…): PNG, JPEG or WebP, at most 1024 KB and 4096px on the longest side. SVG and remote URLs are refused. Null removes it; left out keeps it. At most 1398204 characters. |
favicon |
string, nullable |
no |
The favicon as a base64 data: URI (data:image/png;base64,…): PNG, ICO or WebP, at most 256 KB and 1024px on the longest side. SVG and remote URLs are refused. Null removes it; left out keeps it. At most 349628 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.credentials.replace
Replace a pull directory's provider credentials, verifying the new ones first. Write-only; never returned.
|
|
| REST |
PUT /api/v1/directories/{id}/credentials → 200 |
| Scope |
directory_sync:write — required of the key or token. |
| Danger |
critical |
| MCP tool |
directories_credentials_replace |
| CLI |
cbox id directories credentials replace <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. |
credentials |
object |
yes |
The new credentials, in the keys the provider's setup names (Google: service_account_json, admin_email; Entra: tenant_id, client_id, client_secret). Write-only. |
credentials.report_url |
string |
no |
At most 20000 characters. |
credentials.username |
string |
no |
At most 20000 characters. |
credentials.password |
string |
no |
At most 20000 characters. |
credentials.client_id |
string |
no |
At most 20000 characters. |
credentials.client_secret |
string |
no |
At most 20000 characters. |
credentials.refresh_token |
string |
no |
At most 20000 characters. |
credentials.subdomain |
string |
no |
At most 20000 characters. |
credentials.api_key |
string |
no |
At most 20000 characters. |
credentials.api_token |
string |
no |
At most 20000 characters. |
credentials.service_user_id |
string |
no |
At most 20000 characters. |
credentials.service_user_token |
string |
no |
At most 20000 characters. |
credentials.service_account_json |
string |
no |
At most 20000 characters. |
credentials.admin_email |
string |
no |
At most 20000 characters. |
credentials.tenant_id |
string |
no |
At most 20000 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.hris.connect
Connect an HR system (Workday, BambooHR, Rippling, HiBob or Personio) to sync an organization's people from, verifying the credentials first. The first sync is queued.
|
|
| REST |
POST /api/v1/directories/hris → 201 |
| Scope |
directory_sync:write — required of the key or token. |
| Danger |
critical |
| MCP tool |
directories_hris_connect |
| CLI |
cbox id directories hris connect |
| Input |
Type |
Required |
Description |
organization_id |
string |
yes |
The organization whose people it provisions. At most 64 characters. |
provider |
string |
yes |
workday, bamboohr, rippling, hibob or personio. One of workday, bamboohr, rippling, hibob, personio. |
name |
string |
no |
What administrators call it. Defaults to the HR system's name. At most 120 characters. |
credentials |
object |
yes |
The HR system's credentials, in the keys its setup guide names. Write-only: sealed, never returned. |
credentials.report_url |
string |
no |
Workday: Report web-service URL. At most 20000 characters. |
credentials.username |
string |
no |
Workday: Integration system user. At most 20000 characters. |
credentials.password |
string |
no |
Workday: Integration system user password (secret). At most 20000 characters. |
credentials.client_id |
string |
no |
Workday: API client ID; Personio: Client ID. At most 20000 characters. |
credentials.client_secret |
string |
no |
Workday: API client secret (secret); Personio: Client secret (secret). At most 20000 characters. |
credentials.refresh_token |
string |
no |
Workday: Refresh token (secret). At most 20000 characters. |
credentials.subdomain |
string |
no |
BambooHR: Company subdomain. At most 20000 characters. |
credentials.api_key |
string |
no |
BambooHR: API key (secret). At most 20000 characters. |
credentials.api_token |
string |
no |
Rippling: API token (secret). At most 20000 characters. |
credentials.service_user_id |
string |
no |
HiBob: Service user ID. At most 20000 characters. |
credentials.service_user_token |
string |
no |
HiBob: Service user token (secret). At most 20000 characters. |
custom_attributes |
list of string |
no |
The HR system's own field names to copy onto each person, verbatim. At most 50 items. |
sync_interval_minutes |
integer, nullable |
no |
Minutes between scheduled pulls, 15 to 1440. Omitted or null: the platform default (hourly). At least 15. At most 1440. |
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.sync
Pull a Google Workspace, Microsoft Entra or HR-system directory now, on a worker. full asks an HR system for everybody rather than what changed.
|
|
| REST |
POST /api/v1/directories/{id}/sync → 202 |
| Scope |
directory_sync:write — required of the key or token. |
| Danger |
write |
| MCP tool |
directories_sync |
| CLI |
cbox id directories sync <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. |
full |
boolean |
no |
Ask an HR system that syncs incrementally for everybody, not only what changed. Ignored by other providers. |
directories.sync_settings.update
Set how often a pull directory syncs, and for an HR system which of its fields pass through onto people.
|
|
| REST |
PATCH /api/v1/directories/{id}/sync-settings → 200 |
| Scope |
directory_sync:write — required of the key or token. |
| Danger |
write |
| MCP tool |
directories_sync_settings_update |
| CLI |
cbox id directories sync_settings 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. |
sync_interval_minutes |
integer, nullable |
no |
Minutes between scheduled pulls, 15 to 1440. null returns to the platform default (hourly). At least 15. At most 1440. |
custom_attributes |
list of string |
no |
HR systems only: the HR system's own field names to copy onto each person, verbatim. At most 50 items. |
field_map |
object |
no |
Workday only: the report column holding each field, where it is not the default name. |
field_map.id |
string |
no |
The report column holding id. Default: Employee_ID. At most 190 characters. |
field_map.email |
string |
no |
The report column holding email. Default: Work_Email. At most 190 characters. |
field_map.first_name |
string |
no |
The report column holding first_name. Default: Legal_First_Name. At most 190 characters. |
field_map.last_name |
string |
no |
The report column holding last_name. Default: Legal_Last_Name. At most 190 characters. |
field_map.display_name |
string |
no |
The report column holding display_name. Default: Preferred_Name. At most 190 characters. |
field_map.active |
string |
no |
The report column holding active. Default: Active_Status. At most 190 characters. |
field_map.on_leave |
string |
no |
The report column holding on_leave. Default: On_Leave. At most 190 characters. |
field_map.hire_date |
string |
no |
The report column holding hire_date. Default: Hire_Date. At most 190 characters. |
field_map.termination_date |
string |
no |
The report column holding termination_date. Default: Termination_Date. At most 190 characters. |
field_map.department_id |
string |
no |
The report column holding department_id. Default: Supervisory_Organization_ID. At most 190 characters. |
field_map.department |
string |
no |
The report column holding department. Default: Supervisory_Organization. At most 190 characters. |
field_map.manager_id |
string |
no |
The report column holding manager_id. Default: Manager_Employee_ID. At most 190 characters. |
field_map.title |
string |
no |
The report column holding title. Default: Business_Title. At most 190 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. |
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. |
Feature flags
feature_flags.create
Define a feature flag: a key apps ask about, its default, and who it is on for — named users, named organizations, a rollout percentage.
|
|
| REST |
POST /api/v1/feature-flags → 201 |
| Scope |
feature_flags:write — required of the key or token. |
| Danger |
write |
| MCP tool |
feature_flags_create |
| CLI |
cbox id feature_flags create |
| Input |
Type |
Required |
Description |
key |
string |
yes |
What code asks for and the feature_flags claim carries: lowercase letters and digits, with -, _ or . between them. Fixed once created. At most 64 characters. |
description |
string, nullable |
no |
At most 500 characters. |
enabled |
boolean |
no |
The kill switch: off means off for everyone, whatever the rules say. Defaults to true. |
default_value |
boolean |
no |
The answer when no rule matches. Defaults to false. |
users |
list of object |
no |
Rules for named users — they outrank every other rule. The COMPLETE list when sent. At most 1000 items. |
users[].id |
string |
yes |
The user's id. At most 128 characters. |
users[].enabled |
boolean |
no |
On (true, the default) or off for them, whatever the organization, rollout or default say. |
organizations |
list of object |
no |
Rules for named organizations — they outrank the rollout and the default. The COMPLETE list when sent. At most 1000 items. |
organizations[].id |
string |
yes |
The organization's id. At most 128 characters. |
organizations[].enabled |
boolean |
no |
On (true, the default) or off for them, whatever the organization, rollout or default say. |
rollout_percentage |
integer, nullable |
no |
On for this percentage of everyone else, by a stable hash of the user id (or the organization id without one). null for no rollout. At least 0. At most 100. |
feature_flags.delete
Delete a feature flag and its rules. Its key evaluates to off from now on; tokens already minted keep it until they expire.
|
|
| REST |
DELETE /api/v1/feature-flags/{id} → 204 |
| Scope |
feature_flags:write — required of the key or token. |
| Danger |
destructive |
| MCP tool |
feature_flags_delete |
| CLI |
cbox id feature_flags delete <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The flag's id. |
feature_flags.evaluate
Evaluate every feature flag for a user in an organization: whether each is on, and the rule that decided. For app backends without a token in hand.
|
|
| REST |
GET /api/v1/feature-flags/evaluate → 200 |
| Scope |
feature_flags:read — required of the key or token. |
| Danger |
read |
| MCP tool |
feature_flags_evaluate |
| CLI |
cbox id feature_flags evaluate |
| Input |
Type |
Required |
Description |
user_id |
string |
no |
The user to evaluate for. Left out, only organization rules, an organization-bucketed rollout and defaults apply. At most 128 characters. |
organization_id |
string |
no |
The organization the question is asked in. At most 64 characters. |
feature_flags.get
Read one feature flag: its default, whether it is switched on, and every user, organization and rollout rule.
|
|
| REST |
GET /api/v1/feature-flags/{id} → 200 |
| Scope |
feature_flags:read — required of the key or token. |
| Danger |
read |
| MCP tool |
feature_flags_get |
| CLI |
cbox id feature_flags get <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The flag's id. |
feature_flags.list
List this environment's feature flags with their default, kill switch and targeting rules.
|
|
| REST |
GET /api/v1/feature-flags → 200 |
| Scope |
feature_flags:read — required of the key or token. |
| Danger |
read |
| MCP tool |
feature_flags_list |
| CLI |
cbox id feature_flags 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. |
feature_flags.update
Change a feature flag: switch it on or off for everyone, change its default, or replace its user rules, organization rules or rollout percentage.
|
|
| REST |
PATCH /api/v1/feature-flags/{id} → 200 |
| Scope |
feature_flags:write — required of the key or token. |
| Danger |
write |
| MCP tool |
feature_flags_update |
| CLI |
cbox id feature_flags update <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The flag's id. |
description |
string, nullable |
no |
Null or empty clears it. At most 500 characters. |
enabled |
boolean |
no |
The kill switch: off means off for everyone. |
default_value |
boolean |
no |
The answer when no rule matches. |
users |
list of object |
no |
Rules for named users — they outrank every other rule. The COMPLETE list when sent. At most 1000 items. |
users[].id |
string |
yes |
The user's id. At most 128 characters. |
users[].enabled |
boolean |
no |
On (true, the default) or off for them, whatever the organization, rollout or default say. |
organizations |
list of object |
no |
Rules for named organizations — they outrank the rollout and the default. The COMPLETE list when sent. At most 1000 items. |
organizations[].id |
string |
yes |
The organization's id. At most 128 characters. |
organizations[].enabled |
boolean |
no |
On (true, the default) or off for them, whatever the organization, rollout or default say. |
rollout_percentage |
integer, nullable |
no |
On for this percentage of everyone else, by a stable hash of the user id (or the organization id without one). null for no rollout. At least 0. At most 100. |
Fine-grained authorization
fga.check
Check whether a subject has a relation on a resource — directly, through computed relations, parents or nested groups. Optionally at least as fresh as a consistency_token.
|
|
| REST |
GET /api/v1/fga/check → 200 |
| Scope |
fga:read — required of the key or token. |
| Danger |
read |
| MCP tool |
fga_check |
| CLI |
cbox id fga check |
| Input |
Type |
Required |
Description |
resource_type |
string |
yes |
The resource's type: document. At most 64 characters. |
resource_id |
string |
yes |
The resource's id: readme. At most 128 characters. |
relation |
string |
yes |
The relation to check: viewer. At most 64 characters. |
subject_type |
string |
yes |
The subject's type: user, or group for a userset. At most 64 characters. |
subject_id |
string |
yes |
The subject's id: alice. At most 128 characters. |
subject_relation |
string |
no |
For a userset subject — member with group/eng asks about every member of eng. At most 64 characters. |
consistency_token |
string, nullable |
no |
A consistency_token a write returned: the answer is then at least as fresh as that write. At most 64 characters. |
fga.check_batch
Run 1–100 checks in one round trip, each written resource#relation@subject (document:readme#viewer@user:alice), all at the same revision, answered in order.
|
|
| REST |
GET /api/v1/fga/check/batch → 200 |
| Scope |
fga:read — required of the key or token. |
| Danger |
read |
| MCP tool |
fga_check_batch |
| CLI |
cbox id fga check_batch |
| Input |
Type |
Required |
Description |
checks |
list of string |
yes |
1–100 checks, each resource_type:resource_id#relation@subject_type:subject_id[#subject_relation]. At least 1 items. At most 100 items. |
consistency_token |
string, nullable |
no |
A consistency_token a write returned: the answer is then at least as fresh as that write. At most 64 characters. |
fga.resources.list
List the resources of one type a subject has a relation on (e.g. every document alice can view), through all inheritance; sorted ids, paged with after.
|
|
| REST |
GET /api/v1/fga/resources → 200 |
| Scope |
fga:read — required of the key or token. |
| Danger |
read |
| MCP tool |
fga_resources_list |
| CLI |
cbox id fga resources list |
| Input |
Type |
Required |
Description |
resource_type |
string |
yes |
Which type of resource to list: document. At most 64 characters. |
relation |
string |
yes |
The relation the subject must have: viewer. At most 64 characters. |
subject_type |
string |
yes |
The subject's type: user. At most 64 characters. |
subject_id |
string |
yes |
The subject's id: alice. At most 128 characters. |
subject_relation |
string |
no |
For a userset subject: member with group/eng. At most 64 characters. |
consistency_token |
string, nullable |
no |
A consistency_token a write returned: the answer is then at least as fresh as that write. At most 64 characters. |
limit |
integer |
no |
Ids per page, 1–1000. Default 100. |
after |
string |
no |
The next_cursor of the previous page. At most 128 characters. |
fga.schema.get
Read this environment's fine-grained authorization schema: the source text, its parsed types and relations, its version, and the current consistency token.
|
|
| REST |
GET /api/v1/fga/schema → 200 |
| Scope |
fga:read — required of the key or token. |
| Danger |
read |
| MCP tool |
fga_schema_get |
| CLI |
cbox id fga schema get |
Takes no input.
fga.schema.update
Replace this environment's fine-grained authorization schema (types, relations and how each is decided). Changes the answer to every check at once; refused if invalid or if existing tuples would no longer fit.
|
|
| REST |
PUT /api/v1/fga/schema → 200 |
| Scope |
fga:schema — required of the key or token. |
| Danger |
critical |
| MCP tool |
fga_schema_update |
| CLI |
cbox id fga schema update |
| Input |
Type |
Required |
Description |
schema |
string |
yes |
The schema, in the schema language: type document then relation viewer: [user, group#member] or editor or viewer from parent. At most 65536 characters. |
fga.schema.validate
Check a fine-grained authorization schema without saving it: every error by line, or the parsed types and canonical text.
|
|
| REST |
GET /api/v1/fga/schema/validate → 200 |
| Scope |
fga:read — required of the key or token. |
| Danger |
read |
| MCP tool |
fga_schema_validate |
| CLI |
cbox id fga schema validate |
| Input |
Type |
Required |
Description |
schema |
string |
yes |
The schema to check, in the schema language. At most 65536 characters. |
fga.subjects.list
List the subjects of one type that have a relation on a resource (e.g. every user who can view the readme), groups and inheritance expanded; sorted ids, paged with after.
|
|
| REST |
GET /api/v1/fga/subjects → 200 |
| Scope |
fga:read — required of the key or token. |
| Danger |
read |
| MCP tool |
fga_subjects_list |
| CLI |
cbox id fga subjects list |
| Input |
Type |
Required |
Description |
resource_type |
string |
yes |
The resource's type: document. At most 64 characters. |
resource_id |
string |
yes |
The resource's id: readme. At most 128 characters. |
relation |
string |
yes |
The relation: viewer. At most 64 characters. |
subject_type |
string |
yes |
Which type of subject to list: user. At most 64 characters. |
consistency_token |
string, nullable |
no |
A consistency_token a write returned: the answer is then at least as fresh as that write. At most 64 characters. |
limit |
integer |
no |
Ids per page, 1–1000. Default 100. |
after |
string |
no |
The next_cursor of the previous page. At most 128 characters. |
fga.tuples.delete
Delete 1–100 relationship tuples in one atomic batch. Revokes the access they granted, and everything inherited through them, at once.
|
|
| REST |
POST /api/v1/fga/tuples/delete → 200 |
| Scope |
fga:write — required of the key or token. |
| Danger |
destructive |
| MCP tool |
fga_tuples_delete |
| CLI |
cbox id fga tuples delete |
| Input |
Type |
Required |
Description |
tuples |
list of object |
yes |
1–100 tuples to delete, all together or none. At least 1 items. At most 100 items. |
tuples[].resource_type |
string |
yes |
The resource's type, as the schema names it: document. At most 64 characters. |
tuples[].resource_id |
string |
yes |
Your id for the resource: readme. At most 128 characters. |
tuples[].relation |
string |
yes |
The relation: viewer. At most 64 characters. |
tuples[].subject |
object |
yes |
Who: one subject (user:alice), or a userset (group:eng#member). |
tuples[].subject.type |
string |
yes |
The subject's type: user, or group for a userset. At most 64 characters. |
tuples[].subject.id |
string |
yes |
Your id for the subject: alice, eng. At most 128 characters. |
tuples[].subject.relation |
string, nullable |
no |
For a userset — everybody with this relation on the subject: member of group:eng. Omit for one subject. At most 64 characters. |
fga.tuples.list
List stored relationship tuples oldest first, filtered by resource type and id, relation and subject; pass next_cursor as after to page.
|
|
| REST |
GET /api/v1/fga/tuples → 200 |
| Scope |
fga:read — required of the key or token. |
| Danger |
read |
| MCP tool |
fga_tuples_list |
| CLI |
cbox id fga tuples list |
| Input |
Type |
Required |
Description |
resource_type |
string |
no |
Only tuples on this resource type. At most 64 characters. |
resource_id |
string |
no |
Only tuples on this resource. At most 128 characters. |
relation |
string |
no |
Only tuples of this relation. At most 64 characters. |
subject_type |
string |
no |
Only tuples naming this subject type. At most 64 characters. |
subject_id |
string |
no |
Only tuples naming this subject. At most 128 characters. |
subject_relation |
string |
no |
Only tuples naming a userset with this relation. At most 64 characters. |
limit |
integer |
no |
Tuples per page, 1–100. Default 50. |
after |
string |
no |
The next_cursor of the previous page. At most 64 characters. |
fga.tuples.write
Write 1–100 relationship tuples (resource#relation@subject) in one atomic batch, each checked against the schema. Grants access at once; returns a consistency_token for checks that must see it.
|
|
| REST |
POST /api/v1/fga/tuples → 200 |
| Scope |
fga:write — required of the key or token. |
| Danger |
write |
| MCP tool |
fga_tuples_write |
| CLI |
cbox id fga tuples write |
| Input |
Type |
Required |
Description |
tuples |
list of object |
yes |
1–100 tuples to write, all together or none. At least 1 items. At most 100 items. |
tuples[].resource_type |
string |
yes |
The resource's type, as the schema names it: document. At most 64 characters. |
tuples[].resource_id |
string |
yes |
Your id for the resource: readme. At most 128 characters. |
tuples[].relation |
string |
yes |
The relation: viewer. At most 64 characters. |
tuples[].subject |
object |
yes |
Who: one subject (user:alice), or a userset (group:eng#member). |
tuples[].subject.type |
string |
yes |
The subject's type: user, or group for a userset. At most 64 characters. |
tuples[].subject.id |
string |
yes |
Your id for the subject: alice, eng. At most 128 characters. |
tuples[].subject.relation |
string, nullable |
no |
For a userset — everybody with this relation on the subject: member of group:eng. Omit for one subject. 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.get
Get an invitation and its acceptance receipt, confined to its organization.
|
|
| REST |
GET /api/v1/organizations/{organization_id}/invitations/{invitation_id} → 200 |
| Scope |
invitations:read — required of the key or token. |
| Danger |
read |
| MCP tool |
invitations_get |
| CLI |
cbox id invitations get <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.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. |
Onboarding
onboarding.get
Read current environment onboarding evidence. Does not certify application security or production readiness.
|
|
| REST |
GET /api/v1/onboarding → 200 |
| Scope |
signin:read — required of the key or token. |
| Danger |
read |
| MCP tool |
onboarding_get |
| CLI |
cbox id onboarding get |
Takes no input.
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. |
Pipes
pipes.connections.delete
Disconnect a person's connected account: revoke it at the provider where supported, revoke its tokens here, and forget it.
|
|
| REST |
DELETE /api/v1/pipes/{id}/connections/{connection_id} → 204 |
| Scope |
pipes:write — required of the key or token. |
| Danger |
destructive |
| MCP tool |
pipes_connections_delete |
| CLI |
cbox id pipes connections delete <id> <connection_id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The pipe's id. |
connection_id |
string (path) |
yes |
The connection's id. |
pipes.connections.list
List the accounts people connected through a pipe: who, which account, granted scopes, status (active / needs_reauth) and when the token expires. Never a token.
|
|
| REST |
GET /api/v1/pipes/{id}/connections → 200 |
| Scope |
pipes:read — required of the key or token. |
| Danger |
read |
| MCP tool |
pipes_connections_list |
| CLI |
cbox id pipes connections list <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The pipe's id. |
user_id |
string |
no |
Only this person's connection. At most 128 characters. |
limit |
integer |
no |
Items per page, 1–100. Default 50. |
after |
string |
no |
The next_cursor of the previous page. |
pipes.create
Configure a pipe: the environment's OAuth app at a third-party provider (GitHub, Google, Microsoft 365, Slack, Salesforce, HubSpot, Linear, Notion), so people can connect their accounts. The client secret is sealed and never returned.
|
|
| REST |
POST /api/v1/pipes → 201 |
| Scope |
pipes:write — required of the key or token. |
| Danger |
write |
| MCP tool |
pipes_create |
| CLI |
cbox id pipes create |
| Input |
Type |
Required |
Description |
provider |
string |
yes |
The provider's key. One of github, google, microsoft, slack, salesforce, hubspot, linear, notion. |
client_id |
string |
yes |
The OAuth client id of your app at the provider. At most 500 characters. |
client_secret |
string |
yes |
Its client secret. Write-only: sealed, never returned. At most 4000 characters. |
scopes |
list of string |
no |
The OAuth scopes to ask people for. Left out: the provider's defaults. |
parameters |
object |
no |
Per-installation values some providers need. Left out: the provider's defaults. |
parameters.tenant |
string |
no |
Microsoft 365 only: common (default), organizations, or one directory's tenant id or domain. At most 253 characters. |
parameters.domain |
string |
no |
Salesforce only: login.salesforce.com (default), test.salesforce.com, or your My Domain host. At most 253 characters. |
pipes.delete
Remove a pipe and every connection through it. Their tokens are revoked here, not at the provider — disconnect people first if that matters.
|
|
| REST |
DELETE /api/v1/pipes/{id} → 204 |
| Scope |
pipes:write — required of the key or token. |
| Danger |
destructive |
| MCP tool |
pipes_delete |
| CLI |
cbox id pipes delete <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The pipe's id. |
pipes.get
Show one pipe: its provider, OAuth client id, scopes, the redirect URI to register at the provider, and the apps granted its tokens.
|
|
| REST |
GET /api/v1/pipes/{id} → 200 |
| Scope |
pipes:read — required of the key or token. |
| Danger |
read |
| MCP tool |
pipes_get |
| CLI |
cbox id pipes get <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The pipe's id. |
pipes.grants.create
Grant an app (by OAuth client id) the right to lease fresh access tokens for the accounts people connected through this pipe.
|
|
| REST |
POST /api/v1/pipes/{id}/grants → 200 |
| Scope |
pipes:write — required of the key or token. |
| Danger |
critical |
| MCP tool |
pipes_grants_create |
| CLI |
cbox id pipes grants create <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The pipe's id. |
client_id |
string |
yes |
The OAuth client id of an app in this environment. At most 190 characters. |
pipes.grants.delete
Withdraw an app's right to lease the tokens people connected through this pipe.
|
|
| REST |
DELETE /api/v1/pipes/{id}/grants/{client_id} → 204 |
| Scope |
pipes:write — required of the key or token. |
| Danger |
destructive |
| MCP tool |
pipes_grants_delete |
| CLI |
cbox id pipes grants delete <id> <client_id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The pipe's id. |
client_id |
string (path) |
yes |
The OAuth client id whose grant is withdrawn. At most 190 characters. |
pipes.list
List the pipes — the third-party providers people can connect their accounts to — with their scopes and the apps granted their tokens. Never a client secret.
|
|
| REST |
GET /api/v1/pipes → 200 |
| Scope |
pipes:read — required of the key or token. |
| Danger |
read |
| MCP tool |
pipes_list |
| CLI |
cbox id pipes 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. |
pipes.update
Change a pipe — client id, client secret (sealed), scopes, parameters, or whether it is enabled. Only what is sent changes.
|
|
| REST |
PATCH /api/v1/pipes/{id} → 200 |
| Scope |
pipes:write — required of the key or token. |
| Danger |
write |
| MCP tool |
pipes_update |
| CLI |
cbox id pipes update <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The pipe's id. |
client_id |
string |
no |
A new OAuth client id. Left out, unchanged. At most 500 characters. |
client_secret |
string |
no |
A new client secret, sealed. Left out, unchanged. At most 4000 characters. |
scopes |
list of string |
no |
The OAuth scopes to ask people for. Left out: the provider's defaults. |
parameters |
object |
no |
Per-installation values some providers need. Left out: the provider's defaults. |
parameters.tenant |
string |
no |
Microsoft 365 only: common (default), organizations, or one directory's tenant id or domain. At most 253 characters. |
parameters.domain |
string |
no |
Salesforce only: login.salesforce.com (default), test.salesforce.com, or your My Domain host. At most 253 characters. |
enabled |
boolean |
no |
False refuses new connections and every lease. Left out, unchanged. |
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. |
Radar
radar.decisions.get
Read one Radar decision: the verdict, whether it was enforced, the deciding rule, every rule that fired, the reasons, the risk score and the facts it was decided on.
|
|
| REST |
GET /api/v1/radar/decisions/{id} → 200 |
| Scope |
radar:read — required of the key or token. |
| Danger |
read |
| MCP tool |
radar_decisions_get |
| CLI |
cbox id radar decisions get <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The decision's id. At most 26 characters. |
radar.decisions.list
List this environment's Radar decisions newest first — verdict, deciding rule, every rule that fired, reasons and facts — filtered by verdict, flow, rule, country, email, IP, device or time; pass next_cursor as after to page. Email and IP are matched by keyed pseudonym and never returned.
|
|
| REST |
GET /api/v1/radar/decisions → 200 |
| Scope |
radar:read — required of the key or token. |
| Danger |
read |
| MCP tool |
radar_decisions_list |
| CLI |
cbox id radar decisions list |
| Input |
Type |
Required |
Description |
verdict |
string |
no |
allow, challenge or block. One of allow, challenge, block. |
flow |
string |
no |
sign_in or sign_up. One of sign_in, sign_up. |
rule |
string |
no |
A rule key — builtin:credential_stuffing, rule:<id>, deny_list:ip — that decided or fired. At most 64 characters. |
country |
string |
no |
Two-letter country code. At most 2 characters. |
email |
string |
no |
Attempts with this address (matched by pseudonym). At most 255 characters. |
ip |
string |
no |
Attempts from this IP (matched by pseudonym). At most 64 characters. |
device |
string |
no |
Attempts from this device id. At most 64 characters. |
enforced |
boolean |
no |
Only decisions that were (true) or were not (false) acted on. |
from |
string (date-time) |
no |
On or after this time (ISO 8601). |
to |
string (date-time) |
no |
On or before this time (ISO 8601). |
limit |
integer |
no |
Decisions per page, 1–100. Default 50. At least 1. At most 100. |
after |
string |
no |
The next_cursor of the previous page: the decisions older than it. At most 26 characters. |
radar.lists.add
Add an entry to this environment's Radar allow or deny list: an IP or CIDR range, an email address, a mail domain (and its subdomains), or a device id from the decisions explorer. Deny blocks before every rule; allow skips every rule.
|
|
| REST |
POST /api/v1/radar/lists → 201 |
| Scope |
radar:write — required of the key or token. |
| Danger |
write |
| MCP tool |
radar_lists_add |
| CLI |
cbox id radar lists add |
| Input |
Type |
Required |
Description |
list |
string |
yes |
allow or deny. One of allow, deny. |
kind |
string |
yes |
ip (an address or CIDR range), email, email_domain or device. One of ip, email, email_domain, device. |
value |
string |
yes |
The IP, range, address, domain or device id. At most 255 characters. |
note |
string, nullable |
no |
Why it is listed. At most 255 characters. |
expires_at |
string (date-time), nullable |
no |
When the entry stops applying (ISO 8601). Never, when omitted. |
radar.lists.list
List this environment's Radar allow and deny entries — IPs and CIDR ranges, addresses, mail domains, devices — optionally one list or one kind.
|
|
| REST |
GET /api/v1/radar/lists → 200 |
| Scope |
radar:read — required of the key or token. |
| Danger |
read |
| MCP tool |
radar_lists_list |
| CLI |
cbox id radar lists list |
| Input |
Type |
Required |
Description |
list |
string |
no |
allow or deny; both when omitted. One of allow, deny. |
kind |
string |
no |
Only entries of this kind. One of ip, email, email_domain, device. |
limit |
integer |
no |
Items per page, 1–100. Default 50. |
after |
string |
no |
The next_cursor of the previous page. |
radar.lists.remove
Remove an entry from this environment's Radar allow or deny list.
|
|
| REST |
DELETE /api/v1/radar/lists/{id} → 204 |
| Scope |
radar:write — required of the key or token. |
| Danger |
destructive |
| MCP tool |
radar_lists_remove |
| CLI |
cbox id radar lists remove <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The entry's id. At most 26 characters. |
radar.mode.set
Switch this environment's Radar between monitor (verdicts recorded, never acted on) and enforce (blocks refuse sign-ins and sign-ups, challenges demand a second factor). Changes the environment's security posture.
|
|
| REST |
PUT /api/v1/radar/mode → 200 |
| Scope |
radar:manage — required of the key or token. |
| Danger |
critical |
| MCP tool |
radar_mode_set |
| CLI |
cbox id radar mode set |
| Input |
Type |
Required |
Description |
mode |
string |
yes |
monitor or enforce. One of monitor, enforce. |
radar.rules.create
Add a Radar rule: when EVERY condition (field, operator, value) holds, allow, challenge or block. Rules run in order after the allow/deny lists and before the built-in rules; the first match decides. Example: country not_in [DK, SE] → challenge.
|
|
| REST |
POST /api/v1/radar/rules → 201 |
| Scope |
radar:write — required of the key or token. |
| Danger |
write |
| MCP tool |
radar_rules_create |
| CLI |
cbox id radar rules create |
| Input |
Type |
Required |
Description |
name |
string |
yes |
What the rule is for, as the console lists it. At most 120 characters. |
description |
string, nullable |
no |
Why the rule exists, for whoever reads it next. At most 500 characters. |
action |
string |
yes |
What happens when every condition holds: allow (skip every rule after this one), challenge (a second factor on sign-in; a CAPTCHA or an emailed code on sign-up) or block. One of allow, challenge, block. |
applies_to |
string |
no |
all (the default), sign_in or sign_up. One of all, sign_in, sign_up. |
conditions |
list of object |
yes |
Up to 10 conditions; the rule matches when EVERY one holds. A fact that is unknown (no IP intelligence, no address on a passkey sign-in) matches no condition. At least 1 items. At most 10 items. |
conditions[].field |
string |
yes |
The fact to test. One of ip, country, asn, as_organization, is_hosting, is_vpn, is_proxy, is_tor, email, email_domain, disposable_email, user_agent, method, new_device, impossible_travel, travel_kmh, risk_score, ip_attempts_1m, ip_attempts_1h, ip_distinct_emails_10m, ip_failures_1h, email_attempts_1h, email_failures_1h, device_attempts_1h. |
conditions[].operator |
string |
yes |
How to compare it. Which operators a field takes depends on its type. One of eq, neq, in, not_in, gt, gte, lt, lte, contains, not_contains, starts_with, ends_with, in_cidr, not_in_cidr. |
conditions[].value |
string |
no |
The one value to compare with, as text — DK, 20, true. For every operator except the list ones. At most 255 characters. |
conditions[].values |
list of string |
no |
The values to compare with, for in, not_in, in_cidr and not_in_cidr. At most 100 items. |
enabled |
boolean |
no |
Whether the rule is evaluated. Default true. |
position |
integer |
no |
Where in the order to put it: 1 is evaluated first. Default: last. At least 1. |
radar.rules.delete
Delete a Radar rule. Attempts it decided are decided by the next matching rule, or the built-in rules, from then on.
|
|
| REST |
DELETE /api/v1/radar/rules/{id} → 204 |
| Scope |
radar:write — required of the key or token. |
| Danger |
destructive |
| MCP tool |
radar_rules_delete |
| CLI |
cbox id radar rules delete <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The rule's id. At most 26 characters. |
radar.rules.get
Read one Radar rule: its action, the flows it applies to, its position and its conditions.
|
|
| REST |
GET /api/v1/radar/rules/{id} → 200 |
| Scope |
radar:read — required of the key or token. |
| Danger |
read |
| MCP tool |
radar_rules_get |
| CLI |
cbox id radar rules get <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The rule's id. At most 26 characters. |
radar.rules.list
List this environment's own Radar rules in evaluation order (the first whose conditions all hold decides), with their conditions and a readable summary of each.
|
|
| REST |
GET /api/v1/radar/rules → 200 |
| Scope |
radar:read — required of the key or token. |
| Danger |
read |
| MCP tool |
radar_rules_list |
| CLI |
cbox id radar rules list |
| Input |
Type |
Required |
Description |
limit |
integer |
no |
Rules per page, 1–100. Default 100 — an environment holds at most 100, so one page is all of them. |
after |
string |
no |
The next_cursor of the previous page. At most 26 characters. |
radar.rules.reorder
Set the order Radar rules are evaluated in: rule_ids lists every rule of the environment exactly once, first evaluated first.
|
|
| REST |
PUT /api/v1/radar/rules/order → 204 |
| Scope |
radar:write — required of the key or token. |
| Danger |
write |
| MCP tool |
radar_rules_reorder |
| CLI |
cbox id radar rules reorder |
| Input |
Type |
Required |
Description |
rule_ids |
list of string |
yes |
Every rule id, in the new order. At most 100 items. |
radar.rules.update
Change a Radar rule: its name, description, action, flows, enabled state, position, or (replaced whole) its conditions.
|
|
| REST |
PATCH /api/v1/radar/rules/{id} → 200 |
| Scope |
radar:write — required of the key or token. |
| Danger |
write |
| MCP tool |
radar_rules_update |
| CLI |
cbox id radar rules update <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The rule's id. At most 26 characters. |
name |
string |
no |
What the rule is for, as the console lists it. At most 120 characters. |
description |
string, nullable |
no |
Why the rule exists, for whoever reads it next. At most 500 characters. |
action |
string |
no |
What happens when every condition holds: allow (skip every rule after this one), challenge (a second factor on sign-in; a CAPTCHA or an emailed code on sign-up) or block. One of allow, challenge, block. |
applies_to |
string |
no |
all (the default), sign_in or sign_up. One of all, sign_in, sign_up. |
conditions |
list of object |
no |
Up to 10 conditions; the rule matches when EVERY one holds. A fact that is unknown (no IP intelligence, no address on a passkey sign-in) matches no condition. At least 1 items. At most 10 items. |
conditions[].field |
string |
yes |
The fact to test. One of ip, country, asn, as_organization, is_hosting, is_vpn, is_proxy, is_tor, email, email_domain, disposable_email, user_agent, method, new_device, impossible_travel, travel_kmh, risk_score, ip_attempts_1m, ip_attempts_1h, ip_distinct_emails_10m, ip_failures_1h, email_attempts_1h, email_failures_1h, device_attempts_1h. |
conditions[].operator |
string |
yes |
How to compare it. Which operators a field takes depends on its type. One of eq, neq, in, not_in, gt, gte, lt, lte, contains, not_contains, starts_with, ends_with, in_cidr, not_in_cidr. |
conditions[].value |
string |
no |
The one value to compare with, as text — DK, 20, true. For every operator except the list ones. At most 255 characters. |
conditions[].values |
list of string |
no |
The values to compare with, for in, not_in, in_cidr and not_in_cidr. At most 100 items. |
enabled |
boolean |
no |
Whether the rule is evaluated. Default true. |
position |
integer |
no |
Where in the order to put it: 1 is evaluated first. Default: last. At least 1. |
radar.settings.get
Read this environment's Radar settings: the mode (monitor or enforce, and whether it is inherited from the deployment), the IP intelligence source, and every built-in rule with its action and threshold.
|
|
| REST |
GET /api/v1/radar/settings → 200 |
| Scope |
radar:read — required of the key or token. |
| Danger |
read |
| MCP tool |
radar_settings_get |
| CLI |
cbox id radar settings get |
Takes no input.
radar.settings.update
Tune this environment's built-in Radar rules: builtin_rules maps a rule key (credential_stuffing, bot_velocity, account_attack, impossible_travel, new_device, anonymous_network, hosting_network, disposable_email, risk_score_reject, risk_score_elevated) to any of enabled, action and threshold.
|
|
| REST |
PATCH /api/v1/radar/settings → 200 |
| Scope |
radar:write — required of the key or token. |
| Danger |
write |
| MCP tool |
radar_settings_update |
| CLI |
cbox id radar settings update |
| Input |
Type |
Required |
Description |
builtin_rules |
object |
yes |
Rule key => {"enabled": bool, "action": "allow"|"challenge"|"block", "threshold": int}, each part optional. Keys: credential_stuffing, bot_velocity, account_attack, impossible_travel, new_device, anonymous_network, hosting_network, disposable_email, risk_score_reject, risk_score_elevated. |
Roles
members.apps.roles.replace
Replace one app's member roles atomically. Other apps and the organization membership remain unchanged. An empty role list removes this app's access only.
|
|
| REST |
PUT /api/v1/organizations/{organization_id}/members/{user_id}/apps/{client_id}/roles → 200 |
| Scope |
roles:write — required of the key or token. |
| Danger |
write |
| MCP tool |
members_apps_roles_replace |
| CLI |
cbox id members apps roles replace <organization_id> <user_id> <client_id> |
| Input |
Type |
Required |
Description |
organization_id |
string (path) |
yes |
At most 64 characters. |
user_id |
string (path) |
yes |
At most 64 characters. |
client_id |
string (path) |
yes |
At most 255 characters. |
version |
string |
yes |
SHA-256 of the JSON array of current role ids for this app, sorted lexicographically. Read member roles first. At least 64 characters. At most 64 characters. |
roles |
list of string |
yes |
Manifest keys to assign. An empty list removes manual access to this app. At most 50 items. |
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.definition.activate
Activate a reviewed application role definition for its existing holders.
|
|
| REST |
POST /api/v1/roles/{id}/definition/activate → 200 |
| Scope |
role_definitions:write — required of the key or token. |
| Danger |
destructive |
| MCP tool |
roles_definition_activate |
| CLI |
cbox id roles definition activate <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
At most 64 characters. |
version |
string |
yes |
At least 64 characters. At most 64 characters. |
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 — including whether passkeys and magic links are offered and how long sessions last — 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. |
passkeys |
boolean |
no |
Environment only. Whether people may sign in with a passkey, and add one. Off at the deployment (CBOX_ID_PASSKEYS_ENABLED=false) stays off. |
magic_link |
boolean |
no |
Environment only. Whether a one-time sign-in link may be emailed. Off at the deployment (CBOX_ID_MAGIC_LINK_ENABLED=false) stays off. |
session_idle_minutes |
integer, nullable |
no |
Environment only. Minutes of inactivity before a session ends; null for the deployment's. No more than the deployment allows (CBOX_ID_SESSION_IDLE_MINUTES). At least 1. At most 525600. |
session_absolute_minutes |
integer, nullable |
no |
Environment only. Minutes a session lasts at most, however active; null for the deployment's. No more than the deployment allows (CBOX_ID_SESSION_TTL_MINUTES). At least 5. At most 525600. |
bot_challenge |
boolean |
no |
Environment only. Whether a sign-up Radar flags is asked to prove it is a person (Cloudflare Turnstile). Has no effect where the deployment has no Turnstile keys. |
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.sms.get
Read the SMS second-factor policy: whether text-message codes are accepted, for which countries, and the administrator rule.
|
|
| REST |
GET /api/v1/sign-in/sms → 200 |
| Scope |
signin:read — required of the key or token. |
| Danger |
read |
| MCP tool |
signin_sms_get |
| CLI |
cbox id signin sms get |
Takes no input.
signin.sms.update
Change the SMS second-factor policy: accept text-message codes or not, the countries they may go to, and whether SMS may be an administrator's only factor.
|
|
| REST |
PATCH /api/v1/sign-in/sms → 200 |
| Scope |
signin:write — required of the key or token. |
| Danger |
critical |
| MCP tool |
signin_sms_update |
| CLI |
cbox id signin sms update |
| Input |
Type |
Required |
Description |
enabled |
boolean |
no |
Accept text messages as a second factor in this environment. Off by default: SMS is the weakest factor offered. |
allowed_countries |
list of string |
no |
ISO 3166-1 alpha-2 countries whose numbers may enrol and be texted. Required to be non-empty while SMS is on: which countries you text is your toll-fraud exposure. At most 250 items. |
privileged_need_stronger_factor |
boolean |
no |
Administrators may add SMS only beside an authenticator app or a passkey, and are asked to enrol one if SMS is all they hold. On by default. |
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.disable
Turn a social login provider off without removing it. People who used it keep their accounts.
|
|
| REST |
POST /api/v1/sign-in/social-providers/{id}/disable → 200 |
| Scope |
signin:write — required of the key or token. |
| Danger |
critical |
| MCP tool |
signin_social_disable |
| CLI |
cbox id signin social disable <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The provider's id. |
organization_id |
string, nullable |
no |
Only if it is this organization's; anything else is a 404. At most 64 characters. |
signin.social.enable
Turn a social login provider that was turned off back on, with the credentials it already has.
|
|
| REST |
POST /api/v1/sign-in/social-providers/{id}/enable → 200 |
| Scope |
signin:write — required of the key or token. |
| Danger |
write |
| MCP tool |
signin_social_enable |
| CLI |
cbox id signin social enable <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The provider's id. |
organization_id |
string, nullable |
no |
Only if it is this organization's; anything else is a 404. At most 64 characters. |
signin.social.inherit
Turn one of the environment's social login providers off (or back on) for one organization's sign-in page.
|
|
| REST |
PUT /api/v1/sign-in/social-providers/inherited/{provider} → 200 |
| Scope |
signin:write — required of the key or token. |
| Danger |
write |
| MCP tool |
signin_social_inherit |
| CLI |
cbox id signin social inherit <provider> |
| Input |
Type |
Required |
Description |
provider |
string (path) |
yes |
The catalogue key: google, github… At most 100 characters. |
organization_id |
string |
yes |
The organization whose sign-in page this is about. At most 64 characters. |
offered |
boolean |
yes |
False to stop offering the environment's provider on this organization's page; true to offer it again. |
signin.social.list
List the social login providers (Google, GitHub, Apple…) set up in this environment — the environment's own and organizations' — 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 own providers (not the ones it inherits — see signin.social.offered). At most 64 characters. |
level |
string |
no |
Only the environment's providers, which every organization inherits, or only organizations' own. One of environment, organization. |
limit |
integer |
no |
Items per page, 1–100. Default 50. |
after |
string |
no |
The next_cursor of the previous page. |
signin.social.offered
The social login buttons one organization's sign-in page shows (or the plain sign-in page's), after inheritance from the environment, with where each comes from.
|
|
| REST |
GET /api/v1/sign-in/social-providers/offered → 200 |
| Scope |
signin:read — required of the key or token. |
| Danger |
read |
| MCP tool |
signin_social_offered |
| CLI |
cbox id signin social offered |
| Input |
Type |
Required |
Description |
organization_id |
string |
no |
The organization whose sign-in page to resolve. Left out, the plain sign-in page, before anybody has said who they are. At most 64 characters. |
signin.social.set
Enable a social login provider (Google, GitHub, Apple…) for the whole environment or 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, nullable |
no |
The organization the provider belongs to. Send this or environment_wide. At most 64 characters. |
environment_wide |
boolean |
no |
True to make the provider the environment's own rather than one organization's. Send this or organization_id. |
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. |
scopes |
list of string |
no |
Extra scopes to request beyond the ones sign-in needs (for example read:org on GitHub). Replaces any extra scopes already set; an empty list removes them. At most 20 items. |
reserved_id |
string, nullable |
no |
A ULID to create the provider under, so its redirect URI (which contains the id) can be registered with the provider first. Left out, one is minted. At most 26 characters. |
signin.social.update
Change a social login provider's client credentials, provider values or extra scopes. Secrets left out keep the ones on file.
|
|
| REST |
PATCH /api/v1/sign-in/social-providers/{id} → 200 |
| Scope |
signin:write — required of the key or token. |
| Danger |
critical |
| MCP tool |
signin_social_update |
| CLI |
cbox id signin social update <id> |
| Input |
Type |
Required |
Description |
id |
string (path) |
yes |
The provider's id. |
organization_id |
string, nullable |
no |
Only change it if it is this organization's; anything else is a 404. At most 64 characters. |
client_id |
string |
no |
A new client id. For Apple, the Services ID. At most 400 characters. |
client_secret |
string, nullable |
no |
A new client secret. Write-only; left out or blank keeps the one on file. 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. |
scopes |
list of string |
no |
Extra scopes to request beyond the ones sign-in needs (for example read:org on GitHub). Replaces any extra scopes already set; an empty list removes them. At most 20 items. |
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. |
User properties
Create or replace the app and webhook grants for a user-property namespace. Empty grants revoke access without deleting user data.
|
|
| REST |
PUT /api/v1/user-property-namespaces/{name} → 200 |
| Scope |
user_property_namespaces:write — required of the key or token. |
| Danger |
critical |
| MCP tool |
user_property_namespaces_configure |
| CLI |
cbox id user_property_namespaces configure <name> |
| Input |
Type |
Required |
Description |
name |
string (path) |
yes |
At most 64 characters. |
readers |
list of string |
no |
OAuth client ids allowed to read. Omit or use an empty list to revoke all access. At most 100 items. |
writers |
list of string |
no |
Reader client ids also allowed to write. At most 100 items. |
webhooks |
object |
no |
Map webhook endpoint ids to reader client ids. Omit to remove all webhook grants. |
user_property_namespaces.show
Read the app and webhook grants for a user-property namespace.
|
|
| REST |
GET /api/v1/user-property-namespaces/{name} → 200 |
| Scope |
user_property_namespaces:read — required of the key or token. |
| Danger |
read |
| MCP tool |
user_property_namespaces_show |
| CLI |
cbox id user_property_namespaces show <name> |
| Input |
Type |
Required |
Description |
name |
string (path) |
yes |
At most 64 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.mfa.sms.remove
Remove a user's phone number for text-message sign-in codes. Their other factors and recovery codes stay.
|
|
| REST |
DELETE /api/v1/users/{id}/mfa/sms → 204 |
| Scope |
users:write — required of the key or token. |
| Danger |
critical |
| MCP tool |
users_mfa_sms_remove |
| CLI |
cbox id users mfa sms remove <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. |
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. |
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. |
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. |