Skip to main content

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.

​
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:
  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
Changes take effect within 10 seconds. Make sure your server IPs are correct before saving — incorrect entries will block your own requests.

​
Supported formats

Entries can be individual IP addresses or CIDR ranges:
FormatExampleWhat it matches
Single IPv4203.0.113.5Exactly one address (stored as /32)
IPv4 CIDR203.0.113.0/24256 addresses (203.0.113.0 – 203.0.113.255)
Single IPv62001:db8::1Exactly one address (stored as /128)
IPv6 CIDR2001:db8::/48A subnet of IPv6 addresses

​
Limits

ConstraintValue
Max entries per key20
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"
  }
}
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)
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