Get your API key

API keys are issued from the dashboard and authenticate every call to https://api.cleverouter.eu/v1/*. Keys are personal: each one belongs to a single user account.

Create a key

Click Create key. Give it a description that explains where it runs (production / vercel, staging / fly.io, local dev).

Copy the key. It's shown exactly once — we only store its SHA-256 hash, so there's no way to recover it later.

Paste the key into your secret manager and reference it from your environment:

export CLEVERROUTER_API_KEY=cr_live_XXXXXXXXXXXX

Key format

cr_live_<32 base62>

Part	Meaning
`cr_`	Brand prefix — easy to grep in logs to spot a leak.
`live_`	Environment tag (we may add `test_` keys in the future).
32 chars	Cryptographically random `[A-Za-z0-9]` (192 bits entropy).

The full string is hashed with SHA-256 on the gateway side. Only the hash lives in the database; you cannot decrypt a key from the dashboard.

Rotate a key

Rotation is just create new + revoke old:

Create a new key in the dashboard.

Update your secret store and redeploy with the new key.

Revoke the old key in the dashboard. Revocation takes effect within 60 seconds (the gateway's Redis cache TTL).

Revocation latency

The gateway caches authorised keys in Redis with a 60-second TTL. After revoking a key, expect up to one minute of leftover usage on any handler that already cached the lookup. The revoke event also goes into the Redis cache so the next request fails fast.

Per-key budgets

Each key can carry a budget in cents-per-day or cents-per-month. When the budget is exhausted, the gateway returns 402 budget_exceeded and the SDK throws CRBudgetExceededError.

Setting	Use case
Daily budget	Cap a long-running batch job that could spiral
Monthly budget	Cost-control per tenant or per environment
No budget	Default — the org's plan limit still applies

Budgets are checked at request time against the current day/month spend in usage_daily. Spend is aggregated every 5 minutes from requests by the gateway's rollup job.

Multiple keys per user

A user can hold many keys. Recommended split:

One key per environment (prod, staging, local).
One key per long-running batch job that you want to be able to revoke independently.
One key per third-party integration (zapier, n8n, mastra-agent-x).

Org-scoped keys

Keys are user-scoped today

Today, an API key belongs to the user who created it — not the org. If a person leaves the org, their personal keys keep working until you revoke them. Org-scoped "team keys" are on the roadmap; until then, treat keys as personal credentials and rotate them on offboarding.

Authentication — the Bearer header, rate-limit headers, key-leak hardening.
Rate limits — how 60 RPM is enforced.
Errors — every 4xx and 5xx the gateway returns.