Which HTTP headers does a GraphQL federation router forward to subgraphs by default?

None. No headers are forwarded automatically — you explicitly define what reaches subgraphs.

How do you rename an HTTP header between a GraphQL client and a subgraph?

Use the rename parameter within a propagate rule.

How do you forward JWT claims to GraphQL subgraphs as headers?

Use a dynamic header with a template expression. For example: expression: "request.auth.isAuthenticated ? request.auth.claims.sub : ''". The router extracts the claim from the validated JWT and sends it as a header.

Can different GraphQL subgraphs receive different request headers in a federated graph?

Yes. You can apply different header rules per subgraph while maintaining global defaults.

What regular expression syntax is supported for matching HTTP header names in a GraphQL router?

Go regex syntax, used with the matching parameter. Example: matching: (?i)^X-Correlation-.*

When should you use custom code instead of declarative YAML for header logic in a GraphQL router?

YAML covers all standard cases. Reach for custom code when you need logic that configuration can't express — such as dynamic computation tied to external systems or complex conditional logic.

What is the difference between propagating an existing header and setting a static one in a GraphQL router?

Propagating forwards a header from the original client request. Setting adds a new header with a fixed value you define in config, independent of what the client sent.

GraphQL Request Header Operations | Cosmo by WunderGraph

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

Request header operations in Cosmo Router give you declarative control over which HTTP headers reach each subgraph, forwarding none by default.
Propagate by name or regex, inject static values for service auth, or compute values from JWT claims, all in YAML with no custom middleware.
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

Before Cosmo	With Cosmo
Blanket forward-all or custom middleware per subgraph	Declarative allowlist with named, regex, or expression rules
JWT parsing duplicated in every subgraph	Router validates once; `request.auth.claims.sub` forwarded as a header
No standard way to inject service-to-service auth	`set` operation adds static headers globally or per subgraph
Rename headers requires custom code	`rename` field in YAML does it

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

01

Global defaults + targeted overrides.

Declare rules in config

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

02

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.

03

Default deny, explicit allow.

Outgoing request is assembled

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

04

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.

Start Free Read the Docs

Request Header Operations for GraphQL Federation