Skip to main content
IP Policies are reusable groups of rules for allowing or denying traffic and ngrok dashboard access from specific IPs and CIDRs. Each IP Policy contains one or more rules that specify an IP or CIDR range and whether to allow or deny traffic from that range. You can manage IP Policies in the ngrok dashboard or via the IP Policies API.

​
Creating and managing IP Policies

​
In the dashboard

  1. Go to Security, then IP Policies in the ngrok dashboard.
  2. Click New IP Policy to create a policy.
  3. Add rules to your policy by specifying a CIDR range (such as 203.0.113.0/24) and choosing allow or deny.
  4. Save your policy. You’ll get a policy ID (for example, ipp_...) that you can reference in your Traffic Policy.

​
Via the API

You can also create and manage IP Policies using the ngrok API. Refer to the IP Policy Rules API to add or remove rules from existing policies.

​
Applying IP Policies to Endpoints

To enforce an IP Policy on your endpoints, use the restrict-ips Traffic Policy action. This action lets you reference one or more IP Policy IDs, and ngrok will allow or deny traffic based on the rules in those policies. There are two ways to apply a Traffic Policy to an Agent Endpoint:
  • Standalone policy file: Create a separate policy.yml or policy.json file and pass it to ngrok with the --traffic-policy-file flag. The policy phases (such as on_http_request) are at the top level of the file.
  • Agent config file: Define the policy inline inside your ngrok agent config file (for example, ngrok.yml). In this case, the policy phases must be nested under the traffic_policy: key inside the endpoint configuration.
When embedding a Traffic Policy in your agent config file, the on_http_request (and other phase) blocks must be placed under traffic_policy: inside the endpoint definition—not at the top level of the config file.

​
Using a standalone policy file

Create a policy.yml or policy.json file with the following contents:
Then start your Agent Endpoint using the --traffic-policy-file flag:

​
Using the agent config file

To embed the same policy in your ngrok agent config file, nest the policy block under traffic_policy: inside the endpoint definition:
ngrok.yml

​
Using a Cloud Endpoint

To use a Cloud Endpoint, visit the Endpoints section in the ngrok dashboard and select the Cloud Endpoint. You’ll be taken to the Traffic Policy editor where you can enter the policy directly. The editor uses the standalone policy format. Enter the phase blocks (such as on_http_request) at the top level:
Save your changes in the dashboard when done.

​
Referencing an existing IP Policy by ID

You can also reference an existing IP Policy by its ID instead of listing CIDRs directly:
The same placement rules apply: use the top-level format in a standalone policy file or in the Cloud Endpoint editor, and nest under traffic_policy: when using the agent config file. For a full reference of all configuration options, behavior, and examples for the restrict-ips action, see the Restrict IPs action reference.

​
Applying account-wide IP Policies

To apply account-wide IP Policies, you can use the IP Restrictions feature in the ngrok dashboard. In the dashboard UI, you can apply IP Restrictions to users trying to sign in to your ngrok dashboard, traffic trying to access your API or Endpoints, and source IPs trying to start Agent Endpoints on your account. You can define the IP Policies that make up your restrictions in the dashboard UI.