Skip to main content
Region & IP resolution lets you restrict (or “pin”) which ngrok regions will handle traffic for a domain. Configure your domain to resolve to the IP addresses of one (or several) of ngrok’s globally distributed physical points of presence (PoPs). This feature is designed for customers with data residency and compliance requirements who need to ensure traffic is processed only within specific geographic boundaries.
The same configuration will soon support dedicated IP addresses [preview feature], in addition to Points of Presence.

​
How it works

  1. Choose which ngrok points of presence your domain can use.
  2. All requests to endpoints on that domain will only be routed through your chosen PoPs.
Region Pinning diagram -- how it works

​
Configuring region resolution

To configure (or “pin”) which regions will resolve your traffic: update your domain resource with your preferred set of target regions. You can do this through the API or the dashboard, both of which are described below.

​
Using the API

The resolves_to property tells your domain how to resolve requests. You can specify a list of ngrok physical PoPs (like “Frankfurt” or “California”), dedicated IPs, or both. The following sections describe how to create, update, and un-pin a domain.

​
Create a pinned domain

You can create a new domain and customize region “pinning” (Region Resolution) in a single step. Use the POST /reserved_domains endpoint and include the optional resolves_to property. 
curl --request POST \
 --url https://api.ngrok.com/reserved_domains \
 --header "Authorization: Bearer <token>" \
 --header "Content-Type: application/json" \
 --header "ngrok-version: 2" \
 --data '{
    "domain": "api.example.com",
    "description": "Pinned to US and Europe for compliance reasons",
    "certificate_management_policy": {
      "authority": "letsencrypt",
      "private_key_type": "ecdsa"
    },
    "resolves_to": [
      { "value": "us-cal-1"},  
      { "value": "eu"}
    ]
  }'

​
Update an existing domain

You can add Region Resolution settings to an existing domain. You can also modify the existing list, for example, by adding a third point of presence (example below). No DNS changes are required. Use PATCH to update the list of pinned regions. 
curl --request PATCH \
 --url https://api.ngrok.com/reserved_domains/{domain_id} \
 --header "Authorization: Bearer <token>" \
 --header "Content-Type: application/json" \
 --header "ngrok-version: 2" \
 --data '{
    "domain": "api.example.com",
    "description": "Pinned to US and Europe for compliance reasons",
    "certificate_management_policy": {
      "authority": "letsencrypt",
      "private_key_type": "ecdsa"
    },
    "resolves_to": [
      { "value": "us-cal-1"},  
      { "value": "eu"},
      { "value": "jp"}
    ]
  }'

​
Un-pin a domain

You can “un-pin” a domain. Removing Regional Resolution settings restores the domain to its default IP resolution behavior: global load balancing across all ngrok points of presence. Use PATCH to remove the list of pinned regions, by setting the resolves_to property to an empty list. 
# Revert to Global Routing
curl --request PATCH \
 --url https://api.ngrok.com/reserved_domains/{id}  \
 --header "Authorization: Bearer <token>" \
 --header "Content-Type: application/json" \
 --header "ngrok-version: 2" \
 --data '{
   "resolves_to": [] 
 }'

​
API error handling

If a request contains invalid syntax or an invalid region code, the API request fails. The request returns HTTP 400 Bad Request with a structured error body, as shown in the example below: 
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
 "status_code": 400,
 "error_code": "invalid_region_target",
 "msg": "The region you specified, 'banana' is invalid. use one of the following acceptable values: us,us-cal-1,eu,au,ap,jp,sa,in",
 "details": {}
}

​
Using the dashboard

You can also make these changes through the ngrok dashboard. To configure your Region Resolution targets:
  1. View your existing domains in the dashboard, or create a new one.
  2. Click the domain you wish to modify.
  3. Enter a comma-separated list of PoPs, region aliases that cover multiple PoPs, or both.

​
Dedicated IPs (preview)

This feature is under active development. Behavior, supported fields, and limits may change before General Availability (GA). This guide provides forward-looking context for evaluation and feedback.Visit your dashboard to sign up for Early Access, or to send your feedback via the “Let us know” link.
Dedicated IPs let you configure a domain to receive traffic on static IP addresses that are exclusively dedicated to your account. Today, customers share ngrok’s default range of multi-tenant IP addresses. When a domain uses dedicated IPs, you can create matching endpoints on any inbound port. Today, you are restricted to ports 80 and 443.

​
How to use dedicated IPs

Dedicated IPs and Regional Resolution (“region pinning”) share the same resolves_to field on the domain:
  • Region pinning: resolves_to: [{ "value": "<region-shortcode>" }]
  • Dedicated IPs: resolves_to: [{ "value": "<ip-address>" }]
You can include both, as shown in the example below. 
{
  "resolves_to": [
    { "value": "us-cal-1" },
    { "value": "8.8.8.8:1234" }
  ]
}

​
Frequently asked questions

​
Does this affect TCP endpoints?

Slightly different answer for each sub-feature:
  • Region pinning: no, since this feature applies only to matching HTTP/HTTPS endpoints. TCP uses reserved addresses, which already include a region.
  • Dedicated IPs: yes, dedicated IPs are available for any ngrok-supported protocol, including HTTP/S, TCP, and TLS.

​
What happens if the resolves_to field isn’t added when creating a domain?

Nothing. That is, it uses the standard domain behavior: global load balancing, which automatically routes traffic to the best point of presence for that end-user. This is the baseline behavior for domains, and is used by the vast majority of customers.

​
Is it necessary to specify every region manually?

No, ngrok provides regional aliases as a shortcut to select all PoPs in a given geographic area. Aliases are in Preview (see list below). Initial regions will include european-union and united-states, depending on customer feedback (click “Let us know”).

​
Points of presence reference

The resolves_to parameter uses the following PoP names:
Geographical regionLocationCode (to use in API)
United StatesOhious
Californiaus-cal-1
EuropeFrankfurteu
Asia/PacificSingaporeap
Sydneyau
Mumbaiin
Tokyojp
South AmericaSão Paulosa
Regional AliasesGlobalglobal
Europe [coming soon]european-union
United States [coming soon]united-states