Authentication

ACP uses API key authentication for protected endpoints. Keys can be passed via a custom header or a standard Bearer token. Model-level API keys are forwarded separately.

API Key Header

The primary authentication method is the x-api-key request header. Include it on every request to a protected endpoint:

x-api-key header

GET /health HTTP/1.1
Host: your-worker.workers.dev
x-api-key: your_api_key

Bearer Token

Alternatively, you can use the standard Authorization header with a Bearer token. The value is the same API key:

Bearer token

GET /health HTTP/1.1
Host: your-worker.workers.dev
Authorization: Bearer your_api_key

Either method works

Both x-api-key and Authorization: Bearer are accepted. If both are present, x-api-key takes precedence. Choose whichever fits your HTTP client or framework.

Model API Key (OpenRouter)

When calling the consensus endpoint, ACP forwards LLM requests through OpenRouter. You can supply your own OpenRouter key to use your own account and rate limits:

OpenRouter key header

POST /consensus-iterative HTTP/1.1
Host: your-worker.workers.dev
Content-Type: application/json
x-api-key: your_api_key
x-openrouter-key: your_openrouter_key

{
  "query": "What is 2 + 2?",
  "models": ["openai/gpt-5.4-mini", "anthropic/claude-haiku-4-5"]
}

Header	Required	Description
`x-api-key`	Yes (if auth enabled)	Your ACP API key for accessing protected endpoints.
`Authorization`	Alternative to x-api-key	Standard Bearer token: `Bearer your_api_key`.
`x-openrouter-key`	Optional	Your own OpenRouter API key. If omitted, the server default key is used.
`Content-Type`	Yes (POST requests)	Must be `application/json` for all POST endpoints.

Rate-Limiting Headers

Every response includes headers that report your current rate-limit status. Use these to implement backoff logic in your client:

Response Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets.
`Retry-After`	Seconds to wait before retrying (only present on 429 responses).

Rate limits

The default limits are 100 requests per minute per IP and 1,000 requests per hour per API key. Burst traffic is capped at 10 requests per second. See Errors & Rate Limits for full details.

Full Authenticated Request

Putting it all together, here is a complete cURL request with authentication and an optional OpenRouter key:

cURL example

curl -X POST https://your-worker.workers.dev/consensus-iterative \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key" \
  -H "x-openrouter-key: your_openrouter_key" \
  -d '{
    "query": "What is the capital of France?",
    "models": ["openai/gpt-5.4-mini", "anthropic/claude-haiku-4-5"]
  }'

Keep keys secret

Never commit API keys to source control or expose them in client-side code. Use environment variables or a secrets manager. Rotate keys immediately if you suspect a leak.

Python API

Errors & Limits