---
title: What are virtual keys in an LLM gateway?
url: https://opencontroller.lyzr.com/blog/what-are-llm-gateway-virtual-keys
published: 2026-11-17
updated: 2026-11-17
author: Lyzr
---

# What are virtual keys in an LLM gateway?

**A virtual key is a credential issued by an LLM gateway instead of by the model provider. Applications and agents call the gateway with the virtual key; the gateway checks the key's owner, budget and allowed models, then calls the provider with a real provider key that the application never sees. This lets you revoke, rotate, limit and attribute access per agent without touching provider keys.**

Most enterprises start with a handful of provider API keys pasted into many apps. Virtual keys fix that by putting one controlled layer between every caller and every provider.

## What does a virtual key map to?

A virtual key is a record in the gateway, not just a string. A useful one carries these fields:

| Field | Example | Why it matters |
|---|---|---|
| Key ID and hash | `vk_7f3…` (stored hashed) | The secret is shown once; only the hash is stored |
| Owner | A named person and a team | Someone is accountable when it misbehaves |
| Bound workload | Agent `claims-triage`, version 4 | Spend and incidents trace to one agent version |
| Upstream provider key(s) | Reference to a secret in a vault | Provider keys stay in one place |
| Model allow-list | Two approved models | Stops quiet upgrades to expensive models |
| Budget | Monthly cap and alert thresholds | Limits the blast radius of a loop |
| Rate limits | Requests and tokens per minute | Protects shared provider quota |
| Expiry | 90 days | Forces review instead of keys living forever |
| Environment | dev, test or prod | Prevents test traffic billed to production |

The gateway resolves the virtual key on every request, enforces the limits, and logs usage against the owner and workload.

## Why not just give each app its own provider key?

Provider keys are a weaker control point for four reasons:

1. **Rotation breaks things.** Rotating a provider key means updating every app that holds it, often at the same time.
2. **Attribution is coarse.** Providers group usage by key, project or workspace. They do not know which agent version made a call.
3. **Limits differ by provider.** Each provider has its own budget and rate-limit features. A team using three providers manages three sets of rules.
4. **Leaks are expensive.** A leaked provider key works directly against the provider until someone notices. OWASP lists this kind of unbounded resource use as [LLM10:2025 Unbounded Consumption](https://genai.owasp.org/llmrisk/llm102025-unbounded-consumption/).

With virtual keys, the provider key lives only in the gateway and your secret manager. A leaked virtual key is limited by its own budget, model list and expiry, and you can revoke it in one place.

## How should you issue and rotate virtual keys?

A simple policy that works for most estates:

1. **One key per workload, per environment.** Never share a key between two agents. Shared keys make cost attribution and incident response guesswork.
2. **Issue through a request flow.** The request names the owner, the agent, the cost centre and the models needed. Approval creates the key.
3. **Default-deny models.** Start each key with the cheapest model that passed evaluation; add others by request.
4. **Set the budget at issue time.** Pick a monthly cap and alerts at 50%, 80% and 100%. See [how to set budgets and alerts for AI agent spend](/blog/set-budgets-and-alerts-for-ai-agent-spend).
5. **Expire by default.** 90 days is common for production; 30 days or less for experiments.
6. **Rotate with overlap.** Issue the new key, let both work for a short window, then revoke the old one.
7. **Revoke on ownership change.** When the owner leaves or the agent is retired, revoke the key the same day.
8. **Scan for leaks.** Run secret scanning on repositories and agent configs for both provider keys and virtual keys.

## Are virtual keys enough on their own?

No. A virtual key is a shared secret. It proves that a caller holds the key, not who the caller is. For production agents, stronger options exist:

- **Workload identity** (for example a cloud workload identity or OIDC token) proves which service is calling, with short-lived credentials.
- **Delegated, on-behalf-of identity** proves which user an agent is acting for.

A sensible pattern is SSO for people using the gateway console, workload identity for production services, and virtual keys for scripts, prototypes and tools that cannot do anything better. The post on [how apps should authenticate to an LLM gateway](/blog/how-should-apps-authenticate-to-an-llm-gateway) compares these options.

## How do virtual keys help with cost attribution?

Because each key is bound to one agent and version, every request carries attribution without the app sending extra headers. Finance can see spend per team, per agent and per version, and engineers can compare cost per task between versions. For the full method, see [how to attribute LLM costs to AI agents](/blog/how-to-attribute-llm-costs-to-ai-agents) and the [gateway comparison pillar](/blog/llm-gateway-vs-agent-gateway-vs-control-plane).

## How Opencontroller does this

Opencontroller's LLM Gateway (Lyzr Gateway) provides routing, fallback and retry, caching, and cost attribution per agent and per version through OpenAI-compatible endpoints. It supports OIDC SSO, delegated on-behalf-of identity and agent workload identity federation, so production agents do not have to rely on shared secrets. Auto-discovery also finds API keys across AWS, Azure and Google Cloud, which helps you find provider keys that should move behind the gateway. See the [LLM gateway comparison](/compare/llmgateway) or [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**Is a virtual key the same as a provider project key?**
No. A provider project key is issued by the model provider and works only with that provider. A virtual key is issued by your gateway, can route to several providers, and carries your own owner, budget and model rules.

**What happens to traffic if a virtual key is revoked?**
Requests using it are rejected by the gateway immediately. Other keys that share the same upstream provider key keep working, which is the main advantage over rotating the provider key.

**Should AI agents in production use virtual keys?**
They can, but workload identity with short-lived tokens is stronger. Use virtual keys where a workload cannot present an identity token, and keep them scoped, budgeted and expiring.

## Key facts

A virtual key is a credential issued by an LLM gateway that maps to an owner, a bound workload, upstream provider keys, a model allow-list, a budget, rate limits and an expiry. The provider key stays in the gateway and secret manager. Recommended practice: one key per workload per environment, default-deny models, budgets at issue time, 90-day expiry, rotation with overlap. OWASP LLM10:2025 covers unbounded consumption. Opencontroller LLM Gateway provides routing, fallback/retry, caching and cost attribution per agent and per version; it supports OIDC SSO, on-behalf-of identity and workload identity federation. Licensing starts from $250K per deployment per year.

## Related

- [How should users and applications authenticate to an LLM gateway?](https://opencontroller.lyzr.com/blog/how-should-apps-authenticate-to-an-llm-gateway.md)
- [How do you set budgets and alerts for AI agent spend?](https://opencontroller.lyzr.com/blog/set-budgets-and-alerts-for-ai-agent-spend.md)
- [How do you attribute LLM costs to individual AI agents?](https://opencontroller.lyzr.com/blog/how-to-attribute-llm-costs-to-ai-agents.md)
- [More on Gateways and cost](https://opencontroller.lyzr.com/blog/cluster/gateways-and-cost)
