Create an API key

API keys authenticate every request to the Cactal API and MCP server. A key acts on behalf of your organization or specific websites, with a role that limits what it can do.

Create your first key

Create your first key in the dashboard, in your organization’s API keys settings. Choose a name, an access scope, and an optional expiry.

The plaintext key is shown once, at creation. Cactal stores only a SHA-256 hash and cannot show it again. Copy it immediately and store it in a secret manager. If you lose it, rotate the key to get a new secret.

Export the key in your shell so the examples across these docs work as written:

export CACTAL_API_KEY="<your-key>"

Choose an access scope

A key carries one of two access shapes. Pick the narrowest one that can do the job — especially for agents.

Scope	Shape	Use when
Organization	All websites in the organization, with role `admin`, `full_editor`, or `content_editor`	Trusted automation that manages the whole organization
Websites	Specific website ids, with role `full_editor` or `content_editor`	Agents or integrations that operate one site or one client’s sites

Roles map to capabilities:

content_editor — edit CMS content and assets; no source code edits, publishing, or settings.
full_editor — everything content editors can do, plus source code, publishing, and domains.
admin — organization-scoped keys only; adds member, website, and key management.

The owner role cannot be granted to an API key, and every billing operation requires it — so billing stays with human owners in the dashboard.

Create keys programmatically

Once you have one key (or a dashboard session), you can create more over the API — useful for issuing per-agent or per-client keys:

Create a website-scoped key

curl -X POST https://api.cactal.ai/v1/apiKeys \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "mUprfSyM4wgKY2AbQzXnE",
    "name": "Content agent — Acme Plumbing",
    "expiresAt": null,
    "access": {
      "kind": "websites",
      "websiteIds": ["V1StGXR8Z5jdHi6BmyTxQ"],
      "role": "content_editor"
    }
  }'

The response includes the key record and plaintextKey — the only time it is returned:

Response (abridged)

{
  "apiKey": {
    "id": "aK4nR7wY2sD9fH1jL6qXe",
    "organizationId": "mUprfSyM4wgKY2AbQzXnE",
    "name": "Content agent — Acme Plumbing",
    "expiresAt": null,
    "revokedAt": null
  },
  "plaintextKey": "exampleApiKeySecret000000000000000000000000"
}

Use the key

Send the key as a bearer token on every request:

curl https://api.cactal.ai/v1/websites \
  -H "Authorization: Bearer $CACTAL_API_KEY"

The same header authenticates the MCP server at POST https://api.cactal.ai/v1/mcp.

Key safety

Store keys in a secret manager or environment variable. Never commit them.
Scope agent keys to specific websites with the lowest workable role — see Agent-safe publishing.
Rotate on any suspicion of exposure: POST /v1/apiKeys/{apiKeyId}/rotate returns a new secret and invalidates the old one immediately.
Revoke keys you no longer need: POST /v1/apiKeys/{apiKeyId}/revoke. Revocation is permanent.
Set expiresAt for keys that should not outlive a project.

Full lifecycle workflows live in Manage API keys. The wire-level details are in Authentication.

Get started

Core concepts

Guides

Build with agents

Platform

Create an API key

Create your first key

Choose an access scope

Create keys programmatically

Use the key

Key safety

Next steps

Quickstart

Connect your agent

​Create your first key

​Choose an access scope

​Create keys programmatically

​Use the key

​Key safety

​Next steps

Quickstart

Connect your agent

Create your first key

Choose an access scope

Create keys programmatically

Use the key

Key safety

Next steps