What is IP whitelisting?
Definition
Authorising a proxy by the address your traffic comes from instead of a username and password. Simple on a fixed server, fragile anywhere else.
You register a public address, or a range of them, with the provider, and requests arriving from it are accepted with no username or password. Nothing secret travels with the request, which is the whole appeal: there is no credential to leak into a log or a repository. The catch is that the provider judges the address your connection actually arrives from, and that is not always the address you think you have. Allowlisting is the same mechanism under a newer name.
Allow-list or credentials: where the client runs decides
| Where the job runs | Allow-list | Credentials |
|---|---|---|
| A server with a static public IPv4 address | Works well, and nothing secret to leak | Works |
| A laptop on home, office or hotel networks | Breaks every time the network changes | Works |
| Autoscaled instances or rescheduled containers | Each new host can egress from a new address, unless traffic leaves through one fixed NAT gateway | Works |
| Hosted CI runners | GitHub documents its hosted runners as using dynamically assigned addresses from shared infrastructure, so listing them admits other tenants | Works |
| Behind carrier-grade NAT | Everyone sharing the operator’s public address is admitted with you | Works |
| A dual-stack host | Fails intermittently if only one address family is registered | Works |
The pattern is plain: an allow-list is the better option in exactly one row, and credentials work in all of them. Where a provider accepts both at once, requiring the listed address and the credentials together is stronger than either alone. For how credential authentication works on the wire, see its own entry.
Find the address the provider will see
Run this on the machine that will run the job, not on your laptop:
curl -4 -s https://api64.ipify.org; echo # public IPv4 address
curl -6 -s https://api64.ipify.org; echo # public IPv6 address, if the host has one
curl -s -o /dev/null -w '%{remote_ip}\n' https://api64.ipify.org # which family curl chose
The third line catches the intermittent failure. A dual-stack client races IPv6 and IPv4 connections, the Happy Eyeballs algorithm in RFC 8305, and uses whichever completes first. On our dual-stack test machine both -4 and -6 answered, and with no flag curl 8.7.1 connected over IPv4. Another run, another network or another client can go the other way. If only your IPv4 address is on the list, a connection that leaves over IPv6 is refused, and the job fails on some runs and not others. Register both families, or force one in the client with -4 or -6. The curl guide shows how to confirm which exit a request finally used once it does reach the proxy.
The same logic covers carrier-grade NAT. RFC 6598 set aside 100.64.0.0/10 as shared address space for it, so if your machine reports an address in that range, your real public address belongs to the operator and is shared with other customers. The IP check on the tools page shows the public address a site sees for the browser you open it in.
A refusal that does not name its cause
HTTP has no status code for “your address is not on the list”. What you get is whatever the provider chose to send, and the 403 vs 407 vs 429 guide lists a changed server address among the causes of a 407, since from the proxy’s side you simply sent no credentials. It looks like a wrong password, an expired plan or a dead gateway. Three habits save the hour:
- Record which addresses you registered, next to the rest of the proxy configuration.
- When a working setup stops, check the current egress address before anything else.
- List the narrowest range that works. A whole CIDR block added in a hurry during an incident tends to stay there.
Tools that pass proxies through configuration files, such as git, npm and pip, are where the allow-list pays off most, because no secret has to be written into them; proxies for git, npm and pip covers that case. What is a proxy server? sets both mechanisms side by side. For a job whose address moves, credentials are the honest choice. They travel with the request, so they survive the move.