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

# Authentication

> API keys and the X-API-KEY header.

The Cognizo API authenticates with **API keys**. There is no OAuth flow — you
create a key in the dashboard and send it as a header on every request.

## The header

```bash theme={null}
curl https://core.cognizo.ai/api/v2/brands \
  -H "X-API-KEY: YOUR_API_KEY"
```

Requests without a valid key get `401 UNAUTHORIZED`; a valid key that tries to
reach an endpoint outside the public API surface gets `403 FORBIDDEN`.

## Creating a key

1. Dashboard → **Settings → API Keys**.
2. **Create key**, give it a name (e.g. `production`, `zapier`, `local`), and
   optionally an expiry date.
3. Copy the secret — it starts with `cog_sk_` and is shown **only once**.

A key belongs to the user who created it but is scoped to your
**organization**: it can read and write every brand your org owns, exactly
like signing in to the app.

## Key anatomy

```
cog_sk_2f9K1xQe…                 43 random characters after the prefix
└──┬──┘
   └─ prefix, always cog_sk_
```

Only a SHA-256 digest of the key is stored, so nobody — including us — can
recover the plaintext after creation. The dashboard shows the first few
characters and the last four so you can tell keys apart.

## Expiry, rotation, revocation

* A key can carry an **expiry date**. After it passes, the key stops
  authenticating and requests fail with `401` — no grace period.
* **Rotating:** create the new key, switch your integration to it, then
  revoke the old one. Both work in parallel until you do.
* **Revoking is immediate.** The next request with that key gets `401`,
  including requests already queued in your own retry loop.
* Hold one key per integration. It keeps rotation cheap and shrinks the blast
  radius when something leaks.

<Warning>
  Treat an API key like a password. Anyone holding it can act as your entire
  organization. Never commit keys to source control or paste them into a
  browser console; keep them in a secret manager or a server-side env var.
</Warning>

## Scope

An API key has full read + write access **to the public API surface** — the
endpoints listed in the [API Reference](/api-reference/introduction) — and
nothing else. Every other endpoint the platform runs (internal tooling,
billing, content generation, admin) rejects API keys outright with `403`,
even for the org that owns the key.

Within that surface the key sees exactly what a signed-in member of your org
sees: your brands and the data attached to them, never another org's.

## Using a key with the MCP server

The [MCP server](/mcp/overview) takes the same key in the same header and
forwards it upstream per request — it stores nothing. See
[Security & troubleshooting](/mcp/troubleshooting) for what that means in
practice.