Provider Keys
Connect free-tier provider API keys to the gateway so it can route requests at $0 cost.
The gateway needs at least one provider key to actually serve completions. Keys are sent in requests as X-<Provider>-Key headers (BYOK) or stored encrypted on the server and used automatically.
Supported providers & header names
Pass the key per-request via the matching header, or store it via the API/dashboard:
| Provider | Header | Signup |
|---|---|---|
| Groq | X-Groq-Key | console.groq.com |
| Google Gemini | X-Google-Key | aistudio.google.com |
| OpenRouter | X-OpenRouter-Key | openrouter.ai |
| Cloudflare | X-Cloudflare-Key | dash.cloudflare.com |
| NVIDIA NIM | X-Nvidia-Key | build.nvidia.com |
| Cerebras | X-Cerebras-Key | cloud.cerebras.ai |
| Together | X-Together-Key | api.together.xyz |
| Fireworks | X-Fireworks-Key | fireworks.ai |
| Mistral | X-Mistral-Key | console.mistral.ai |
| SambaNova | X-SambaNova-Key | cloud.sambanova.ai |
| DeepSeek | X-DeepSeek-Key | platform.deepseek.com |
| DeepInfra | X-DeepInfra-Key | deepinfra.com |
| Cohere | X-Cohere-Key | dashboard.cohere.com |
Stored vs per-request
If you store a provider key on the server, the gateway uses it automatically — clients only need a gateway key. If you instead pass an X-<Provider>-Key header on a request, that overrides the stored key for that provider (useful for multi-tenant or testing).
Connect a key (stored, encrypted)
# 1. Get a session token (localhost only)
TOK=$(curl -s -H "host: localhost" http://localhost:4141/v1/gateway/bootstrap \
| python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
# 2. Store a provider key (encrypted at rest)
curl -X POST -H "x-freerouter-session: $TOK" \
-H "Content-Type: application/json" \
-d '{"provider":"groq","key":"gsk_xxx","label":"my-groq"}' \
http://localhost:4141/v1/providersList connected providers:
curl -H "x-freerouter-session: $TOK" http://localhost:4141/v1/providersRemove one (by id from the list above):
curl -X DELETE -H "x-freerouter-session: $TOK" \
http://localhost:4141/v1/providers/<id>Never commit keys
Provider keys are stored locally and encrypted. Do not put raw keys in code or version control. The dashboard "Connect a provider" form does the same POST /v1/providers call for you.
Use a key per-request (BYOK, no storage)
Skip storage entirely and pass the key inline. The model must then be a concrete provider/modelId:
curl http://localhost:4141/v1/chat/completions \
-H "X-Groq-Key: gsk_xxx" \
-H "Content-Type: application/json" \
-d '{"model":"groq/llama-3.1-8b-instant","messages":[{"role":"user","content":"Hi"}]}'See SDK Providers for the full list of free model IDs per provider.