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

# IP Whitelisting

> Restrict API key usage to specific IP addresses or CIDR ranges

## Overview

IP whitelisting lets you restrict an API key so it can only be used from specific IP addresses or network ranges. Requests from any other IP are rejected with a `403` error.

This is especially useful for enterprise environments where API traffic should only originate from known servers, VPNs, or office networks.

<Tip>
  IP whitelisting is optional. If no IP addresses are configured on a key, all IPs are allowed — the key works exactly as before.
</Tip>

## How it works

When you add IP addresses to an API key's allowlist:

1. Every request using that key is checked against the allowlist
2. If the request IP matches any entry, the request proceeds normally
3. If the request IP does not match, the API returns `403 IP_NOT_ALLOWED`

The check happens after authentication and scope validation, so an invalid key still returns `401` — not `403`.

## Setting up IP whitelisting

### During key creation

You can configure IP restrictions when creating a new API key:

1. Go to **Settings > Developer**
2. Click **Create API Key**
3. Fill in the name, description, and scopes
4. In the **IP Allowlist** section, click **Add IP**
5. Enter an IP address or CIDR range and an optional label
6. Click **Create**

### On an existing key

To add or modify IP restrictions on an active key:

1. Go to **Settings > Developer**
2. Find the key in the API Keys list
3. Click the menu (three dots) and select **IP Allowlist**
4. Add, edit, or remove entries
5. Click **Save**

<Warning>
  Changes take effect within 10 seconds. Make sure your server IPs are correct before saving — incorrect entries will block your own requests.
</Warning>

## Supported formats

Entries can be individual IP addresses or CIDR ranges:

| Format      | Example          | What it matches                                 |
| ----------- | ---------------- | ----------------------------------------------- |
| Single IPv4 | `203.0.113.5`    | Exactly one address (stored as `/32`)           |
| IPv4 CIDR   | `203.0.113.0/24` | 256 addresses (`203.0.113.0` – `203.0.113.255`) |
| Single IPv6 | `2001:db8::1`    | Exactly one address (stored as `/128`)          |
| IPv6 CIDR   | `2001:db8::/48`  | A subnet of IPv6 addresses                      |

### Limits

| Constraint          | Value                                         |
| ------------------- | --------------------------------------------- |
| Max entries per key | 20                                            |
| Minimum IPv4 prefix | `/9` (ranges broader than this are rejected)  |
| Minimum IPv6 prefix | `/33` (ranges broader than this are rejected) |

<Tip>
  Each entry can have an optional label (e.g. "Office network", "CI/CD server") to help you identify what each IP is for.
</Tip>

## Error response

When a request comes from an IP not in the allowlist:

```json theme={null}
{
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Request IP address is not in the API key's allowlist"
  }
}
```

The response status code is `403`.

## Common scenarios

### Restrict to a single server

If your API calls always come from one server, add its public IP:

```
203.0.113.10
```

### Restrict to an office network

If your team's office uses a NAT gateway, add the gateway's public IP or subnet:

```
198.51.100.0/24
```

### Restrict to a cloud provider subnet

If your application runs on AWS, GCP, or Azure, add the NAT gateway or egress IP range for your VPC:

```
10.0.0.0 is NOT valid — use your public egress IP
35.192.0.0/12 (example GCP range)
```

<Warning>
  Private IP ranges like `10.x.x.x`, `172.16.x.x`, or `192.168.x.x` won't match because the API sees your public IP. Use the public IP of your NAT gateway or load balancer.
</Warning>

## Best practices

* **Start without restrictions** — test your integration first, then add IP restrictions once everything works
* **Use CIDR ranges for dynamic environments** — if your servers get new IPs on deploy (e.g. Kubernetes, serverless), use a CIDR range covering your egress IPs
* **Label your entries** — use descriptive labels so your team knows why each entry exists
* **Keep a backup key** — consider having a second API key without IP restrictions stored securely for emergency access
* **Monitor blocked requests** — blocked attempts are logged in the [API Usage Logs](#api-usage-logs) section of the Developer settings

## API usage logs

All API requests — including blocked ones — are logged and visible in **Settings > Developer > API Usage Logs**. You can filter by API key, HTTP method, and status code, and export logs as CSV.

This helps you:

* Verify that your server IPs are being recognized correctly
* Identify unauthorized access attempts
* Debug IP-related issues when setting up whitelisting