LiteLLMLiteLLM 1.105 · Python 3.10+
Dashboard
0%

Gateway keys

A gateway key is the secret that a caller sends to the LiteLLM proxy in the Authorization header, which the proxy checks before it forwards anything to a provider.

Last updated: 12 Oct, 2026 · LiteLLM 1.105

Hybrid SDK, Router and gateway said that the gateway holds the provider keys. The gateway's own address is reachable by anyone who can reach the port, so it needs its own lock. That lock is the gateway key, and it is separate from the Groq and Gemini keys behind it.

Syntax: the master key is set in general_settings, and callers send it as a bearer token.

yaml
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
python
Authorization: Bearer <the master key>        # the header every client library sends

Setting the master key

Choosing a key the proxy accepts

The master key is the one key that is always valid. The proxy refuses to start with a master key it cannot trust. It refuses three kinds: none, an empty one and a publicly known default. The refusal message also prints a recipe for a good key: sk- followed by the output of openssl rand -hex 32. The program starts the server three times, with no key, with an empty key and with sk-1234, a key that many docs examples use, and prints the refusal line each time.

ExampleWriting config.yaml and gateway.py
import sys
from pathlib import Path

Path("config.yaml").write_text("""model_list:
  - model_name: fast
    litellm_params:
      model: groq/openai/gpt-oss-20b
      api_key: os.environ/GROQ_API_KEY
  - model_name: smart
    litellm_params:
      model: groq/openai/gpt-oss-120b
      api_key: os.environ/GROQ_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
""")
Path("gateway.py").write_text("""import os, subprocess, sys, time, urllib.request
from contextlib import contextmanager

KEY = "sk-gateway-demo-0123456789abcdef"

@contextmanager
def running(port, config="config.yaml"):
    env = {**os.environ, "LITELLM_MASTER_KEY": KEY}
    litellm = os.path.join(os.path.dirname(sys.executable), "litellm")
    cmd = [litellm, "--config", config, "--port", str(port)]
    proc = subprocess.Popen(cmd, env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
    try:
        for _ in range(60):
            try:
                urllib.request.urlopen(f"http://127.0.0.1:{port}/health/readiness")
                break
            except OSError:
                time.sleep(1)
        yield f"http://127.0.0.1:{port}"
    finally:
        proc.terminate()
        proc.wait(10)
""")
sys.path.insert(0, ".")      # lets the programs that follow import gateway from this folder
print("wrote config.yaml and gateway.py")
ExampleThree unsafe master keys are refused
import os, re, subprocess, sys

litellm = os.path.join(os.path.dirname(sys.executable), "litellm")
for label, key in [("no key", None), ("empty key", ""), ("sk-1234", "sk-1234")]:
    env = {k: v for k, v in os.environ.items() if k != "LITELLM_MASTER_KEY"}
    if key is not None:
        env["LITELLM_MASTER_KEY"] = key
    run = subprocess.run([litellm, "--config", "config.yaml", "--port", "4125"],
                         env=env, capture_output=True, text=True, timeout=90)
    text = re.sub(r"\x1b\[[0-9;]*m", "", run.stdout + run.stderr)
    line = [l for l in text.splitlines() if l.startswith("LiteLLM proxy refused")][0]
    print(f"{label:10}", line)
  • Each refusal line names its reason: no key set, an empty key, or a publicly known default. The proxy stops instead of starting with a key that anyone could leave out or guess. The program stopped on its own each time, so no server was left running.

Calling with and without the key

The program starts the server with a proper key and sends four requests for the model list: the right key as a bearer token, the right key in the x-litellm-api-key header, a wrong key, and no key. It prints the HTTP status of each, and for a failure the first part of the body.

ExampleFour requests to the model list
import urllib.error, urllib.request
from gateway import running, KEY

def try_models(url, headers):
    try:
        return urllib.request.urlopen(urllib.request.Request(url + "/v1/models", headers=headers)).status
    except urllib.error.HTTPError as err:
        return err.code, err.read().decode()[:100]

tries = [
    ("right key, Bearer", {"Authorization": f"Bearer {KEY}"}),
    ("right key, x-litellm-api-key", {"x-litellm-api-key": KEY}),
    ("wrong key", {"Authorization": "Bearer sk-wrong"}),
    ("no key", {}),
]
with running(4123) as url:
    for label, headers in tries:
        print(f"{label:30}", try_models(url, headers))
  • The two right-key lines print 200. The proxy accepts the master key in the standard Authorization header and in its own x-litellm-api-key header.
  • The wrong key is rejected with status 400 and the message No connected db. This server has no database, and the Docker quick start page says a request that carries a virtual key fails with that message. The master key is the only key the proxy can check without a database.
  • No key is rejected with status 500 and a bare Internal Server Error on this install, which has litellm[proxy] only. The request does not get through, but the status is not the 401 that many clients expect. The gateway log for that request starts with No api key passed in. Then the traceback shows the gateway's error handler running import prisma and failing with ModuleNotFoundError. prisma is the database package, and it ships in the extra-proxy extra, not in litellm[proxy]. That is what the log showed. This lesson did not install prisma and run the request again, so it does not claim what status a gateway with that package returns. Treat any non-200 reply as a refusal and read the server's own log for the reason.

Gateway key vs provider key

Provider keyGateway key
Issued byGroq, Gemini and other providersyou, with openssl rand -hex 32
Held bythe server onlyevery caller of the server
Opensthe provider's API and its billingthe gateway's API
Appears in config.yaml asos.environ/GROQ_API_KEYos.environ/LITELLM_MASTER_KEY
If it leaksrevoke it at the providerchange it in the server's environment

Where you use gateway keys

  • A shared server on a company network, where the key stops anyone who finds the port.
  • Rotating a provider key in one place, because callers never held it.
  • Giving a script access by handing it the gateway's address and key instead of a provider account.
Watch out. The master key opens everything on the server, including its admin routes. Give it to the person who runs the gateway, and give applications keys of their own, which Virtual keys: a key per application covers. Per-application keys need a database, which this lesson's server does not have. Never write a key into config.yaml: read it from the environment, as the config does here.
Try it yourself
  • Change sk-wrong to the right key with one character removed. The reply is the same wrong-key reply.
  • Add a fifth request with the header Authorization: KEY, without the word Bearer, and read the status.
  • Print KEY inside the with block, then replace the constant in gateway.py with a key from openssl rand -hex 32.

Every expert started right here.