For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Provide and rotate the API keys that agentgateway uses to authenticate to your LLM providers.

Provider API keys authenticate agentgateway to LLM providers such as OpenAI or Anthropic. A leaked key lets attackers run requests at your expense.

Clients can authenticate with virtual keys. Agentgateway replaces each virtual key with the provider key before forwarding the request.

This guide covers inline keys, environment variables, files, and Kubernetes secrets or passthrough tokens. To replace an existing key, see Rotate a provider key.

Before you begin

Configure your agentgateway proxy

Choose how to provide the key.

Rotate a provider key

Rotate provider keys regularly, when your provider requires it, or after a suspected leak. Clients that use virtual keys need no configuration changes.

1. Create a new API key in the console of your LLM provider. Keep the old key active for now.

2. Replace the key on the gateway using the method that matches your configuration.

   Option	How to replace the key	Restart needed
   File (auth.key.value.file)	Replace the file contents. Agentgateway uses the new key for the next request.	No
   Inline	Edit the key in the configuration file. Agentgateway reloads the file when it changes.	No
   Environment variable	Set the variable to the new key and restart agentgateway.	Yes

   For file references in params.apiKey, agentgateway reads the key only when loading the configuration. After replacing the key file, save the configuration file to trigger a reload, or restart agentgateway.

3. Send a request through agentgateway, and verify that it succeeds with the new key. If your gateway requires virtual keys, add an Authorization: Bearer <virtual-key> header.

   curl -s http://localhost:4000/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello!"}]}' | jq .

   Example output:

   {
     "choices": [{
       "message": {
         "role": "assistant",
         "content": "Hello! How can I help you today?"
       }
     }]
   }

4. Revoke the old key in the console of your LLM provider.

Next steps