API Authentication

All API requests to Tempered require authentication via an API key.

API Keys

API keys use the format prx_ followed by a unique token. They are created per-organisation and scoped to specific permissions.

Key Scopes

Scope	Permissions
eval	Submit evaluations, read results, manage knowledge documents
admin	Everything in eval plus organisation management, API key management, webhook configuration

Creating an API Key

Via the Dashboard

1. Go to Settings → API Keys
2. Click Create API Key
3. Enter a name (e.g., "CI/CD Pipeline", "Production Agent")
4. Select the scope (eval or admin)
5. Click Create
6. Copy the key immediately — it is shown once and cannot be recovered

Via the API

curl -X POST https://your-tempered-instance/api/v1/org/api-keys/ \
  -H "Authorization: Bearer prx_your_admin_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Pipeline", "scope": "eval"}'

Response:

{
  "id": "a1b2c3d4-...",
  "name": "CI Pipeline",
  "key_prefix": "prx_abc1",
  "scope": "eval",
  "raw_key": "prx_abc1...full_key_here..."
}

Using Your API Key

Include the key in the Authorization header as a Bearer token:

curl -H "Authorization: Bearer prx_your_api_key" \
  https://your-tempered-instance/api/v1/evaluations/

Python Example

import httpx

client = httpx.Client(
    base_url="https://your-tempered-instance",
    headers={"Authorization": "Bearer prx_your_api_key"},
)

# Submit an evaluation
response = client.post("/api/v1/evaluations/", json={
    "description": "Deploy new monitoring stack to production",
})
evaluation_id = response.json()["id"]

Revoking a Key

If a key is compromised, revoke it immediately:

curl -X POST https://your-tempered-instance/api/v1/org/api-keys/{key_id}/revoke/ \
  -H "Authorization: Bearer prx_your_admin_api_key"

Security Best Practices

• Never commit API keys to source control
• Use environment variables or a secrets manager to store keys
• Create separate keys for different environments and integrations
• Use the minimum scope — eval for most integrations, admin only for management tools
• Rotate keys periodically — revoke and recreate every 90 days
• Monitor usage — check the last_used_at timestamp in the API Keys dashboard

Rate Limits

API requests are rate-limited per organisation:

• Default: 100 evaluations per hour
• Enterprise: Configurable limits

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header indicating when you can retry.

Quota Enforcement

Your billing tier determines the number of evaluations per month. When you reach the limit:

• The API returns 429 Too Many Requests
• Upgrade your tier or wait for the next billing period
• Check current usage via GET /api/v1/billing/subscription/usage/