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

# Authentication

> Create an API key and authenticate every request with a bearer token.

Every Kettio API request needs a bearer token:

```http theme={null}
Authorization: Bearer agk_live_YOUR_KEY
```

The base URL is `https://kettio.com` for all endpoints.

## Create a key

<Steps>
  <Step title="Open API Keys">
    Go to [Dashboard → API Keys](https://kettio.com/dashboard?section=api-keys).
  </Step>

  <Step title="Generate a key">
    Keys are prefixed `agk_live_`.
  </Step>

  <Step title="Store it immediately">
    Kettio displays the raw key **once**. Put it straight into your secret manager.
  </Step>
</Steps>

<Warning>
  This is a server-to-server API. Never embed a key in browser or mobile code, commit it to a
  repository, or paste it into a public issue thread. If you lose a key, create a replacement
  from the dashboard.
</Warning>

## Verify it works

```bash theme={null}
curl -X POST https://kettio.com/api/v1/rank \
  -H "Authorization: Bearer agk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [{ "url": "https://cdn.example.com/ad-a.png", "id": "ad-a" }],
    "audience": { "name": "Millennial pet owners" }
  }'
```

A `401` means the key is missing or invalid. Anything else means authentication succeeded — see
[error codes](#error-codes) below for what the other statuses mean.

## Error codes

| Status | Meaning                                               |
| ------ | ----------------------------------------------------- |
| `401`  | Missing or invalid API key                            |
| `402`  | Insufficient credits for this batch                   |
| `404`  | `audience_id` not found, or not owned by your account |
| `422`  | Validation error in the request body                  |
| `429`  | Rate limited — check the `Retry-After` header         |

Rate limiting and credits are counted in **scoring evaluations**, not assets. See
[Limits and billing](/concepts/limits-and-billing).

## Using a key with MCP

The MCP server reads the same key from an environment variable:

```bash theme={null}
KETTIO_API_URL=https://kettio.com
KETTIO_API_KEY=agk_live_YOUR_KEY
```

Full setup for each client is in [MCP installation](/mcp/installation).