Skip to main content
REST requests to api.cactal.ai authenticate with an API key sent as a bearer token:
There is no cookie or session authentication on the public API host. A request that carries a browser session cookie is rejected with 401 so that keys and sessions can never be confused. The MCP endpoint also supports OAuth authorization code flow with PKCE. Standard MCP clients can connect to https://api.cactal.ai/v1/mcp without a manually configured secret, sign in to Cactal, and approve access. The resulting token is valid only for the MCP resource and uses the signed-in user’s grants. See Connect over MCP.

​
Keys

A key’s secret is a 43-character base64url string generated from 32 random bytes. Cactal stores only its SHA-256 hash:
  • The plaintext is returned once, when the key is created or rotated.
  • Nothing on Cactal’s side can reveal it again — treat loss as a rotation event.
  • Expired (expiresAt in the past) and revoked keys fail authentication with 401.
Create keys in the dashboard or with POST /v1/apiKeys — see Create an API key.

​
Access scopes

Each key carries an access object that fixes what it can reach:
Organization-scoped access
Website-scoped access
The owner role is not grantable to keys. Update a key’s scope at any time by sending access to PATCH /v1/apiKeys/{apiKeyId} — the change applies immediately.

​
Roles and capabilities

Roles expand to capabilities — the permission vocabulary that gates every endpoint. Each endpoint in this reference declares its requirement as x-cactal-required-capability in the OpenAPI spec (for example, websites.create or cms.items.setPublished). The MCP server uses the same model: tools/list only shows tools the presented user or key could actually call.

​
Authentication vs authorization errors

For website resources, no-access returns 404 rather than 403, so website existence never leaks. Organization-scoped endpoints instead return 403 when you lack a grant on an existing organization, and 404 only when the organization id is unknown.

​
Key lifecycle

Rotation and revocation take effect on the next request. In-flight abuse stops as soon as you rotate. Make rotate your first response to a suspected leak, then review the key’s recorded actions via GET /v1/organizations/{organizationId}/audit-log, list its pending content changes with GET /v1/websiteSourceCode/changes, and inspect selected files with GET /v1/websiteSourceCode/files/diff.

​
Storage rules

  • Keep keys in a secret manager or environment variables; never in code, logs, or client-side bundles.
  • Issue one key per integration or agent so you can rotate and audit them independently.
  • Prefer website-scoped content_editor keys for agents that only manage content — see Agent-safe publishing.