How to allowlist IP addresses for an API key
You can limit an API key so it only works from IP addresses you trust. Requests from any other address are rejected, even if the key itself is valid.
Add IP addresses to an API key
- Go to Settings → Machine users and open the machine user that owns the key.
- Open the API key you want to restrict.
- In the IP allowlist card, select Add range.
- Enter an IP address or a CIDR range, then select Add range again (or press Enter). To add several at once, separate them with commas or spaces.
- Select Save, then confirm with Save allowlist.
The change takes about a minute to apply.
What you can enter
- IPv4 or IPv6 addresses, for example
8.8.4.0/24or2606:4700::/32. - A single address without a prefix length. Plain saves it as one address range (
/32for IPv4,/128for IPv6). - Up to 100 ranges per API key.
Use the public IP address your servers connect from. Plain rejects private, loopback, link local, carrier grade NAT, multicast and reserved ranges, because requests to Plain never arrive from them.
If you enter a range with host bits set, such as 8.8.4.7/24, Plain saves the network that range starts at (8.8.4.0/24) and tells you.
Broad ranges
Plain warns you before you save a very broad range, such as an IPv4 range wider than /8. A range ending in /0 allows every address, so it does not restrict the key at all.
What happens to requests from other IP addresses
Once a key has an allowlist, any request made with that key from an address outside the list is rejected with a 403 error. The key keeps working from addresses on the list.
Before you save, check that every server, job and integration that uses the key is covered. Anything that is not on the list stops working once the change applies.
Check which keys have an allowlist
In the API keys list on the machine user page, a key with an allowlist shows an IP allowlist badge with the number of ranges.
Permissions
You need the API key edit permission to change an allowlist. Without it you can still view the list.