Skip to main content

Templates

Explore a curated collection of examples and configuration templates 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.

See the following categories for specific expressions and actions:

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.

# snippet
---
on_http_request:
  - expressions: []
    name: "Add JWT authentication and rate limiting"
    actions:
      - type: "rate-limit"
        config:
          name: "Only allow 30 requests per minute"
          algorithm: "sliding_window"
          capacity: 30
          rate: "60s"
          bucket_key:
            - "req.headers['x-api-key']"
      - type: "jwt-validation"
        config:
          issuer:
            allow_list:
              - value: "https://<YOUR-AUTH-PROVIDER>"
          audience:
            allow_list:
              - value: "<YOUR-NGROK-DOMAIN>"
          http:
            tokens:
              - type: "jwt"
                method: "header"
                name: "Authorization"
                prefix: "Bearer "
          jws:
            allowed_algorithms:
              - "RS256"
            keys:
              sources:
                additional_jkus:
                  - "https://<YOUR-AUTH-PROVIDER>/.well-known/jwks.json"
on_http_response: []

Rate limiting​

Rate limit for specific endpoint​

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

# snippet
---
on_http_request:
  - expressions:
      - "req.url.contains('/api/specific_endpoint')"
    actions:
      - type: "rate-limit"
        config:
          name: "Only allow 30 requests per minute"
          algorithm: "sliding_window"
          capacity: 30
          rate: "60s"
          bucket_key:
            - "conn.client_ip"

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.

# snippet
---
on_http_request:
  - expressions:
      - "!('Authorization' in req.headers)"
    name: "Unauthorized rate limiting tier"
    actions:
      - type: "rate-limit"
        config:
          name: "Allow 10 requests per minute"
          algorithm: "sliding_window"
          capacity: 10
          rate: "60s"
          bucket_key:
            - "conn.client_ip"
  - expressions:
      - "('Authorization' in req.headers)"
    name: "Authorized rate limiting tier"
    actions:
      - type: "rate-limit"
        config:
          name: "Allow 100 requests per minute"
          algorithm: "sliding_window"
          capacity: 100
          rate: "60s"
          bucket_key:
            - "conn.client_ip"
on_http_response: []

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.

# snippet
---
on_http_request:
  - expressions:
      - "!('Tier' in req.headers)"
    name: "Free rate limiting tier"
    actions:
      - type: "rate-limit"
        config:
          name: "Allow 10 requests per minute"
          algorithm: "sliding_window"
          capacity: 10
          rate: "60s"
          bucket_key:
            - "conn.client_ip"
  - expressions:
      - "getReqHeader('tier').exists(v, v.matches('(?i)bronze'))"
    name: "Bronze rate limiting tier"
    actions:
      - type: "rate-limit"
        config:
          name: "Allow 100 requests per minute"
          algorithm: "sliding_window"
          capacity: 100
          rate: "60s"
          bucket_key:
            - "conn.client_ip"
  - expressions:
      - "getReqHeader('tier').exists(v, v.matches('(?i)silver'))"
    name: "Bronze rate limiting tier"
    actions:
      - type: "rate-limit"
        config:
          name: "Allow 1000 requests per minute"
          algorithm: "sliding_window"
          capacity: 1000
          rate: "60s"
          bucket_key:
            - "conn.client_ip"
  - expressions:
      - "getReqHeader('tier').exists(v, v.matches('(?i)gold'))"
    name: "Gold rate limiting tier"
    actions:
      - type: "rate-limit"
        config:
          name: "Allow 10000 requests per minute"
          algorithm: "sliding_window"
          capacity: 10000
          rate: "60s"
          bucket_key:
            - "conn.client_ip"
on_http_response: []

Block unwanted requests​

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.

# snippet
---
on_http_request:
  - name: "Add `robots.txt` to deny all bots and crawlers"
    expressions:
      - "req.url.contains('/robots.txt')"
    actions:
      - type: "custom-response"
        config:
          status_code: 200
          content: "User-agent: *\r\nDisallow: /"
          headers:
            content-type: "text/plain"

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

# snippet
---
on_http_request:
  - name: "Add `robots.txt` to deny specific bots and crawlers"
    expressions:
      - "req.url.contains('/robots.txt')"
    actions:
      - type: "custom-response"
        config:
          status_code: 200
          content: "User-agent: ChatGPT-User\\r\\nDisallow: /"
          headers:
            content-type: "text/plain"

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).

# snippet
---
on_http_request:
  - name: "Block specific bots by user agent"
    expressions:
      - "req.user_agent.matches('(?i).*(chatgpt-user|gptbot)/\\\\d+.*')"
    actions:
      - type: "deny"
        config:
          status_code: 404

Deny non-GET requests​

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

# snippet
---
on_http_request:
  - expressions:
      - "req.method != 'GET'"
    actions:
      - type: "deny"

Custom response for unauthorized requests​

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

# snippet
---
on_http_request:
  - expressions:
      - "!('authorization' in req.headers)"
    actions:
      - type: "custom-response"
        config:
          status_code: 401
          content: "Unauthorized"

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.

# snippet
---
on_http_request:
  - expressions:
      - "conn.geo.country_code in ['<COUNTRY-01>', '<COUNTRY-02>']"
    name: "Block traffic from unwanted countries"
    actions:
      - type: "custom-response"
        config:
          status_code: 401
          content: "Unauthorized request due to country of origin"
on_http_response: []

Limit request sizes​

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

# snippet
---
on_http_request:
  - expressions:
      - "req.method == 'POST' || req.method == 'PUT'"
      - "req.content_length >= 1000"
    name: "Block POST/PUT requests of excessive length"
    actions:
      - type: "custom-response"
        config:
          status_code: 400
          content: "Error: content length"
on_http_response: []

Other​

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.

# snippet
---
on_http_request:
  - expressions:
      - "'user-agent' in req.headers"
      - "size(req.headers['user-agent'].filter(x,
        x.matches('(?i).*Edg/\\\\d+.*'))) > 0"
    actions:
      - type: "custom-response"
        config:
          status_code: 200
          content: "Hello Edge User!"

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.

# snippet
---
on_http_request:
  - expressions:
      - "'2' in req.headers['X-Api-Version']"
    name: "Deprecate API v2"
    actions:
      - type: "custom-response"
        config:
          status_code: 400
          content: "{\"error\":{\"message\":\"Version 2 of the API is no longer supported.
            Use Version 3 instead.\"}}"
on_http_response: []

Manipulate request headers​

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.

# snippet
---
on_http_request:
  - expressions: []
    name: "Add headers to requests"
    actions:
      - type: "add-headers"
        config:
          headers:
            is-ngrok: "1"
            country: "${.ngrok.geo.country_code}"
on_http_response: []

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.

# snippet
---
on_http_request: []
on_http_response:
  - expressions: []
    name: "Add compression"
    actions:
      - type: "compress-response"
        config:
          algorithms:
            - "gzip"
            - "br"
            - "deflate"
            - "compress"

Enforce TLS version​

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

# snippet
---
on_http_request:
  - expressions:
      - "conn.tls.version < '1.3'"
    name: "Reject requests using old TLS versions"
    actions:
      - type: "custom-response"
        config:
          status_code: 401
          content: "Unauthorized: TLS version too old"
on_http_response: []

Log unsuccessful events​

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

# snippet
---
on_http_request: []
on_http_response:
  - expressions:
      - "res.status_code < '200' && res.status_code >= '300'"
    name: "Log unsuccessful requests"
    actions:
      - type: "log"
        config:
          metadata:
            message: "Unsuccessful request"
            edge_id: "<YOUR-NGROK-DOMAIN>"
            success: false