Skip to navigation

Request and response headers

Fabric AI Gateway reads some request headers to authenticate and route a request, and adds some headers to the response. This page lists those headers, and what the gateway changes in the request that the upstream receives. Every other header passes through unchanged in both directions.

Header names aren’t case-sensitive.

Request headers the gateway reads

HeaderRoute typesWhat it does
fg-api-keyAllCarries the gateway key. Key Auth reads the key from this header, and the key also selects the namespace whose routes serve the request. A request with no fg-api-key is served by the Default namespace’s routes. A key that the gateway doesn’t know is refused with 401 before any route is matched. Until the data plane has received its first configuration, a request that carries a gateway key gets 503, so retry it. A request without a key gets 404. Two different key values in the headers that the route reads get 401 with conflicting credentials. The gateway never forwards this header to the upstream. For details, see Authenticate and send a request.
AuthorizationAllWith JWT Auth, carries Bearer <token> from your identity provider.
x-gateway-serviceLLMSends the request to the named connection on the route, with no failover to other connections. On a route with several connections and no routing plugin, the header is required. A missing, empty, or unknown name gets 400. On a route with the llm-model-router plugin, the gateway ignores this header: it doesn’t change which providers are tried and never produces the 400.
X-Amr-Session-IDLLMPins a conversation to one model when the route uses the Adaptive Model Router, so that each turn reuses the same model and keeps the provider’s prompt cache. The router also recognizes X-Claude-Code-Session-ID, Thread-ID, Session-ID, Session_Id, X-Session-ID, and X-Session-Affinity, in that order. It uses the first one that has a value. If that value is over 256 characters, the request isn’t pinned: the router doesn’t fall back to the next header. For details, see Route requests with the Adaptive Model Router.
anthropic-versionLLMForwarded to the provider unchanged. On a route with the llm-model-router plugin, it also makes GET /v1/models answer in Anthropic’s list format instead of OpenAI’s.
X-Request-IdAllIf you send one of up to 256 characters, the gateway uses it as the request ID, forwards it to the upstream, and returns it. Otherwise the gateway generates one.
traceparent, B3 headersAllIf you send trace context, the gateway continues your trace and passes it on to the upstream.
Mcp-Session-IdMCPIdentifies the MCP session. The gateway sets it in its answer to initialize, and the client sends it on later requests.
MCP-Protocol-VersionMCPNames the MCP protocol revision. It must agree with the request body, or the gateway answers 400.
Accept: text/event-streamMCPOn a GET, opens the long-lived notification stream for the caller.

An admin can set a Key Auth instance to read the gateway key from a list of headers instead, such as Authorization: Bearer and x-api-key, the headers that the OpenAI and Anthropic SDKs send. On such a route, Key Auth reads only those headers. If more than one of them carries a key and the keys differ, the request gets 401 conflicting credentials.

Headers that providers read, such as anthropic-beta and OpenAI-Organization, reach the provider unchanged.

Response headers the gateway adds

HeaderWhenValue
X-Request-IdEvery response, including errorsThe request ID: yours, or one the gateway generated. Quote it when you contact support, and use it to find the request in Traces.
x-fabric-modelLLM routes with the llm-model-router plugin, when a provider answeredThe provider and model that answered, for example openai/gpt-4o-mini.
X-Amr-Model, X-Amr-Tier, X-Amr-Escalations, X-Amr-Cost-Usd, X-Amr-StrategyLLM routes where the Adaptive Model Router answered in cascade modeThe model that answered, its tier, how many times the router escalated, the estimated cost in USD, and the strategy it used.
RateLimit-Limit, RateLimit-Remaining, RateLimit-ResetA rate limit plugin instance that is set to show headersThe configured limit, the requests left, and the seconds until the window resets. The gateway also sends the same three as X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When several limits apply, the headers describe the one with the fewest requests left.
RateLimit, RateLimit-PolicySame as aboveRateLimit is limit=…, remaining=…, reset=…. RateLimit-Policy is <limit>;w=<window seconds>.
Retry-AfterSome 429 and 503 errorsSeconds to wait before you retry. It’s sent with a 429 from the LLM Rate Limit plugin, with a 429 from a rate limit instance that shows headers, and with 503 upstream_auth_unavailable (5).
WWW-Authenticate401 from JWT AuthBearer resource_metadata="<url>". MCP clients follow the link to sign in.
Allow405The methods that the route accepts for the path.

On LLM routes, the provider’s response is never compressed, because the gateway reads it to count tokens. If a provider compresses it anyway, the gateway decompresses it and removes Content-Encoding and Content-Length.

What the upstream receives

The gateway forwards the request with these changes:

  • Your gateway credential is removed. The fg-api-key header is always removed. So is the header that the authentication plugin read the key or token from.
  • The upstream credential is added. For a provider, the gateway adds the credential from the connection in the provider’s own header, such as Authorization: Bearer … or x-api-key, or signs the request, for example with AWS Signature Version 4 for Amazon Bedrock. A client header with the same name is replaced.
  • Forwarding headers are set. X-Forwarded-For gets your address appended. X-Forwarded-Proto and X-Forwarded-Host are set if you didn’t send them. Host is the upstream’s host.
  • Console cookies are removed. Cookies whose names start with fabric_, which the Fabric console sets, are removed from the Cookie header. Other cookies pass through.
  • Hop-by-hop headers are removed. Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, TE, Trailer, Transfer-Encoding, and Upgrade aren’t forwarded. Because Upgrade is removed, WebSocket connections don’t work through the gateway.
  • Compression is turned off where the gateway reads the response. Accept-Encoding is removed on LLM and MCP routes, and on REST routes whose responses are transformed or validated.
  • Trace context is added. The upstream receives W3C traceparent and B3 headers for the current trace.

Next steps