> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# IP Policies
> Use rules to allow or deny traffic and dashboard access from specific IPs and CIDRs.
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](https://dashboard.ngrok.com/ip-policies) or via the [IP Policies API](/docs/api-reference/ippolicies/list).
## Creating and managing IP Policies
### In the dashboard
1. Go to [**Security**, then **IP Policies**](https://dashboard.ngrok.com/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](/docs/api-reference/ippolicies/list).
Refer to the [IP Policy Rules API](/docs/api-reference/ippolicyrules/list) 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`](/docs/gateway/traffic-policy/actions/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](/docs/gateway/agent/config/v3) (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:
```yaml policy.yml theme={null}
on_http_request:
# Only allow requests from trusted IPs
- actions:
- type: restrict-ips
config:
enforce: true
allow:
- 203.0.113.0/24
- 198.51.100.42/32
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "restrict-ips",
"config": {
"enforce": true,
"allow": [
"203.0.113.0/24",
"198.51.100.42/32"
]
}
}
]
}
]
}
```
Then start your Agent Endpoint using the `--traffic-policy-file` flag:
```bash theme={null}
ngrok http $YOUR_PORT --url $YOUR_DOMAIN --traffic-policy-file /path/to/policy.yml
```
### Using the agent config file
To embed the same policy in your [ngrok agent config file](/docs/gateway/agent/config/v3), nest the policy block under `traffic_policy:` inside the endpoint definition:
```yaml ngrok.yml theme={null}
endpoints:
- name: my-endpoint
url: https://example.ngrok.app
upstream:
url: 8080
traffic_policy:
on_http_request:
# Only allow requests from trusted IPs
- actions:
- type: restrict-ips
config:
enforce: true
allow:
- 203.0.113.0/24
- 198.51.100.42/32
```
### Using a Cloud Endpoint
To use a Cloud Endpoint, [visit the **Endpoints** section in the ngrok dashboard](https://dashboard.ngrok.com/endpoints) 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:
```yaml theme={null}
on_http_request:
# Only allow requests from trusted IPs
- actions:
- type: restrict-ips
config:
enforce: true
allow:
- 203.0.113.0/24
- 198.51.100.42/32
```
Save your changes in the dashboard when done.
### Referencing an existing IP Policy by ID
You can also reference an existing [IP Policy](/docs/api-reference/ippolicies/list) by its ID instead of listing CIDRs directly:
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: restrict-ips
config:
enforce: true
ip_policies:
- ipp_1yjqdrIBwgciY2I9zH2EelgBbJF
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "restrict-ips",
"config": {
"enforce": true,
"ip_policies": [
"ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"
]
}
}
]
}
]
}
```
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](/docs/gateway/traffic-policy/actions/restrict-ips).
## Applying account-wide IP Policies
To apply account-wide IP Policies, you can use [the **IP Restrictions** feature in the ngrok dashboard](https://dashboard.ngrok.com/ip-restrictions).
In the dashboard UI, you can apply [IP Restrictions](/docs/gateway/traffic-policy/examples/add-authentication#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.
## Related resources
* [Restrict IPs Traffic Policy action](/docs/gateway/traffic-policy/actions/restrict-ips): Full reference for the `restrict-ips` action, including all configuration options and examples.
* [IP Policies API reference](/docs/api-reference/ippolicies/list): Manage IP Policies programmatically via the ngrok API.
* [IP Policy Rules API reference](/docs/api-reference/ippolicyrules/list): Add or remove rules from your IP Policies via the ngrok API.