IP Allowlist

Each API key can have its own IP allowlist, so only requests from the specified source IPs can use that key.

When to use it

This is best for production services running on servers with a fixed egress IP. If your application runs from a home network, mobile network, or another changing address, confirm that its egress IP is stable first; otherwise you may lock yourself out.

How to set it up

Go to /keys and open the key’s “…” menu. Choose “IP Allowlist”, enter the entries, and save.

You can also use PATCH /api/v1/keys/:id with a signed-in session or a Management API key:

1
2
3
4
5
6
7
8
9
10
11
12
13
PATCH https://api.bazaarlink.ai/v1/keys/KEY_ID
Authorization: Bearer sk-bl-YOUR_MANAGEMENT_KEY
Content-Type: application/json

{
"allowedCidrs": [
  "203.0.113.7",
  "198.51.100.0/24"
]
}

# Clear the allowlist and return to unrestricted access
{"allowedCidrs": []}

Entry format

Enter one value per line in the UI. In the API, put the same values in the `allowedCidrs` array. Accepted values are a bare IPv4 address, an IPv4 CIDR, or an IPv6 literal (exact match only).

1
2
3
203.0.113.7
198.51.100.0/24
2001:db8::1

Behavior

Leave it empty (send an empty [] array) to allow all source IPs. This is the default, so existing keys keep working as before.

The source IP is read from the `cf-connecting-ip` header.

If the list is non-empty but the source IP cannot be resolved, the request is rejected (fail-closed).

⚠️ Important: rejected requests return a generic 401

A request from outside the list—or one whose source IP cannot be resolved—returns exactly the same generic HTTP 401 as an invalid key, with no dedicated error message. This is intentional security design so someone who obtained the key cannot learn that an allowlist exists. The trade-off is that a misconfigured list looks exactly like an invalid key and is very difficult to debug. Before saving, confirm that your server’s egress IP is already in the list.

⚠️ Important: IPv6 uses exact string matching only

IPv6 does not support subnet calculation; the address must match the string exactly. If your IPv6 address changes, you can be locked out. IPv4 supports /0–/32 CIDR ranges.

When changes take effect

After PATCH or UI save succeeds, the updating instance clears its cache immediately. Under normal conditions, other instances synchronize within about 15 seconds at most. If shared Redis is temporarily unavailable, cross-instance invalidation cannot propagate immediately and may fall back to the one-hour cache TTL.