Skip to main content

Traffic Policy Examples

Explore a curated collection of examples and configuration examples spanning from common to unconventional use cases for the Traffic Policy module.

A number of these examples come from a longer article about how ngrok makes policy management accessible to developers, including a simple Go-based application for testing these and other configurations.

Route requests​

Forward to an internal endpoints based on request attributes​

You can use CEL interpolation to dynamically forward requests to different internal endpoints based on URL, hostname, path, headers, and more. This allows you to manage complex traffic topologies without manually creating and managing each forward-internal action.

Forward requests from https://*.example.com to https://<SUBDOMAIN>.internal.

Loading…

Forward requsets containing a X-Customer-Value: {CUSTOMER} header to https://{CUSTOMER}.internal.

Loading…

Add authentication​

Add JWT authentication and key-based rate limiting​

Building from our Auth0 guide, these rules also add rate limiting based on your consumers' JWTs.

Loading…

Conditional Access to a page using oauth variables​

Loading…

Capturing and sending identity token over a header​

Loading…

Rate limit requests​

Rate limit for specific endpoint​

This rule applies rate limiting of 30 requests per second to the endpoint /api/videos.

Loading…

Rate limit API consumers based on authentication status​

Create a low rate limit for unauthenticated (likely free) users, while allowing authenticated users a higher level of capacity.

Loading…

Rate limit API consumers based on pricing tiers​

Using a naming scheme in your upstream servers, and API calls using a tier header, you can quickly customize access to your API based on any number of pricing tiers.

Loading…

Block unwanted requests​

Deny traffic from Tor networks​

Use connection variables available in IP Intelligence to block Tor exit node IPs.

Loading…

Disallow bots and crawlers with a robots.txt​

This rule returns a custom response with a robots.txt file to deny search engine or AI crawlers on all paths.

Loading…

You can also extend the expression above to create specific rules for crawlers based on their user agent strings, like ChatGPT-User and GPTBot.

Loading…

Block bots and crawlers by user agent​

In addition to, or instead of, denying bots and crawlers with a robots.txt file, you can also take action on only incoming requests that contain specific strings in the req.user_agent request variable.

You can extend the expression to include additional user agents by extending (chatgpt-user|gptbot) like so: (chatgpt-user|gptbot|anthropic|claude|any|other|user-agent|goes|here).

Loading…

Deny non-GET requests​

This rule denies all inbound traffic that is not a GET request.

Loading…

Custom response for unauthorized requests​

This rule sends a custom response with status code 401 and body Unauthorized for requests without an Authorization header.

Loading…

Block traffic from specific countries​

Remain compliant with data regulations or sanctions by blocking requests originating from one or more countries using their respective ISO country codes.

Loading…

Limit request sizes​

Prevent excessively large user uploads, like text or images, that might cause performance or availability issues for your upstream service.

Loading…

Manipulate headers​

Enrich your upstream service​

Add new headers to requests to give your upstream service more context about the consumer, which in turn allows for richer functionality, such as localized languages and pricing.

Loading…

Remove service details from response headers​

Some frameworks, like Express, add headers like X-Powered-By: Express to responses, which you may not want to reveal to your users.

The following example removes the X-Powered-By header.

Loading…

Other​

Deploy simple A/B tests​

Using the rand.double() macro set to >= 0.5, you can equally split incoming requests to two different internal agent endpoints, which forward traffic to the two versions of your service.

You can manipulate <= 0.5 to match the percentage of requests to route to your B test, e.g. <= 0.1 for 10%.

Loading…

If you don't have multiple services, you could also route B traffic to a separate route.

Loading…

Create 'pretty' URLs for SEO​

You can map the permalinks created by a blog CMS to "pretty" alternatives that are easier for both humans and SEO bots to understand.

The following rule rewrites the a user-friendly URL like /blog/11/example-title to /blog/index.php?p=11&title=example-title, which is readable by your CMS.

Loading…

User agent filtering​

We deliver tailored content to Microsoft Edge users by examining the User-Agent header for the case-insensitive string (?i)edg/ succeeded by digits \d. To see how this works in practice, explore the following regex101 demonstration.

To ensure correct decoding from YAML/JSON, it's necessary to properly escape the \d sequence. In YAML, if your string is not enclosed in quotes, use a single escape: \\d. However, when your string is wrapped in quotes, either in YAML or JSON, you need to double-escape: \\\\d for accurate decoding.

Loading…

Deprecate an API version​

By include a X-Api-Version header in your API reference or developer documentation, you can quickly return a helpful error message, which encourages them to explore usage of the new version.

Loading…

Manipulate request headers​

Add compression​

Quickly ensure all JSON responses are compressed en route to your API consumer. If your upstream service already handles compression, ngrok skips this step.

Loading…

Enforce TLS version​

Prevent obsolete and potentially vulnerable browsers, SDKs, or CLI tools like curl from attempting to access your API.

Loading…

Log unsuccessful events​

Connect your API to ngrok's event logging system for smarter troubleshooting of your API gateway and upstream services.

Loading…