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

# API Keys

> How to provision, rotate, and revoke API keys.

## Overview

Requests to the **REST API** authenticate with an API key in the `X-API-Key` header. The **MCP endpoint** accepts the same key as a bearer token — or an OAuth 2.0 sign-in, which needs no key at all.

```
# REST API
X-API-Key: alch_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# MCP endpoint — API key
Authorization: Bearer alch_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# MCP endpoint — OAuth 2.0 (client obtains this itself; nothing to copy)
Authorization: Bearer <oauth access token>
```

<Note>
  For MCP, prefer OAuth where the client supports it — there's no key to copy, leak, or rotate. Reach for an API key when the client can't run an OAuth flow, or for headless and CI runs where no browser is available. See [Add to Agents](/agents/overview#mcp-endpoint).
</Note>

Keys are prefixed with `alch_` followed by 32 random URL-safe characters. The full raw key is shown **once** at creation and is never stored — only a hash is kept.

## Provisioning a key

### Via the app (recommended)

1. Go to **[app.askalchemist.com/settings/api-keys](https://app.askalchemist.com/settings/api-keys)**
2. Click **Create key**
3. Enter a name (e.g. `cursor-dev`, `prod-agent`)
4. Copy the key immediately — it won't be shown again

### Via the API

If you're already authenticated via the app session (Clerk JWT), you can create keys programmatically:

```bash theme={null}
curl -X POST https://api.askalchemist.com/console/content/me/api-keys \
  -H "Authorization: Bearer <clerk_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'
```

Response:

```json theme={null}
{
  "key_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-agent",
  "prefix": "alch_abc123",
  "tier": "free",
  "is_active": true,
  "created_at": "2026-06-16T12:00:00Z",
  "last_used_at": null,
  "raw_key": "alch_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

## Listing your keys

```bash theme={null}
curl https://api.askalchemist.com/console/content/me/api-keys \
  -H "Authorization: Bearer <clerk_jwt>"
```

The list response omits `raw_key` — only the `prefix` (first 12 characters) is shown to help you identify keys.

## Revoking a key

```bash theme={null}
curl -X DELETE https://api.askalchemist.com/console/content/me/api-keys/<key_id> \
  -H "Authorization: Bearer <clerk_jwt>"
```

Returns `204 No Content` on success. Revoked keys are rejected immediately on the next request.

## Tiers

Keys carry a `tier` field that controls rate limits and access scope.

| Tier   | Rate limit          | Notes                    |
| ------ | ------------------- | ------------------------ |
| `free` | 100 requests/minute | Default for all new keys |

Higher tiers are available for production workloads — contact us at [hello@askalchemist.com](mailto:hello@askalchemist.com).

## Rate limit headers

Every API response includes rate limit state:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1718534460
```

A `429 Too Many Requests` response means you've hit the limit for the current window. Wait until `X-RateLimit-Reset` (Unix timestamp) before retrying.

## Security practices

* **One key per integration** — name keys after where they're used (`cursor-dev`, `prod-pipeline`). This makes it easy to rotate a compromised key without disrupting other integrations.
* **Never commit keys to version control.** Use environment variables or a secrets manager.
* **Rotate regularly.** Revoke and reissue keys quarterly or after any suspected exposure.