What is a virtual key in an AI gateway?

Also called virtual API key, gateway-issued key

Definition

A virtual key is an API key issued by an AI gateway that maps a caller to its allowed models, budget, and rate limits, while the gateway keeps the real provider credentials.

A virtual key is a credential that an AI gateway issues to an application, team, or user in place of a model provider's API key. The caller sends the virtual key with each request, and the gateway looks up the policy attached to it, adds the real provider credential, and forwards the call. Provider keys stay in one place, and each caller gets its own budget, rate limits, and model access, which the gateway can change or revoke without touching the provider account.

How virtual keys work#

Virtual keys work as a policy lookup on every request. The gateway authenticates the key, checks that it is active and unexpired, confirms the requested model is allowed, checks the remaining budget and rate limits, and then selects a provider deployment and its credential. Usage and cost are recorded against the key, which produces spend reports per team or customer.

Gateway documentation describes similar fields:

  • Bifrost calls virtual keys its primary governance entity. Provider access is deny-by-default, a key can be restricted to specific provider API keys, budgets and rate limits on tokens and requests apply per key, and a key can belong to a team or a customer. Clients send it in an x-bf-vk header or in a provider-style authorization header.
  • LiteLLM creates keys through a /key/generate endpoint, with an allowed models list, model aliases, max_budget and budget_duration, rpm_limit and tpm_limit, a team or user owner, an expiry, and metadata. Key management requires a Postgres database. Provider credentials sit on the model entries in the proxy configuration, not on the key, and keys can also grant access to MCP servers.

The term is not fully standard across products. Portkey used "virtual key" for a securely stored provider credential and has since migrated the feature to its Model Catalog. Check what a product means by the term before comparing feature lists.

Virtual key vs provider API key#

A provider API key authenticates an organization to one model provider and draws on that organization's shared limits and billing. A virtual key authenticates one caller to the gateway and carries policy for that caller only. A leaked provider key exposes the account's whole quota; a leaked virtual key exposes one budget that the gateway can cap and revoke.

Provider API key Virtual key
Issued by Model provider AI gateway
Grants access to One provider's API Models the gateway exposes, often across providers
Limits and budget The organization's tier and spend limits Set per key, team, or customer
Effect of revoking Breaks every application using it Cuts off one caller
Held by The gateway Each application, team, or user

Concentrating provider keys in the gateway makes the gateway a high-value target, so keep those keys in a secret manager and restrict who can create virtual keys. Per-caller keys also make gateway logs attributable, so LLM observability dashboards can break down tokens, latency, and cost by team or customer. The same pattern extends to agent tool traffic through an MCP gateway. What is an AI gateway shows where key checks sit in the request path.

Cite this definition

The AI Engineering Editors. "What is a virtual key in an AI gateway?" The AI Engineering, updated Nov 11, 2026. https://theaiengineering.com/glossary/virtual-key

Title
What is a virtual key in an AI gateway?
Author
The AI Engineering Editors
Publisher
The AI Engineering
Updated
View as Markdown

Part of the AI gateways and LLM routing hub · Updated