LiteLLMLiteLLM 1.105 · Python 3.10+
Dashboard
0%

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.

bash
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.

ExampleThe key fields LiteLLM 1.105 accepts
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)

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.

ExampleThe key routes in LiteLLM 1.105
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")

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.

ExampleA gateway with no database refuses to issue a key
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])

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'. The prisma package is left out of litellm[proxy]. The installed code also defines a clearer message for a gateway that has prisma but no DATABASE_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_URL is 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 keyVirtual key
Who holds itThe gateway's administratorOne application or agent
Where it is definedmaster_key in the config, or LITELLM_MASTER_KEYA row in the database, made by /key/generate
What it can doEverything, including making keysCall the models it lists, within its limits
Needs a databaseNoYes

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.
Watch out. A gateway with no database accepts only the master key, and 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.
Try it yourself
  • 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"].annotation and read the type it expects.
  • Print the paths that start with /user/ or /team/ from app.openapi()["paths"] to see what else the database holds.

You understood something today that you didn't yesterday.