Modify HTTP request headers in Gateway

Gateway HTTP policies with Allow actions can modify the headers of matching requests before they reach their destination. You can add dynamic values to set headers to forward information like user identity, source IP, and other inputs to upstream services, enforce SaaS tenant control, strip internal headers, override header content.

Header manipulation requires TLS decryption, because HTTP headers are only visible on traffic which Gateway can decrypt.

Gateway supports three header operations on HTTP policies. When a request matches an Allow policy with header operations configured, Gateway applies them in the following order:

1. Delete - Remove headers from the request.
2. Overwrite - Overwrite headers on the request. Headers with matched names will have their values overwritten. If the header does not exist, it is created.
3. Add - Append headers to the request. If the header already exists, the added value is appended to the existing value.

You can configure up to 20 header operations per policy. Header names are limited to 256 bytes, and header values are limited to 4 KB.

Adding a header appends a value to the request. If the header already exists, the value is added alongside the existing value rather than replacing it.

Overwriting a header overwrites any existing value. If the header does not already exist on the request, it is created. Use this operation when you need to guarantee a specific header value regardless of what the client sent.

Deleting a header removes it from the request entirely. If the header does not exist, the operation has no effect.

Header values can include dynamic variables that Gateway resolves at request time using identity, device, and network context from the current session. Dynamic variables use the @{...} syntax and can be mixed with static text in the same value.

For example, a header value of user-@{identity.email} resolves to user-jdoe@example.com at request time.

The following dynamic variables are available:

Dynamic variables require an active identity session. If Gateway cannot resolve a variable (for example, the user is not authenticated), the variable is replaced with a warning string such as cf-unresolved or cf-invalid, and a warning is added to the HTTP log.

To create an HTTP policy with header operations:

1. In the Cloudflare One dashboard ↗, go to Traffic policies > Firewall policies > HTTP.
2. Select Add a policy.
3. Build an expression to match the traffic you want to modify.
4. In Action, select Allow.
5. Under Modify request headers, select Add or Overwrite to add or overwrite headers, or select Remove to delete a header.
6. For Add and Overwrite operations, enter the header name and value. To use a dynamic variable, enter the @{...} syntax in the value field, or select the {} button to see the list of available values. For Remove operations, enter only the header name.
7. Save your policy.

To create an HTTP policy with header operations via the API, include add_headers, set_headers, and delete_headers in the rule_settings object.

curl https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/rules \
--header "Authorization: Bearer {api_token}" \
--header "Content-Type: application/json" \
--data '{
  "name": "Forward identity headers",
  "action": "allow",
  "enabled": true,
  "filters": ["http"],
  "traffic": "any(http.request.domains[*] in {\"app.example.com\"})",
  "rule_settings": {
    "add_headers": {
      "X-User-Email": ["@{identity.email}"],
      "X-User-Groups": ["@{identity.groups}"]
    },
    "set_headers": {
      "X-Forwarded-User": ["@{identity.email}"]
    },
    "delete_headers": ["X-Debug-Token", "X-Internal-Only"]
  }
}'

The rule_settings fields for header manipulation are:

A single header value can contain a mix of static text and dynamic variables. For example:

{
  "add_headers": {
    "X-Request-Context": ["user=@{identity.email}, device=@{device.id}, src=@{source.ip}"]
  }
}

If you save a HAR (HTTP Archive) file from a browser to analyze your web traffic, custom headers defined with Gateway will not appear in the file. This is because Gateway injects the header after the request leaves the browser.

To verify Gateway is applying a custom header:

1. In your policy with custom headers, add a selector to match traffic for HTTPBin ↗, an open-source site for testing HTTP requests. For example:

   Selector	Operator	Value	Logic	Action	Untrusted certificate action
   Application	in	Google Workspace	Or	Allow	Block
   Domain	in	httpbin.org

2. On your device, go to httpbin.org/anything ↗. Your custom header will appear in the list of headers.

3. (Optional) Remove the HTTPBin expression from your policy.

Tenant control allows your users to access corporate SaaS applications while blocking access to personal accounts on the same service. For example, you can allow access to your company's Google Workspace while blocking personal Gmail logins.

Gateway implements tenant control by injecting custom HTTP headers into matching requests. These headers tell the SaaS application which tenant (organization) is authorized. If the user attempts to authenticate with a personal account, the SaaS application reads the header and rejects the request.

You can use dynamic header values to forward user identity information to your upstream applications without requiring those applications to integrate with Cloudflare Access directly.

Your upstream application can read these headers to identify the user, enforce authorization logic, or populate audit logs.

To prevent clients from spoofing internal headers, use the delete operation to remove headers before forwarding the request, then use the add or set operation to re-inject them with verified values.

curl https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/rules \
--header "Authorization: Bearer {api_token}" \
--header "Content-Type: application/json" \
--data '{
  "name": "Replace internal headers",
  "action": "allow",
  "enabled": true,
  "filters": ["http"],
  "traffic": "any(http.request.domains[*] in {\"internal.example.com\"})",
  "rule_settings": {
    "delete_headers": ["X-Internal-User"],
    "set_headers": {
      "X-Internal-User": ["@{identity.email}"]
    }
  }
}'

You can include custom headers in an HTTP policy to allow your users through Cloudflare WAF. This is useful for allowing only Cloudflare One Client users through your WAF.

1. Create an Allow policy for an internal domain behind your WAF with a custom header.

   Selector	Operator	Value	Action
   Domain	in	internalapp.com	Allow

   Custom header name	Custom header value
   X-Example-Header	example-value

2. In Cloudflare WAF, create a custom rule to require the same HTTP header.

You can configure Browser Isolation to send custom headers. This is useful for implementing tenant control for isolated SaaS applications or sending arbitrary custom request headers to isolated websites.

To use custom headers with Browser Isolation, create two HTTP policies targeting the same domain or application group. For example, you can create policies for HTTPBin ↗, an open-source site for testing HTTP requests:

1. Create an Isolate policy for httpbin.org.

   Selector	Operator	Value	Action
   Domain	in	httpbin.org	Isolate

2. Create an Allow policy for httpbin.org with a custom header.

   Selector	Operator	Value	Action
   Domain	in	httpbin.org	Allow

   Custom header name	Custom header value
   Example-Header	example-value

3. Go to httpbin.org/anything ↗. Cloudflare will render the site in an isolated browser. Your custom header will appear in the list of headers.