Skip to main content

Traffic Policy Actions Reference

TODO: intro

Add Headers​

The Add Headers Traffic Policy action enables you to add headers to an HTTP request before it is sent upstream or an HTTP response before it is sent back to the client.

Configuration Reference​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request, on_http_response

Type​

add-headers

Configuration Fields​

  • headersobjectCEL

    Map of header key to header value to be added.

    Minimum 1, Maximum 10.

    Supports CEL Interpolation in header values.

Behavior​

When configured in the on_http_request phase, this action will add the specified headers to incoming http requests before reaching the upstream server. When configured in the on_http_response phase, the specified headers are added to the http response from the upstream server.

Addition Only​

This action will only add headers to the request or response. If the header already exists it will append another header with the same key unless it is the host header, see Special Cases.

To replace or remove headers use the remove-headers action then add the header with the desired value.

Case Sensitivity​

Header keys added through this action are normalized to lowercase per the HTTP/2 specification.

Ordering​

Since actions are run in the order they are specified, to modify headers that have been added by other actions you must place this action after them in your traffic policy document.

Special Cases​

  • Adding the host header override the existing value instead of appending another header.
  • You may not add or remove the user-agent header.
  • You may not use this action to add the ngrok-skip-browser-warning header to skip the ngrok browser warning on free accounts. For more information, check out the free plan limits guide.

Examples​

Adding headers to an HTTP response​

The following Traffic Policy configuration will add headers to the response from the upstream service when the method is GET and the URL starts with /status/200.

Example Traffic Policy Document​

You can use one of the following snippets:

Policy​

Loading…

Agent Config​

Loading…

For this example, we are assuming that ngrok is pointing at the upstream service https://httpbin.org and we will be adding two headers:

  • x-custom-header with the value my-custom-value
  • x-string-interpolation-example with the value started at ${conn.ts.start} to demonstrate the use of CEL interpolation to include the request connection start time.

Example Request​

Loading…
Loading…

traffic-policy/actions/add-headers/examples/http-add-client-ip-headers-to-all-requests.mdx

Action Result Variables​

  • actions.ngrok.add_headers.headers_addedobject

    Map of headers that were added by the action.

The Basic Auth Traffic Policy action enables you to enforce HTTP Basic Auth on your endpoints. Requests with a valid username and password will be sent to your upstream service, all others will be rejected with a 401 Unauthorized response.

Configuration Reference​

This is the Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request

Type​

basic-auth

Configuration Fields​

  • credentialsarray of stringsRequired

    A list of up to 10 allowed username:password credential pairs.

    Password must be at least 8 characters and no more than 128 characters.

  • realmstring

    The HTTP realm of the request as per RFC 7235.

    Default is ngrok.

  • enforcebool

    Default true. If false, continue to the next action even if basic authentication failed. This is useful for handling fall-through, debugging, and testing purposes.

Behavior​

The basic-auth action enforces HTTP Basic Authentication on incoming requests, as specified in RFC 7235. When a request is received, the action verifies the request by validating against a known set of user:password credentials. If the verification is successful, the action allows the request to continue through the action chain and finally to your application; if verification fails, the request will be terminated with a 401 Unauthorized response.

Additional Restrictions​

You can specify up to 10 username:password pairs. The password must be at least 8 characters and no more than 128 characters. Including multiple colons in the username:password pair will result in the first colon being treated as the delimiter between the username and password. Realm cannot exceed 128 characters, and cannot contain non-ASCII characters.

Verification Process​

  • HTTP Authentication: The action validates incoming HTTP requests to confirm they contain the required Authorization header, in the form of Authorization: Basic <credentials>, where <credentials> is the Base64 encoding of username and password joined by a single colon :.
  • Request Handling: If the authentication is successful, the request is forwarded to the next action. If the authentication fails, it will return to user a 401 response, which will prompt the user to provide a correct set of credentials.
  • Configurable Enforcement: By default, authentication failures result in 401s. However, setting enforce: false allows unauthenticated requests to proceed, while logging the authentication result. This option is for debugging and testing.

Secret Handling and Encryption​

All secrets used for basic authentication are encrypted at config validation. When ngrok processes a request, the secret is decrypted.

Examples​

The following Traffic Policy configuration is an example configuration of the basic-auth action.

Example Traffic Policy Document​

You can use one of the following snippets:

Policy​

Loading…

Agent Config​

Loading…

Example Request​

First, base64 encode the username:password pair. user:password1 becomes dXNlcjpwYXNzd29yZDE=

Loading…
Loading…

In this example, we are sending a request to our API with a valid set of credentials in the Authorization header with the Basic prefix and getting back a 200 OK response.

You can try it without the header, and you will receive a 401 Unauthorized prompt instead.

Action Result Variables​

  • actions.ngrok.basic_auth.credentials.presentedbool

    Whether there were Basic Auth credentials presented in the Authorization header.

  • actions.ngrok.basic_auth.credentials.usernamestring

    The username of the credentials presented.

  • actions.ngrok.basic_auth.credentials.authorizedbool

    Whether the presented basic auth credentials were authorized for this request.

Circuit Breaker​

The Circuit Breaker action helps maintain system reliability by rejecting requests when the error rate and request volume within a rolling window exceed defined thresholds. It pauses traffic temporarily to allow the system to recover and automatically re-evaluates upstream health before resuming.

Configuration Reference​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request

Type​

circuit-breaker

Configuration Fields​

  • error_thresholdfloatRequired

    Threshold percentage of errors that must be met before requests are rejected. Must be a value between 0.0 and 1.0. Defaults to 0.5.

  • volume_thresholdinteger

    Number of requests in a rolling window before checking the error threshold. Must be a number between 1 and 2,000,000,000. Defaults to 10.

  • window_durationduration

    Number of seconds in the rolling window that metrics are retained for. Must be a value between 1s and 2m. Defaults to 10s.

  • tripped_durationduration

    Number of seconds the system waits after rejecting a request before re-evaluating upstream health. Must be a value between 1s and 2m. Defaults to 10s.

  • num_bucketsinteger

    Number of buckets that metrics are divided into within the rolling window. Fixed at 10.

  • enforceboolean

    Determines if the circuit breaker is active. If false, the circuit breaker never trips, and no requests are rejected. Defaults to true.

Examples​

This example configuration sets up an endpoint (hotdog.ngrok.io) that allows only 1 request every 60 seconds and trips the circuit breaker for 2 minutes.

Example Traffic Policy Document​

You can use one of the following snippets:

Policy​

Loading…

Agent Config​

Loading…

Start Endpoint with Traffic Policy​

Loading…

Helper script​

Loading…
Loading…

Action Result Variables​

This action does not set any variables after it has been executed.

Compress Response​

The Compress Response Traffic Policy action enables you to improve the performance of your web applications by compressing HTTP response bodies returned by your upstream service.

Configuration Reference​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request, on_http_response

Type​

compress-response

Configuration Fields​

  • algorithmsarray of strings

    A list of allowed compression algorithms to be considered during encoding type negotiation. Each element must be unique.

    Defaults to gzip, deflate, br, compress.

    • Supported algorithms
    • br
    • compress
    • deflate
    • gzip

Behavior​

When an HTTP request includes an Accept-Encoding header, HTTP responses are automatically compressed, and a Content-Encoding header is added to the response.

If the response is already compressed by your upstream service, no additional compression will be applied.

Streaming Compression​

When compression is applied, the response body is not buffered; it is compressed in real-time as it streams through the ngrok endpoint.

Algorithm Choice​

If a request specifies Accept-Encoding but none of the requested algorithms are supported, no compression is applied, and the upstream response is returned unmodified.

Quality Values​

Compression is negotiated based on the Accept-Encoding header as defined by the RFC, respecting q-values and selecting the supported algorithm with the highest q-value.

For example:

Loading…

The algorithm gzip would be selected because it has the highest q-value of 1.0.

Response Headers​

When this action performs compression, the following changes are made to the HTTP response headers:

  • The Content-Length header is removed.
  • A Content-Encoding header is added, specifying the negotiated algorithm.
  • A Vary: Accept-Encoding header is added to indicate that the response varies based on the Accept-Encoding request header.

Examples​

Compressing API Responses Based on URL Path​

The following Traffic Policy configuration demonstrates how to set this up using the compress-response action with an expression to compress traffic on specific URL paths.

Example Traffic Policy Document​

You can use one of the following snippets:

Policy​

Loading…

Agent Config​

Loading…

For this example, we are assuming that an ngrok agent is pointing at the upstream service https://jsonplaceholder.typicode.com.

Example Request​
Loading…
Loading…

In this example, when a request is made to /api/posts, ngrok compresses the response using one of the specified algorithms (e.g., gzip). The response includes the content-encoding: gzip header, and the body is compressed accordingly.

This setup ensures that only API responses for paths starting with /api/ are compressed, enhancing performance and responsiveness for only those endpoints.

Action Result Variables​

  • actions.ngrok.compress.already_compressedboolean

    Indicates whether the body was already compressed before the action was applied. Returns true if no further compression was performed.

  • actions.ngrok.compress.negotiated_algorithmstring

    The compression algorithm selected and applied by the action, based on the client's request and action configuration.

Custom Response​

The Custom Response Traffic Policy action enables you to return a hard-coded response back to the client that made a request to your endpoint.

Configuration Reference​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request, on_http_response

Type​

custom-response

Configuration Fields​

  • status_codeintegerRequired

    Status code of the custom response being sent back.

  • contentstring

    Body of the custom response being sent back.

    Supports CEL Interpolation.

  • headersobjectCEL

    Map of key-value headers of the custom response to be sent back. If content-type is not included in headers, this action will attempt to infer the correct content-type. Maximum properties 10.

    Supports CEL Interpolation.

Behavior​

If this action is executed, no subsequent actions in your traffic policy will be executed.

on_http_request Usage​

When used during the on_http_request phase, this action bypasses the upstream server and immediately returns the configured response to the caller.

on_http_response Usage​

When used during the on_http_response, this action overwrites the response from the upstream server with the configured response.

Inferring Content-Type​

If the content-type header is not explicitly specified in headers, this action will attempt to infer the correct content-type based on the provided content.

Examples​

Custom HTML Maintenance Page​

The following Traffic Policy configuration demonstrates how to use the custom-response action to return a custom HTML maintenance page back for all requests to your endpoint.

Example Traffic Policy Document​

You can use one of the following snippets:

Policy​

Loading…

Agent Config​

Loading…
Example Request​
Loading…
Loading…

In this example, when a request is made to any page on your endpoint, ngrok returns back the custom HTML maintenance page.

This setup is useful for when you want to temporarily disable your endpoint.

Custom JSON API Response with CEL Interpolation​

The following Traffic Policy configuration demonstrates how to use the custom-response action to return a JSON response with CEL Interpolation for the connection start time.

Example Traffic Policy Document​

You can use one of the following snippets:

Policy​

Loading…

Agent Config​

Loading…
Example Request​
Loading…
Loading…

In this example, when a request is made to /api/example, ngrok returns a custom JSON response with a status code of 200. The response includes a content-type: application/json header and a JSON body that uses CEL Interpolation to show the connection start time using the conn.ts.start variable.

Custom Plaintext Response with Multiple CEL Interpolations​

The following Traffic Policy configuration demonstrates how to use the custom-response action to return a text/plain response with multiple CEL interpolations.

Example Traffic Policy Document​

You can use one of the following snippets:

Policy​

Loading…

Agent Config​

Loading…
Example Request​
Loading…
Loading…

In this example, when a request is made to /api/example, ngrok returns a custom plain text response with a status code of 418. The response includes a content-type: text/plain header and a body that uses multiple string interpolations to show the connection start time and the current time.

Action Result Variables​

This action does not set any variables after it has been executed.

Deny​

The Deny Traffic Policy action enables you to reject incoming requests on your endpoints before they make it to your upstream service.

Configuration Reference​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_tcp_connect, on_http_request

Type​

deny

Configuration Fields​

  • status_codeinteger

    Response status code. Default is 999.

Behavior on_tcp_connect​

When this action is executed, the upstream server is never reached and a response is immediately returned and no further actions or rules in the policy configuration will be executed.

Behavior on_http_request​

When this action is executed, the upstream server is never reached and a response is immediately returned and no further actions or rules in the policy configuration will be executed.

Custom Content​

The deny traffic policy action will not send back a response body to the client. To send back a response body, use the custom-response action.

Examples on_tcp_connect​

Deny all traffic​

The following Traffic Policy configuration will deny all inbound traffic on your endpoint.

Example Traffic Policy Document​

You can use one of the following snippets:

Policy​

Loading…

Agent Config​

Loading…
Example Request​
Loading…

In this example, we attempt to connect to 5.tcp.ngrok.io:22984 using the telnet command and ngrok immediately closes the connection.

Examples on_http_request​

Deny traffic with a 404 status code​

The following Traffic Policy configuration will deny all inbound traffic with a 404 on your endpoint.

Example Traffic Policy Document​

You can use one of the following snippets:

Policy​

Loading…

Agent Config​

Loading…
Example Request​
Loading…
Loading…

In this example, we attempt to connect to example.ngrok.app using the curl command and ngrok immediately closes the connection with a 404 status code.

Action Result Variables​

This action does not set any variables after it has been executed.

Action Variables​

Action variables are made available for use in subsequent expressions and CEL interpolations after an action has run. Variable values will only apply to the last action execution, results are not concatenated.