Gateway: Virtual keys cookbook
Practical recipes for virtual keys — one per environment, budgets that cap themselves, allowlists that stop model drift, and revocation that takes a click. For the raw API surface, see Authentication & virtual keys.
One key per environment
Issue a separate virtual key for each place your code runs, all backed by the same provider keys:
| Key | Scope |
|---|---|
tvk_…dev | Local development — generous models, tiny budget. |
tvk_…staging | CI and staging — the models you actually ship against, capped RPM. |
tvk_…prod | Production — locked allowlist, budget you trust, monitored in logs. |
The payoff shows up in the logs: request volume, spend, latency, and error rate are all filterable by key, so "what did staging cost last week" is a filter, not an investigation.
Budgets that cap themselves
Every virtual key carries a budget. When a runaway loop or a chatty test suite hits it, the key stops serving — your real provider key is never exposed, and nothing else on the account is affected. Rotate the budget up when you mean it, not after the invoice arrives.
Model allowlists stop model drift
A virtual key can pin the exact models it will serve. Two places this earns its keep:
- Production — the key only serves the model you deployed and tested against; a stray model name in a commit changes nothing.
- Shared environments — teammates can experiment on their own keys while the shared key stays pinned.
Rate limits per key
RPM and TPM limits are per virtual key. Set staging below production so a parallel test suite cannot starve real traffic, and keep dev low enough that a fork-bombed script tops out quietly.
Revocation is instant
A leaked or stale key is revoked from the Portal — immediately, without rotating the underlying provider key and updating every consumer. This is the main operational reason to never ship a raw provider key.
Recipe: allowlist + fallback chain
Combine a pinned allowlist with a fallback chain: the primary model serves, the chain catches outages and rate limits, and the allowlist guarantees nothing outside the approved set ever runs. Add a budget and the worst case is a paused key, not a paused app or a surprise bill.