> ## Documentation Index
> Fetch the complete documentation index at: https://cactal.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an API key

> Create a Cactal API key, choose its access scope, and store it safely. API keys authenticate every REST and MCP request.

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](https://app.cactal.ai), in your organization's API keys settings. Choose a name, an access scope, and an optional expiry.

<Warning>
  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.
</Warning>

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

```bash theme={null}
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:

```bash Create a website-scoped key theme={null}
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:

```json Response (abridged) theme={null}
{
  "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:

```bash theme={null}
curl https://api.cactal.ai/v1/websites \
  -H "Authorization: Bearer $CACTAL_API_KEY"
```

The same header authenticates the [MCP server](/docs/agents/mcp) 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](/docs/agents/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](/docs/guides/manage-api-keys). The wire-level details are in [Authentication](/docs/api-reference/authentication).

## Next steps

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Use your key to create and publish your first website.
  </Card>

  <Card title="Connect your agent" icon="bot" href="/docs/agents/mcp">
    Give an MCP client scoped access to Cactal.
  </Card>
</Columns>