Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Header manipulation is a core feature of API Gateways that allows you to modify HTTP headers on incoming requests and outgoing responses. This enables better security, routing, debugging, and interoperability between services. By adding, modifying, or removing headers, you can: 🛠 Enrich requests with additional metadata before they reach your backend.
🔒 Enhance security by stripping sensitive headers from responses.
🚀 Enable service compatibility by adjusting headers for different upstream APIs.

​
🔍 What are the benefits of modifying headers?

Headers contain critical metadata that helps control authentication, caching, routing, security, and debugging. Modifying headers at the gateway level ensures consistency without requiring upstream service changes. Key Benefits:
  • Modify Requests at the Edge: Adjust headers before requests reach your services.
  • Ensure API Compatibility: Add or modify headers to meet the expectations of different backends.
  • Improve Security & Privacy: Strip unnecessary or sensitive headers from responses.
  • Simplify Authentication & Tracing: Add authentication tokens or tracking headers for better monitoring.
  • Reduce Backend Overhead: Offload header transformations from your application code.
  • Enhancing Security: Remove headers like Server to hide backend details from attackers.
  • Injecting Authentication Headers: Add Authorization headers for SSO, API tokens, or identity providers.
  • Adding Debugging & Tracing Information: Inject X-Request-ID or Trace-Id headers for observability and monitoring.

​
Header manipulation examples

​
Adding request headers

The following examples will add the X-Request-Header: my-custom-value header to requests before they are forwarded to the upstream.
Check out the add headers and remove headers Traffic Policy action pages for more details about how they function and the parameters they accept.
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
  name: example-agent-endpoint
spec:
  url: https://example-hostname.ngrok.io
  upstream:
    url: http://my-service.my-namespace:8080
  trafficPolicy:
    inline:
      on_http_request:
          actions:
            - type: add-headers
              config:
                headers:
                  X-Request-Header: my-custom-value

​
Adding response headers

The following examples will add the X-Response-Header: my-custom-value header to responses before they are sent to the clients.
Check out the add headers and remove headers Traffic Policy action pages for more details about how they function and the parameters they accept.
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
  name: example-agent-endpoint
spec:
  url: https://example-hostname.ngrok.io
  upstream:
    url: http://my-service.my-namespace:8080
  trafficPolicy:
    inline:
      on_http_response:
          actions:
            - type: add-headers
              config:
                headers:
                  X-Response-Header: my-custom-value

​
Removing request headers

The following examples will remove the X-Trace-Id header from requests before they are forwarded to the upstream if the header is present.
Check out the add headers and remove headers Traffic Policy action pages for more details about how they function and the parameters they accept.
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
  name: example-agent-endpoint
spec:
  url: https://example-hostname.ngrok.io
  upstream:
    url: http://my-service.my-namespace:8080
  trafficPolicy:
    inline:
      on_http_request:
          actions:
            - type: remove-headers
              config:
                headers:
                  - X-Trace-Id

​
Removing response headers

The following examples will remove the Server header from responses before they are sent to the clients if the header is present.
Check out the add headers and remove headers Traffic Policy action pages for more details about how they function and the parameters they accept.
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
  name: example-agent-endpoint
spec:
  url: https://example-hostname.ngrok.io
  upstream:
    url: http://my-service.my-namespace:8080
  trafficPolicy:
    inline:
      on_http_response:
          actions:
            - type: remove-headers
              config:
                headers:
                  - Server