Virtual Keys: One scoped key per workload.
Give each app its own key. Choose its models, endpoints, and allowed IPs. Set rate and spend limits within your team’s controls.
Watch a key keep to its lane.
How virtual keys work. Scoped access, limits, and rotation.
Model, endpoint, and IP boundaries.
Restrict each key by allowed models, HTTP routes, and IP or CIDR ranges. Deny lists always override allows.
- Apps use sk-nrouter-* keys while nRouter manages provider credentials
- Requests outside a key allowlist return HTTP 403 and spend $0.00
- Disallowed models report x-nr-auth-reason: key_model_not_allowed
Per-key rate and spend limits.
Set request, token, and spend caps per key within your team and organization limits.
- Effective RPM and TPM limits take the lowest key, team, or org limit
- Keys with a spend limit check live spend on every request
- Over-budget calls return HTTP 402 before any model request runs
Rotate with an overlap window.
Create a replacement key and choose a 1 to 168 hour overlap window (24 hours by default) while you roll out.
- Full secret is shown once at creation; only a fingerprint is stored
- Owners and Organization Admins control rotation, denylists, and revocation
- An earlier expiry on the old key stays in force during the overlap
FAQs
How do virtual keys keep provider credentials out of application code?
Your apps use nRouter keys (sk-nrouter-*), and we manage the upstream provider credentials. Each virtual key is bound to your organization and team on the server, so if an application key is exposed, you can revoke or rotate that single key without changing credentials across your other services.
How do model, endpoint, and IP restrictions inherit across organization, team, and key?
A virtual key inherits its team and organization model access by default, or you can restrict it to a subset of permitted models, exact HTTP routes, and IPv4, IPv6, or CIDR ranges. Deny lists always override allowlists across organization, team, and key scopes, and disallowed model requests return HTTP 403 with x-nr-auth-reason: key_model_not_allowed. Members can adjust models and request or token limits on their own keys (and verified Team Admins on their team’s keys) within team and organization limits, including restoring inherited access. Setting key denylists, rotating keys, and revoking keys require an Owner or Organization Admin.
What happens when a virtual key reaches its spend limit or rate limit?
Effective RPM and TPM limits are bounded by the lowest of the key limit, team limit, and organization plan limit; exceeding a rate limit returns HTTP 429 Too Many Requests with Retry-After and x-nr-limit-source: key. Keys with a spend ceiling check live spend on every request, and when the ceiling is reached, the gateway refuses the call before any model request runs with HTTP 402 Payment Required and x-nr-limit-source: budget, holding and spending $0.00.
How quickly does key revocation or deletion take effect?
When an Owner or Organization Admin revokes, blocks, deletes, or rotates a key, the control plane sends a best-effort invalidation request so the gateway evicts that key from its local cache. Because keys without a spend limit are cached in gateway memory with a 5-second TTL (and keys with a spend limit check the database on every call), revocation propagates as soon as cache eviction completes or within the 5-second cache window. Subsequent calls with a blocked or expired key return HTTP 401 with x-nr-auth-reason: key_blocked or key_expired.
How are virtual keys stored, and what happens if I lose a key?
When you create a virtual key, the full 43-character secret (sk-nrouter-* followed by 32 base64url characters) is shown once and cannot be retrieved again; managed Playground keys are derived on the server and never revealed. nRouter stores only a SHA-256 fingerprint of the secret alongside the masked identifier (sk-nrouter-...last4) and key configuration. If you lose a key you created, rotate it or create a replacement key, update your application, and revoke the old key.
How does key rotation with an overlap window work?
Owners and Organization Admins can rotate a key to issue a new secret while keeping the previous key valid for a selectable 1 to 168 hour overlap window (24 hours by default). If the old key already had an earlier expiration timestamp, that earlier expiry remains in force. The rotation response also reports old_key_expiry_status so that if applying the expiration window to the old key fails, you can revoke the old key manually after updating your services.
How is usage attributed across keys and teams?
Every virtual key is bound on the server to an organization and team, and every request records the authenticated key identifier, team_id, and organization_id on its spend record for usage and cost attribution. Custom metadata and tags configured on a key are stored on the key record itself for organizing and auditing keys in the dashboard.
- Members can adjust models and request or token limits on their own keys (and verified Team Admins on their team’s keys) within team and organization limits, including restoring inherited access. Key denylists, rotation, and revocation require an Owner or Organization Admin.
- Rotation lets you select a 1 to 168 hour overlap window (24 hours by default), shortened if the old key already had an earlier expiry. If applying the old key’s expiry fails, the API reports that status so you can revoke the old key manually.
- When a key is revoked, deleted, or rotated, the control plane sends a best-effort cache eviction to the gateway. Uncapped key lookups cache in gateway memory for up to 5 seconds, while keys with a spend limit check live spend on every request.