Header rules

A header rule controls which request headers the gateway forwards to the backend, and lets you remove or add headers on the way.

Header rules are defined under Rules.HeaderRules and bound by name with HeaderRule on GlobalConfig, a server or a route. The closest scope wins: route, then server, then global. When no rule applies, all headers are forwarded.

Rules:
  HeaderRules:
    allowlist-headers:
      Mode: Custom
      CustomHeadersList: [X-Request-Id, X-Trace-Id]

    strip-and-set:
      Mode: All
      ForwardCookies: false
      Remove: [X-Internal]
      Set:
        X-Source: gateway

    preserve-host:
      Mode: All
      PreserveHost: true

Options

Key	Type	Default	Description
Mode	All or Custom	required	All forwards every header. Custom forwards only the headers in CustomHeadersList.
CustomHeadersList	list of header names	none	Headers forwarded when Mode is Custom.
ForwardAuthorization	true / false	true	false removes Authorization, X-Api-Key and X-Auth-Token.
ForwardCookies	true / false	true	false removes Cookie.
Remove	list of header names	none	Headers removed from the request.
Set	map of header name to value	none	Headers added to the request, replacing any existing value.
PreserveHost	true / false	false	true sends the client’s Host header to the backend instead of the backend’s own host.

Order of application

1. Mode and CustomHeadersList select the headers to keep.
2. ForwardAuthorization and ForwardCookies remove the credential headers when set to false.
3. Remove removes the listed headers.
4. Set adds the listed headers.

Because Set runs last, a header you set is always sent, even if an earlier step removed it.

Headers that are always kept in Custom mode

Content-Type, Content-Length and Content-Encoding are forwarded even when they are not in CustomHeadersList, because dropping them would break request bodies.

Header names

• Names are case insensitive, x-trace-id and X-Trace-Id are the same header.
• Names can’t be empty and can’t contain underscores or other characters that are not valid in a header name.
• Headers reserved for the gateway can’t be listed in CustomHeadersList: names starting with X-Nocleye-, and X-User-Id, X-User, X-User-Email, X-User-Roles, X-Tenant, X-Tenant-Id, X-Roles, X-Role, X-Client-Id, X-Caller-Id, X-Authenticated, X-Debug and X-Debug-Forwarded.

Headers removed from every request

To stop clients from impersonating an identity, the gateway always drops, regardless of the rule:

• any header whose name contains an underscore,
• the reserved headers listed above,
• Traceparent.

The only way to send one of the reserved headers to a backend is to add it yourself with Set.