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.
general_settings:
master_key: os.environ/LITELLM_MASTER_KEYAuthorization: Bearer <the master key> # the header every client library sendsSetting 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.
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")wrote config.yaml and gateway.py
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)no key LiteLLM proxy refused to start: no master key is set, so every request would be accepted without authentication. empty key LiteLLM proxy refused to start: the master key is empty. sk-1234 LiteLLM proxy refused to start: the master key is a publicly known default.
- 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.
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))right key, Bearer 200
right key, x-litellm-api-key 200
wrong key (400, '{"error":{"message":"No connected db.","type":"no_db_connection","param":null,"code":"400"}}')
no key (500, 'Internal Server Error')- The two right-key lines print 200. The proxy accepts the master key in the standard
Authorizationheader and in its ownx-litellm-api-keyheader. - 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 Erroron this install, which haslitellm[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 withNo api key passed in. Then the traceback shows the gateway's error handler runningimport prismaand failing withModuleNotFoundError.prismais the database package, and it ships in theextra-proxyextra, not inlitellm[proxy]. That is what the log showed. This lesson did not installprismaand 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 key | Gateway key | |
|---|---|---|
| Issued by | Groq, Gemini and other providers | you, with openssl rand -hex 32 |
| Held by | the server only | every caller of the server |
| Opens | the provider's API and its billing | the gateway's API |
Appears in config.yaml as | os.environ/GROQ_API_KEY | os.environ/LITELLM_MASTER_KEY |
| If it leaks | revoke it at the provider | change 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.
config.yaml: read it from the environment, as the config does here.Related
- Previous: Hybrid SDK, Router and gateway
- Next: The gateway in a container
- See also: Virtual keys: a key per application
- Reference: Master key rotations in the LiteLLM docs
- Change
sk-wrongto 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 wordBearer, and read the status. - Print
KEYinside thewithblock, then replace the constant ingateway.pywith a key fromopenssl rand -hex 32.
Every expert started right here.