Mint a key
Mint an API key. plaintextKey is returned once; store it now. Pass scopes: a key with none works only on GET /v1/me. A key-authed caller cannot grant a scope it doesn’t hold (insufficient_scope), and a publishable key may hold only objects:read and usage:write (scope_not_grantable). A secret key needs a plan with API access (api_access_not_on_plan). Requires scope: applications:manage. Also accepts a signed-in session instead of a key (the bootstrap path the CLI and dashboard use before a key exists). A session caller must be a workspace admin.
Authorizations
A Custral API key, created in Settings → Developers → Applications, sent as Authorization: Bearer sk_…. The X-Api-Key header is also accepted and takes precedence. Use a secret key (sk_…) from your server; a publishable key (pk_…) may hold only objects:read and usage:write. Never expose a secret key in a browser.
Body
What the key may do. A key with no scopes authenticates but is refused everywhere except GET /v1/me, so always pass them.
A permission a key can hold. A publishable (pk_…) key may hold only objects:read and usage:write.
records:read, records:write, objects:read, documents:read, documents:write, conversations:read, conversations:write, property_agents:read, property_agents:write, tasks:read, usage:read, usage:write, quotes:write, billing:read, billing:admin, billing:portal, applications:manage, webhooks:manage, connectors:read, connectors:manage, mcp:read, mcp:write, widget:identify, widget:manage