Virtual keys: a key per application
A virtual key is an API key that the gateway itself issues, stores in its database and can limit, track and revoke, so each application calls the gateway with its own key instead of a provider key.
Last updated: 12 Oct, 2026 · LiteLLM 1.105
Gateway keys protected the gateway with one master key. That key can do everything, so it cannot be handed to every application. Virtual keys fix that: the administrator keeps the master key, and each application gets a key of its own with a model list, a budget and a rate limit. Virtual keys need a Postgres database, which is not run in this course. This lesson shows the requests from the documentation without output, and runs what can run here: the list of fields the installed version accepts, the key routes it ships, and what a gateway with no database answers.
Syntax: a key is created with a POST to /key/generate, authorised by the master key, with a JSON body naming the limits.
curl http://localhost:4000/key/generate \
-H "Authorization: Bearer sk-<master-key>" \
-H "Content-Type: application/json" \
-d '{
"key_alias": "support-desk",
"models": ["quick", "careful"],
"max_budget": 10,
"budget_duration": "30d",
"rpm_limit": 60,
"team_id": "support"
}'Not run here. This block needs a Postgres database and shows no output.
Choosing what a key may do
Naming the models, the money and the rate
The virtual keys page shows models and metadata in its example request. It mentions the other fields in its sections on default and upper-bound settings, and its own example does not combine them the way the request above does. models lists the model names the key may call. max_budget is a spending cap in dollars. budget_duration is how often that budget applies, such as "10d". rpm_limit and tpm_limit limit requests and tokens. max_parallel_requests limits how many requests run at once. duration is how long the key lasts, such as "30d". key_alias is a name you can read. team_id attaches the key to a team. metadata holds anything you want to read back.
Checking the fields against the installed version
The request body is validated by a class in the installed package. Its field names are the arguments the gateway will accept, so reading them proves a name exists in this version and not only in a page.
from litellm.proxy._types import GenerateKeyRequest
wanted = ["key_alias", "models", "max_budget", "soft_budget", "budget_duration",
"rpm_limit", "tpm_limit", "max_parallel_requests", "duration",
"team_id", "model_max_budget", "metadata"]
for name in wanted:
print(f"{name:22}", GenerateKeyRequest.model_fields[name].annotation)key_alias str | None models list | None max_budget float | None soft_budget float | None budget_duration str | None rpm_limit int | None tpm_limit int | None max_parallel_requests int | None duration str | None team_id str | None model_max_budget dict | None metadata dict | None
Every name on the list exists in this version. model_max_budget takes a dictionary, so a budget can be set per model group. soft_budget and model_max_budget are in the installed class but the virtual keys page does not mention them. Confirm what they do on a gateway with a database before depending on them.
Listing the key routes
Creating a key is one of several routes. The installed gateway describes its own routes in an OpenAPI document, which lists the key management paths without starting a server.
from litellm.proxy.proxy_server import app
paths = app.openapi()["paths"]
print(*sorted(p for p in paths if p.startswith("/key/") and "{" not in p), sep="\n")/key/aliases /key/block /key/bulk_update /key/delete /key/generate /key/health /key/info /key/list /key/regenerate /key/service-account/generate /key/spend/report /key/unblock /key/update
Calling /key/generate with no database
A gateway without a database cannot store a key, so it cannot issue one. The example starts the same kind of gateway as the last lesson, with a master key and no DATABASE_URL, sends a /key/generate request, and prints the answer and the line the gateway logged.
import subprocess
import time
import urllib.request
from pathlib import Path
import httpx
def start(port=4400, env=None):
proc = subprocess.Popen(
["litellm", "--config", "config.yaml", "--port", str(port)],
stdout=open("gateway.log", "w"), stderr=subprocess.STDOUT, env=env,
)
while True:
try:
urllib.request.urlopen(f"http://127.0.0.1:{port}/health/liveliness")
return proc
except OSError:
time.sleep(1)
Path("config.yaml").write_text("""model_list:
- model_name: careful
litellm_params:
model: groq/openai/gpt-oss-120b
api_key: os.environ/GROQ_API_KEY
general_settings:
master_key: sk-gateway-1234
""")
proc = start()
try:
r = httpx.post("http://127.0.0.1:4400/key/generate", json={"max_budget": 10},
headers={"Authorization": "Bearer sk-gateway-1234"})
print(r.status_code, r.text)
finally:
proc.terminate()
proc.wait()
print([l.strip() for l in open("gateway.log") if "No module named" in l][:1])500 Internal Server Error ["ModuleNotFoundError: No module named 'prisma'"]
What the failed request showed
- No key was issued. The request carried the master key and a valid body, and the answer was a server error. Nothing was stored, because there is nowhere to store it.
- The log names a missing package on this install. The line it printed is
No module named 'prisma'. Theprismapackage is left out oflitellm[proxy]. The installed code also defines a clearer message for a gateway that hasprismabut noDATABASE_URL:DB not connected. This endpoint needs a database; set DATABASE_URL to a PostgreSQL connection string. That message comes from reading the installed source. This lesson did not run a gateway that reaches it. - The documentation says a database is required. The virtual keys page says a key needs a Postgres database, and that the proxy connects when
DATABASE_URLis set.
What a budget does when it is crossed
Budgets are checked against spend that the gateway reads from its database. The budgets page says so directly: budgets require a database, and without one the global max_budget check is skipped and requests carry on past the limit. With a database, the page shows an overspent key answered with an authentication error whose text is ExceededTokenBudget: Current spend for token: 7.2e-05; Max Budget for Token: 2e-07, and a team overspend answered with ExceededBudget: Crossed spend within team. It gives no status code for those two. For a per-model budget on a key it shows type budget_exceeded with code 400, and for an internal user's per-model budget it shows code 429. It says requests are rejected with 503 when spend cannot be verified. Do not write code that matches one status code for every budget. Not run here. This block needs a Postgres database and shows no output.
Rotating, blocking and deleting a key
The route list above names the other operations, and all of them exist in 1.105. The virtual keys page describes some of them. /key/regenerate rotates an existing key. /key/block disables a key and /key/unblock enables it again. /key/info reads a key and its spend. /key/update edits a key. That page does not describe /key/delete or /key/list, which are in the installed route list, so look up their request bodies in the gateway's own API reference. All of these need the same database.
Master key vs virtual key
| Master key | Virtual key | |
|---|---|---|
| Who holds it | The gateway's administrator | One application or agent |
| Where it is defined | master_key in the config, or LITELLM_MASTER_KEY | A row in the database, made by /key/generate |
| What it can do | Everything, including making keys | Call the models it lists, within its limits |
| Needs a database | No | Yes |
Where virtual keys fit
- One key per application. A leaked key costs one application, and it can be blocked without touching the others.
- One budget per team. A team id on each key lets a department have a ceiling.
- A named key per agent. An alias on the key makes the log say which agent made a call.
max_budget in its config is not enforced. Do not tell an application it has a budget until the gateway you deploy has a database and the budget has been tested against it.Related
- Previous: The gateway in a container
- Next: The admin UI: seeing what the gateway did
- Reference: Virtual keys and Budgets and users in the LiteLLM docs
- Add
"team_id": "support"to the request body in the last example and print the answer again. The database is still missing, so it fails the same way. - Print
GenerateKeyRequest.model_fields["budget_duration"].annotationand read the type it expects. - Print the paths that start with
/user/or/team/fromapp.openapi()["paths"]to see what else the database holds.
You understood something today that you didn't yesterday.