> ## Documentation Index
> Fetch the complete documentation index at: https://wundergraphinc-brendan-add-sof-link.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Subgraph Request Headers Operations

> The router allows users to operate on the request headers.

## 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](/router/configuration#config-file) file and adjust it according to your needs.

```yaml theme={null}
# 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"
```

### 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.

### 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](https://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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#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](/router/configuration/template-expressions) 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.

<Note>
  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.
</Note>

### 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.

```yaml theme={null}
headers:
  all:
    request:
      - op: "propagate"
        named: "X-User-Id"
        default: "123"
```

### gRPC services

When using [Cosmo Connect](/connect/overview), headers are forwarded to gRPC services as [metadata](https://grpc.io/docs/guides/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.

<Info>
  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.
</Info>