Add static headers on gateway upstreams

Static headers on upstream requests

To add fixed headers to the requests the gateway sends to one upstream, set headers: on that upstream. Use it when a proxy you run in front of the provider routes or attributes traffic by a header.

headers: requires Claude Code v2.1.277 or later on the gateway server. An earlier gateway refuses to start when it finds the key. Upgrade every replica before you add the key, and remove the key before you roll back to an earlier version.

The headers go to the server that base_url names, or to the provider's own endpoint when base_url is unset. The provider receives them too unless your proxy removes them.

This example reaches a provider: vertex upstream through a proxy at upstream-proxy.internal.example.com. It sets the x-source header the proxy reads, and sends a token from the PROXY_TOKEN environment variable as x-proxy-token:

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    base_url: https://upstream-proxy.internal.example.com
    auth: {}
    headers:
      x-source: claude-apps-gateway
      x-proxy-token: ${PROXY_TOKEN}

Values are printable ASCII text with no space at either end. Quote a number, true, or false so YAML reads it as text.

To keep a secret out of the config file, use secret expansion to load the value from an environment variable with ${VAR} or from a file with ${file:/path}. A ${VAR} that resolves to an empty value stops the gateway from starting.

headers: works on every provider, and each upstream sends only its own.

Not every request that the gateway sends to an upstream carries them:

Request the gateway sends to this upstream	Carries headers:
/v1/messages, streaming or not, and /v1/messages/count_tokens	Yes
A request that failed over from another upstream	Yes, this upstream's headers: only
Amazon Bedrock's CountTokens call for a request the client abandoned	No
The Workload Identity Federation token exchange	No

On an Amazon Bedrock or Claude Platform on AWS upstream that signs requests with AWS SigV4, these headers are part of the signature, so your proxy must pass them through unchanged.

If you use a name the gateway reserves, it refuses to start, and the startup error names the header. Reserved names include:

• authorization and x-api-key
• host, content-type, and user-agent
• Any name starting with anthropic-, x-goog-, x-amz-, or x-amzn-