> ## Documentation Index
> Fetch the complete documentation index at: https://s2.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Network Policies

> Network policies restrict which networks an access token can be used from, by source CIDR block or AWS VPC endpoint.

A network policy is an allow-list of networks. Attach one to an [access token](https://s2.dev/docs/concepts/access-tokens.md) when issuing it, and S2 rejects any request made with that token from outside those networks.

A token without a network policy can be used from any network.

You can manage network policies from the dashboard or through the API:

> [card] [Dashboard](https://s2.dev/dashboard/access-tokens/network-policies)
>
> Create and delete policies under **Access Tokens → Network Policies**, and pick one when issuing a token.

> [card] API
>
> &#x20;[`GET /network-policies`](https://s2.dev/docs/api/network-policies/list)
>
> &#x20;[`POST /network-policies`](https://s2.dev/docs/api/network-policies/create)
>
> &#x20;[`GET /network-policies/{id}`](https://s2.dev/docs/api/network-policies/get)
>
> &#x20;[`DELETE /network-policies/{id}`](https://s2.dev/docs/api/network-policies/delete)

The [CLI](https://s2.dev/docs/cli/network-policies.md) supports them too.

## Rules

A policy only allows; there are no deny rules. It has a rule for each path a request can take to S2:

| Rule | Path | Matches |
| - | - | - |
| `public_net.cidrs` | Public internet | Source IP address |
| `private_net.aws.vpce_ids` | [AWS PrivateLink](https://s2.dev/docs/platform/private-networking.md) | VPC endpoint ID |

A request is accepted if it matches any entry of the rule for its path. For example, this policy accepts requests from either CIDR block, and from the VPC endpoint:

```json theme={null}
{
  "public_net": { "cidrs": ["203.0.113.0/24", "2001:db8:1234::/48"] },
  "private_net": { "aws": { "vpce_ids": ["vpce-0a1b2c3d4e5f67890"] } }
}
```

A path without a rule is closed. A policy with only `public_net` denies all PrivateLink requests, and one with only `private_net` denies all requests over the public internet.

> [!NOTE]
>
> The source address of a PrivateLink request is not checked, so CIDR blocks of private addresses (like `10.0.0.0/8`) do not allow PrivateLink traffic. Allow the VPC endpoint ID instead.

> [!WARNING]
>
> Account requests, such as listing basins or issuing tokens, go to `a.s2.dev` over the public internet by default, even from a VPC with a PrivateLink endpoint.
>
> A token with only `private_net` rules is denied for those. To allow them, [send account requests over PrivateLink](https://s2.dev/docs/platform/private-networking.md#account-requests-over-privatelink) too, or add `public_net` CIDRs for your egress addresses.

> [!TIP]
>
> CIDR blocks can be IPv4 or IPv6. If your clients use dual-stack networking, they may connect over either, so include both their IPv4 and IPv6 ranges.

A policy can have up to 32 CIDR blocks and 32 VPC endpoint IDs.

## Properties

### Slug

A name unique to the account, of up to 96 letters, digits, `-` and `_`.

### Reference

Each policy also gets a random nonce at creation. Its full reference is `<slug>.<nonce>`, and that is what a token is bound to. Requests that name a policy accept either the slug or the full reference.

### Immutability

Policies cannot be changed. To allow different networks, create a new policy and issue tokens with it.

## Access tokens

Choose a policy with `network_policy` when [issuing](https://s2.dev/docs/api/access-tokens/issue.md) a token. Token info reports the policy's full reference and omits `network_policy` for an unrestricted token.

A token with a network policy can only issue tokens bound to that same policy. The new token gets the policy whether or not the request sets `network_policy`. Naming any other policy, even a narrower one, is rejected.

## Deletion

A policy cannot be deleted while an access token is bound to it. Such a request fails with `network_policy_in_use` (`409`); [revoke](https://s2.dev/docs/api/access-tokens/revoke.md) those tokens first.

## Denied requests

A request that a token's network policy does not allow fails with `403` and the `network_policy_denied` [error code](https://s2.dev/docs/api/error-codes.md). The message names the address S2 saw the request come from:

```json theme={null}
{
  "code": "network_policy_denied",
  "message": "Request from 198.51.100.7 is not permitted by the token's network policy"
}
```

A PrivateLink request also names the VPC endpoint:

```json theme={null}
{
  "code": "network_policy_denied",
  "message": "Request from 10.0.1.23 through vpce-0a1b2c3d4e5f67890 is not permitted by the token's network policy"
}
```

> [!TIP]
>
> A dual-stack client may not know whether it connected over IPv4 or IPv6. The address in the message tells you which one to allow.

## Token activity

The [`token-activity`](https://s2.dev/docs/api/metrics/account#token-activity) metric set shows where each access token was recently used from, with separate records for accepted and denied requests. Each record has the source address, the VPC endpoint for PrivateLink requests, the user agent and, for a denial, the reason, such as `network_policy_denied`. Records can lag by a couple of minutes.

It is useful for building a policy from the addresses a token is already used from, and for finding what a policy is blocking. You can see it:

* In the dashboard, in the **Last Seen** column of the [access tokens](https://s2.dev/dashboard/access-tokens) table.
* With the CLI: `s2 metrics account token-activity my-token`. See [token activity](https://s2.dev/docs/cli/metrics.md#access-token-activity).
* Through the [metrics API](https://s2.dev/docs/api/metrics/account.md#token-activity).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.