API Key Management

Once you have a working API key, the next questions are operational: how do you rotate it, how do you separate environments, how do you scope what it can do? This page is the answer.

If you have not created a key yet, start with Authentication.

Key scopes

Every API key is scoped to exactly one team within your organization, and inherits that team's permissions. You cannot accidentally call a model that your team is not allowed to use — the gateway rejects the request before it reaches the provider.

The dashboard surfaces three knobs per key when you create or edit it:

• Allowed models — a per-key allowlist of model names (gemini-2.5-pro, gpt-4o-mini, etc.). Empty list means "everything your team can use".
• Allowed endpoints — restrict the key to /chat/completions, /embeddings, /images/generations, etc. Useful when you want a key that can only embed, not chat.
• IP allowlist — comma-separated CIDR blocks. Requests from any other source IP return 401 before reaching the provider.

Rotation flow

Keys can be rotated without service interruption:

1. Create a new key with the same scopes (or use the Duplicate action on the existing key).
2. Roll the new key out to your application (env var, secret manager, etc.).
3. Wait until you confirm the new key is in use (the dashboard shows last-used timestamp per key).
4. Revoke the old key from the dashboard.

We do not support in-place rotation that swaps the secret behind a single id, on purpose — it would let a forgotten consumer keep working after you thought you had revoked access. Two keys, two ids, explicit hand-off.

The audit log records every key create / rotate / revoke event with actor, IP, and timestamp.

Environment separation

The recommended pattern is one key per (environment, service) pair:

The dashboard sorts keys alphabetically by name — the prefix groups environments together visually. We do not enforce this naming, but every team that has been burned by a leaked dev key recommends it.

If you use the same key across environments, you also share rate limits, budget caps, and audit trails. Bad day if a runaway staging job exhausts the budget your prod service depends on.

Expiration

When you create a key, you can pin an expiration:

• Never — the default; the key is valid until you revoke it.
• 30 days — rotates monthly. Recommended for human-held keys (a developer's dev key).
• 90 days — quarterly rotation. Default for service-to-service integrations.
• Custom datetime — pick any future timestamp.

Where enabled, the dashboard can send email reminders ahead of expiry. After expiry, the key returns 401 until you create a replacement.

IP allowlist

Per-key CIDR blocks gate the source IP of inbound requests. Common patterns:

• Service in one VPC — allow that VPC's NAT-gateway IP range only.
• CI/CD only — allow your CI provider's outbound IP range (GitHub Actions / CircleCI / Buildkite publish their ranges).
• Developer keys — leave blank; developers move IPs all day.

The allowlist is evaluated before the key is consumed against your budget — denied requests cost zero credits.

Cross-link

The full dashboard Keys page lists every key on your team, its scopes, last-used time, and lifetime usage. From there you can create, duplicate, edit, or revoke any key in two clicks.

FAQ

Who on my team can create, edit, or revoke API keys?

Owners, admins, and members can create keys; only owners and admins can edit or revoke a key or run a rotation. Viewers can see keys and usage but cannot create, change, or revoke them.

Can I restrict a key to only certain models?

Yes. Each key has an Allowed models allowlist — leave it empty to permit everything your team can use, or list specific models like gemini-2.5-pro or gpt-4o-mini. A call to a model outside the allowlist is rejected before it reaches the provider, so it costs you nothing.

Is a key tied to my whole organization or just one team?

Every key is scoped to exactly one team within your organization and inherits that team's permissions. That means a key can never call a model or exceed a limit that its team isn't allowed to.

How do I rotate a key without downtime?

Create a new key with the same scopes (the Duplicate action clones them), roll it out to your app, confirm it's live via the per-key last-used timestamp, then revoke the old key. There is intentionally no in-place secret swap behind a single id — two keys with two ids force an explicit hand-off so a forgotten consumer can't keep working after you thought you'd cut it off.

Can I set spending or rate limits on an individual key?

Yes — you can attach a per-key budget cap and per-key RPM/TPM rate limits when you create or edit it. Because these live on the key, giving each service its own key keeps one workload from spending or throttling another's headroom.

What happens when a key expires?

After its expiration timestamp the key returns 401 until you create a replacement. The default is Never; you can also pick 30 days, 90 days, or a custom datetime, and where enabled the dashboard emails a reminder ahead of expiry.

How do I tell whether a key is still in use before I revoke it?

The Keys page shows a last-used timestamp and recent request count for every key. Check that a replacement key is actually being called before you revoke the one it's replacing.

Is there an audit trail of key changes?

Yes. Every create, rotate, and revoke event is recorded with the actor, source IP, and timestamp, and each key row links to its activity in the audit log.

Why can't I just replace the secret behind one key id?

This is deliberate. Swapping the secret in place would let any consumer you forgot about keep working after you believed you had revoked access — the two-key, explicit-handoff model closes that gap.

Should I reuse one key across dev, staging, and production?

No — use one key per environment-and-service pair (for example prod-checkout-service). Sharing a single key across environments also shares its rate limits, budget caps, and audit trail, so a runaway staging job could exhaust the budget your production service depends on.