Headers

Header go through many different components during the lifecycle of a request:

1. on_request hook has mutable access to the incoming gateway headers before anything else.
2. authenticate has read-only access to the gateway headers
3. global header rules are applied. From now on we're talking about "subgraph headers" rather than the "gateway headers"
4. authorize_query has mutable access to the subgraph headers.
5. subgraph header rules are applied.
6. on_subgraph_request is the final component with mutable access to the subgraph headers just before sending the request.

Define header rules and execute them in order. The gateway uses forward, insert, rename_duplicate or remove rules to manage headers for subgraphs:

[[headers]]
rule = "forward"
name = "authorization"

[[headers]]
rule = "forward"
name = "x-custom-header"
rename = "y-custom-header"

[[headers]]
rule = "forward"
name = "x-possible-empty"
default = "default-value"

Forward multiple headers by using a regular expression.

The engine matches headers in lowercase. Write your regular expression in lowercase, or add a flag to match both lowercase and uppercase letters.

[[headers]]
rule = "forward"
pattern = "^x-custom*"

Use the insert rule to add header values:

[[headers]]
rule = "insert"
name = "authorization"
value = "Bearer secret-token"

Insert header values from environment variables:

[[headers]]
rule = "insert"
name = "authorization"
value = "Bearer {{ env.AUTHORIZATION_TOKEN }}"

Use the remove rule to block header forwarding for headers that match patterns:

[[headers]]
rule = "remove"
name = "x-custom-secret"

The rename_duplicate rule forwards the defined header value and copies the value with the specified rename to the subgraphs.

[[headers]]
rule = "rename_duplicate"
name = "x-custom-value"
default = "the value was missing"
rename = "y-custom-value"

The gateway forwards two headers to the subgraph with the same value - one named x-custom-value and one named y-custom-value. When a request is missing the x-custom-value header, and you define a default value, the gateway creates both headers using that default value. If you omit the default, the gateway doesn't forward the header or create a duplicate.

It is also possible to use dedicated subgraph header rules. For example to apply header rules only for the prodcuts subgraph you may use the following:

[[subgraph.products.headers]]
rule = "forward"
name = "x-custom-header"
rename = "y-custom-header"