Skip to main content

Authentication

Provider credentials​

Set provider specific credentials as environment variables. The gateway injects these when proxying requests to providers.

Example for OpenAI:

export OPENAI_API_KEY=sk-your-key

Gateway API keys​

The gateway's primary credential is the MASTER_KEY. It is a single admin credential used for both the admin API and client (proxy) requests. Run ferrogw init to generate one, then export it:

export MASTER_KEY="ferro-..."   # generated by `ferrogw init`

Once a MASTER_KEY is set you can use it as a bearer token to call the admin API and issue scoped, persistent gateway API keys via POST /admin/keys. Those issued keys can then be used by clients in place of the master key.

Deprecated: bootstrap keys

The legacy ADMIN_BOOTSTRAP_KEY / ADMIN_BOOTSTRAP_READ_ONLY_KEY env vars are deprecated and emit deprecation warnings at startup. They are honored only on first run while the API key store is empty and MASTER_KEY is unset. Use MASTER_KEY instead.

Client request authentication​

By default, all /v1/* inference routes require authentication (/v1/chat/completions, /v1/completions, /v1/embeddings, /v1/images/generations, /v1/models, and the pass-through proxy). Clients must send a bearer token — either the MASTER_KEY or an admin-issued API key:

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

To disable proxy authentication for local development only, set ALLOW_UNAUTHENTICATED_PROXY=true. The gateway logs a warning on startup when this is enabled; it is not recommended for production.