subgraph-request-header-operations.mdx

title	Subgraph Request Headers Operations
description	The router allows users to operate on the request headers.
icon	arrow-right-to-bracket

Forward HTTP headers to subgraphs

Forwarding specific client headers (request headers) to your subgraphs is a straightforward process. By default, no headers are forwarded for security reasons. To enable header forwarding, insert the following snippet into your config.yaml file and adjust it according to your needs.

# config.yaml

# See https://cosmo-docs.wundergraph.com/router/configuration#config-file
# for the full list of configuration options.

headers:
  all: # Header rules for all subgraph requests.
    request:
      - op: "propagate"            # Forward a client header
        named: X-Test-Header       # Exact match (Use the canonicalized version)

      # Regex match (Case insensitive)
      - op: "propagate"
        matching: (?i)^X-Custom-.*

      - op: "propagate"
        matching: ^(Header-1|Key)$
        negate_match: true         # Ensure that all headers except the Header-1 and Key are propagated

      # Sets the value when the header was not set
      - op: "propagate"
        named: "X-User-Id"
        default: "123"

      # Rewrites the header from X-Test-1 to X-Test
      - op: "propagate"
        named: "X-Test-1"
        rename: "X-Test"

      - op: "set"
        name: "X-Custom-Header"
        value: "my-required-key"

      # Dynamic value using template expression
      - op: "set"
        name: "X-User-ID"
        expression: "request.auth.isAuthenticated ? request.auth.claims.sub : ''"

  subgraphs:
    products: # Will only affect the Subgraph named "products"
      request:
        - op: "propagate"
          named: "Subgraph-Secret"
          default: "some-secret"

  subgraph_patterns: # Apply rules to every subgraph whose name matches the regex
    - matching: "^products(-feature-.+)?$"
      request:
        - op: "propagate"
          named: "X-Products-Auth"

What does the snippet do?

With all we address all subgraph requests. Next, we can define several rules on the client's request. The operation propagate forwards all matching client request headers to the subgraphs. The operation set sets a new header which is forward to the subgraphs.

The subgraphs section allows to propagate headers for specific subgraphs. The name must match with the subgraph name in the Studio.

The subgraph_patterns section applies rules to every subgraph whose name matches the regular expression in matching. This is useful for targeting a base subgraph and its feature subgraphs (for example, PR-preview deployments named products-feature-pr-123) without duplicating the same block under every variant.

Rule evaluation order

Rules are applied in this order:

1. headers.all rules.
2. headers.subgraph_patterns entries whose matching regex matches the subgraph name, in config order.
3. headers.subgraphs.<name> rules for the exact subgraph name.

Because exact rules are applied last, a rule under headers.subgraphs.products can still override a broader pattern rule when both target the same header.

Pattern selectors

Each entry under subgraph_patterns accepts:

• matching — A Go regular expression evaluated against the subgraph name. Required.
• negate_match — If true, the regex result is inverted. Useful for "all subgraphs except X" rules.
• request — Request rules to apply when the pattern matches.
• response — Response rules to apply when the pattern matches.

Subgraph names are case-sensitive identifiers. Invalid regular expressions fail router startup.

Supported header rules

Currently, we support the following header rules:

• propagate - Forwards all matching client request headers to the subgraphs. You can choose between one of the following matchers:

  • named - It exactly matches on the header name.

  • matching - Regex matches on the header name. You can use regex101.com to test your regexes. Go to the website and select Golang on the left panel. Note: The Router never propagates hop-by-hop headers (such as Connection) when propagating by regex.

  • negate_match - If set to true, the result of the matching regex will be inverted. This is useful for simulating negative lookahead behavior, which is not natively supported.

  • rename: Replaces the identified header based on its name or matching criteria and transfers the value to the newly specified header.

  • default: Fallback to this value when the named, matching or rename header could not be found.

• set - Sets a header on the request forward to the subgraph. You must set one of the following:

  • name - The name of the header to set

  • value - The static value to set for the header

  • expression - A template expression that evaluates to the value of the header. For example: request.auth.isAuthenticated ? request.auth.claims.sub : '' will set the header to the user's ID if they are authenticated, otherwise an empty string.

Go canonicalizes headers by default e.g. `x-my-header` to `X-My-Header.` Write your rule accordingly or use `(?i)``^X-Test-.*` flags to make your regex case insensitive.

Default value

You can also define a value when the client header is not set by the client. Can only be used with the named matcher.

headers:
  all:
    request:
      - op: "propagate"
        named: "X-User-Id"
        default: "123"

gRPC services

When using Cosmo Connect, headers are forwarded to gRPC services as metadata according to the rules defined in the config. Metadata keys match header names but in lowercase. To access X-User-Id you need to use x-user-id as the key.

Rule ordering

All rules are evaluated in the order they are defined.

Please inform us if you have more advanced use cases that cannot be accommodated with the current feature set. You can still use [Custom Modules](/router/custom-modules) to implement any logic yourself. You can aggregate, remove, or add headers as you like.