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.
IP whitelisting is optional. If no IP addresses are configured on a key, all IPs are allowed — the key works exactly as before.
How it works
When you add IP addresses to an API key’s allowlist:
- Every request using that key is checked against the allowlist
- If the request IP matches any entry, the request proceeds normally
- 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:
- Go to Settings > Developer
- Click Create API Key
- Fill in the name, description, and scopes
- In the IP Allowlist section, click Add IP
- Enter an IP address or CIDR range and an optional label
- Click Create
On an existing key
To add or modify IP restrictions on an active key:
- Go to Settings > Developer
- Find the key in the API Keys list
- Click the menu (three dots) and select IP Allowlist
- Add, edit, or remove entries
- Click Save
Changes take effect within 10 seconds. Make sure your server IPs are correct before saving — incorrect entries will block your own requests.
| 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) |
Each entry can have an optional label (e.g. “Office network”, “CI/CD server”) to help you identify what each IP is for.
Error response
When a request comes from an IP not in the allowlist:
{
"error": {
"code": "IP_NOT_ALLOWED",
"message": "Request IP address is not in the API key's allowlist"
}
}
403.
Common scenarios
Restrict to a single server
If your API calls always come from one server, add its public IP:
Restrict to an office network
If your team’s office uses a NAT gateway, add the gateway’s public IP or subnet:
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)
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.
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 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
