Authentication

All CleverThis API requests must be authenticated with an API key. There are two key types serving different API surfaces.

Key types

Key type	Prefix	Used for	Scoped to
Inference key	ct_live_	/v1/chat/completions, /v1/models	A specific namespace
Management key	ct_mgmt_	/a2a control plane	A workspace

Inference keys (ct_live_) authorize inference requests. Each key is scoped to exactly one namespace, which determines which models are accessible. Generate inference keys from Settings → API Keys in the dashboard.

Management keys (ct_mgmt_) authorize management operations via the A2A control plane: creating namespaces, deploying models, managing billing, reading usage, etc. Generate management keys from Settings → API Keys and select "Management" as the key type.

Sending the key

Both key types are sent as Bearer tokens in the Authorization header:

# Inference request
curl https://api.cleverthis.com/v1/chat/completions \
  -H "Authorization: Bearer ct_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

# Management request
curl https://api.cleverthis.com/a2a \
  -H "Authorization: Bearer ct_mgmt_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "namespaces.list", "params": {}, "id": 1}'

Key security

• Never commit API keys to source control. Use environment variables.
• Rotate keys regularly from Settings → API Keys.
• Use separate keys per environment (dev, staging, production).
• Management keys are more sensitive than inference keys — store them with extra care.

Error responses

An invalid or missing key returns 401 Unauthorized. A valid key used against the wrong API surface (e.g. a ct_live_ key sent to /a2a) returns 403 Forbidden.

Coming soon

Key expiry, per-key rate limits, and IP allowlisting are being added to key management.