API Key Management
How to manage NemoRouter API keys — scopes, rotation, environment separation, expiration, IP allowlist.
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:
- Create a new key with the same scopes (or use the Duplicate action on the existing key).
- Roll the new key out to your application (env var, secret manager, etc.).
- Wait until you confirm the new key is in use (the dashboard shows last-used timestamp per key).
- 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:
| Environment | Key prefix | Example name |
|---|---|---|
| Local dev | dev- | dev-checkout-service |
| Staging | stage- | stage-checkout-service |
| Production | prod- | prod-checkout-service |
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.
The dashboard sends an email reminder 7 days, 1 day, and at the moment 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.