Managing API keys

One key per integration

Spend, requests and errors are attributed per key. Give every service, environment and experiment its own key, named for what it does (checkout-summariser-prod, evals-nightly). You can then read a key's spend on its own line, cap it, and revoke it without touching anything else.

Creating a key

In the dashboard, API keys → Create key. Over the API, POST /api/keys. Either way you choose:

• Name and project. Projects are folders for keys; every organisation starts with a default project, and analytics can be filtered by project.
• Expiry (optional). Use one for anything short-lived: an experiment, a contractor, a demo. The dashboard offers the usual offsets and a Pick a date option for an exact day; the API takes an ISO timestamp on create and Unix epoch seconds on edit.
• Credit cap (optional). A lifetime rupee ceiling for this key. Size it to the worst case you are willing to pay for.
• Allowed models (optional). A list of route ids. Anything else answers 403.
• Environment (label). production, development or testing, for your own filtering.

The secret is shown once. Copy it into your environment before closing the panel.

Reading the roster

Each key on the roster shows its prefix (sk_i2_a1b2…), project, creation date, expiry, cap and scope, plus an enforcement status per limit. Open a key to see its own analytics: requests, latency, tokens and spend over the window you choose, and every allowed model listed in full.

last_used_at is real: it is derived at read time from the request telemetry rather than written on each use, so null means the key has genuinely never made a request. The dashboard's roster filters by status (active, expired, revoked) and by type, and defaults to active, which is the only view that answers "what can call the gateway right now".

A revoked key is soft-deleted upstream and stops being returned by the roster, so the dashboard's Revoked view lists only what was revoked since the page was opened. The permanent record is the activity log.

Changing a key's limits

A key's rate limit, credit cap and expiry can be changed after creation, with PATCH /api/keys/{key_id} or Edit limits in the dashboard. It is a full replace: every call restates all three, which is why the dashboard's expiry control carries a "leave as it is" option.

Two refusals are worth knowing before you wire a form to it, because both are 400 and both name the real figure:

• A cap cannot be set below what the key has already spent this cycle.
• Every key's cap added together cannot exceed the organisation's budget. The dashboard shows how much is left to allocate while you type.

A key's name, type and model scope are still fixed at creation. Changing those means minting a new key.

Rotating a key

Rotation is create, switch, revoke:

1. Create a new key with the same project, cap and scope.
2. Deploy the new secret.
3. Revoke the old key once the request log shows traffic has moved (filter by key).

There is no in-place rotation: the secret itself cannot be regenerated on an existing key.

Revoking

Revoke from the roster, or DELETE /api/keys/{key_id}. The gateway refuses the key on its very next request. Revocation is recorded in the activity log with the key's prefix as the target; the secret is never written anywhere.

Rate limits

Every key is issued at 60 requests per minute unless you set otherwise. The limit is per key and can be raised, at creation or later, up to a platform-wide ceiling; above the ceiling is a 400. Requests over the limit answer 429 and are never billed. How many a window actually lost to throttling is on Request logs.