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>

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.

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)

Go to app.askalchemist.com/settings/api-keys
Click Create key
Enter a name (e.g. cursor-dev, prod-agent)
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:

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:

{
  "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

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

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.

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.

Get Started

Add to Agents

MCP Reference

API Reference

Overview

Provisioning a key

Via the app (recommended)

Via the API

Listing your keys

Revoking a key

Tiers

Rate limit headers

Security practices

​Overview

​Provisioning a key

​Via the app (recommended)

​Via the API

​Listing your keys

​Revoking a key

​Tiers

​Rate limit headers

​Security practices

Overview

Provisioning a key

Via the app (recommended)

Via the API

Listing your keys

Revoking a key

Tiers

Rate limit headers

Security practices