Request Header Operations for GraphQL Federation

Decide exactly which headers reach your subgraphs. Set rules in YAML: no middleware, no code changes to subgraphs.

Nothing is forwarded by default. You say what reaches each subgraph.

Incoming headers · curated per rule

The Problem

Headers are powerful and easy to over-share

Federated graphs need a single place to enforce what crosses the trust boundary to subgraphs.

Forwarding all headers exposes data you did not mean to share

Cookies, internal tracing headers, load-balancer metadata: the set of headers on an incoming request is wider than what any subgraph actually needs. Blind forwarding is a leak waiting to happen.

Header middleware per subgraph creates drift

Each subgraph team ends up with its own parsing of Authorization, its own correlation-id logic, its own fallback behavior. The rules diverge over time, and nothing is centrally enforceable.

Static forwarding is not enough

Some headers need to be computed at the router (a user id from a validated JWT, a default when the client does not send one). None of that fits into forward this header name.

Our Solution

Declarative header control with no custom middleware

Cosmo Router request header operations let you control exactly which headers reach your subgraphs: propagate, set static values, compute from auth claims, or forward all with an allowlist. YAML rules live at the router, not in middleware scattered across subgraphs.

What happens at request time

1. Request header operations in Cosmo Router give you declarative control over which HTTP headers reach each subgraph, forwarding none by default.
2. Propagate by name or regex, inject static values for service auth, or compute values from JWT claims, all in YAML with no custom middleware.
3. Rules live under all for global defaults and under subgraphs for per-subgraph overrides. Evaluation order is predictable.

YAML rules keep evaluation predictable and diffs auditable.

Request headers

Before & After

Router Controls

Three capabilities

• Security by default

No headers reach subgraphs unless you explicitly configure them. Define an allowlist with propagate rules instead of blocking a denylist.

• Dynamic values

Compute header values using template expressions with access to authentication claims and request context. No custom middleware needed.

• Per-subgraph control

Apply different header rules to different subgraphs while maintaining global defaults. One config file covers the entire graph.

How request header operations work

1. Global defaults + targeted overrides.

Declare rules in config

headers.all.request sets global propagate/set rules; headers.subgraphs.<name>.request layers per-subgraph overrides.

2. Go regex; (?i) for case-insensitive.

Rules match incoming headers

Match a single name, a regex family, or compute values from request context with expressions.

3. Default deny, explicit allow.

Outgoing request is assembled

Headers added, renamed, or set on the outgoing request. Headers with no rule are not forwarded.

4. One enforcement point.

Subgraph receives the curated set

The subgraph sees exactly the headers your config said it should.

Lock down subgraph headers from one config

Allowlist what crosses the boundary without middleware sprawl.

FAQ

Request header operations

• Which HTTP headers does a GraphQL federation router forward to subgraphs by default?
• How do you rename an HTTP header between a GraphQL client and a subgraph?
• How do you forward JWT claims to GraphQL subgraphs as headers?
• Can different GraphQL subgraphs receive different request headers in a federated graph?
• What regular expression syntax is supported for matching HTTP header names in a GraphQL router?
• When should you use custom code instead of declarative YAML for header logic in a GraphQL router?
• What is the difference between propagating an existing header and setting a static one in a GraphQL router?

Full reference in the request headers documentation.