IP Whitelisting Best Practices

A whitelist entry authorizes an address, not a person. When credential-free proxy auth works, when it breaks, and how to spot drift early.

Whitelist authentication has an appealing pitch: no passwords in your code, no secrets to rotate, connect and go. The pitch is honest as far as it goes, but the secret does not disappear; it changes shape. Instead of managing a credential, you are now managing the stability and exclusivity of your network's outward-facing address, which is a property most infrastructure was never designed to promise you. This guide is about running whitelist mode in practice: what an entry really grants, which environments it suits, which it quietly sabotages, and how to recognize its failure signature. For the comparison of the two proxy authentication modes and initial setup, see authentication; this article assumes you are past that and living with the consequences.

Which products this applies to

Whitelist authentication works on every product: the static datacenter products (shared and dedicated), all three rotating gateways (shared, premium and unmetered) and the residential gateway. What you register is your own source address, so it does not matter that a rotating or residential exit changes on every request.

On rotating you have a choice. Send no credentials and you get an untargeted exit. Send your username with an empty password and you keep your country, city and sticky-session controls, which are carried in the username, without putting the secret in a config file or your shell history.

It works on the residential gateway too, with one difference: there you must send no username and no password at all, so a whitelisted residential connection is deliberately untargeted and rotates freely across the pool. There is no empty-password halfway option as there is on rotating, because residential targeting rides entirely in the username; anything that pins a country, city or session still authenticates with credentials.

An entry authorizes an address, not a person

The mental model that prevents most whitelist mistakes: when you add an entry under Auth & IP Access, you are not registering "my laptop" or "the scraper". You are declaring that any connection arriving from that address may use your proxies, no questions asked. The proxy cannot see who is behind the address: the address is the entire identity.

That grant extends to everyone who shares the address, and far more sharing goes on than most people assume. Whitelist an office line and every colleague on that network inherits access. Whitelist a home connection behind carrier-grade NAT and you may be authorizing an unknowable set of your ISP's other subscribers who present the same public address. Whitelist the NAT gateway of a cloud VPC and every instance behind it is in. Whatever they push through your proxies is metered against your bandwidth and attributed to your account.

So the standard for adding an entry is simple to state: whitelist only addresses whose sharing set you can enumerate and accept. A dedicated server you rent alone passes. A static office IP passes if you trust the office. A coworking space, a hotel, a mobile hotspot, or anything you have not verified to be exclusively yours does not.

Find the address the proxy will actually see

The address that matters is not what your machine believes about itself: a machine's own interface usually carries a private address, and NAT rewrites it on the way out. What the proxy sees is your egress address, and the reliable way to learn it is to ask the outside world from the exact machine that will carry the traffic:

curl -s https://api.ipify.org

Three details trip people up here:

Run it where the traffic runs. Checking from your laptop while the workload lives on a server whitelists the wrong network. SSH into the server and run it there.
Machines in one facility can differ. Two servers in the same datacenter may egress through different addresses. Check each machine that will connect; each distinct answer needs its own entry.
The answer can change, which is most of the rest of this article.

If you would rather see the answer alongside the reverse DNS and the headers your client is sending, our what is my IP tool reports all three from the browser you open it in: useful for a workstation, but not a substitute for running the curl above on the machine that will actually carry the traffic. When an entry covers a range rather than a single host, the subnet calculator will tell you exactly which addresses a given CIDR block authorizes before you commit to it, which is the arithmetic people most often get wrong in the direction of granting too much.

Slot budget: a free account has 1 whitelist slot, and paid plans include 3, with additional slots available; see the pricing page. Entries can be managed from the dashboard or programmatically through the API's /ip-whitelist endpoints, described in the proxy management API reference.

Residential lines drift, usually overnight

Consumer ISPs hand out addresses dynamically. A DHCP lease renews, a modem reboots after a power blip, the ISP rebalances a subnet during a maintenance window, and your connection comes back on a different public address. Nothing on your side changed, nothing looks different, and every request now arrives from an address your whitelist has never heard of.

The signature is distinctive: a setup that worked for days or weeks fails at the start of a session, often first thing in the morning, with authentication errors and no code changes anywhere. If your line does not come with a static-IP arrangement from the ISP, this will happen to you on a schedule you do not control, and re-adding the new address each time is a treadmill rather than a fix. From a dynamic home connection, credential authentication is simply the correct tool; it is indifferent to what address you hold today.

CI runners and serverless have nothing to whitelist

Hosted CI (shared runner pools) and serverless platforms allocate egress from large shared ranges. Each job or invocation can surface from a different address, and every address in the pool is simultaneously in use by strangers. Whitelisting what you observe during one run fails twice over: the next run comes from somewhere else, so your pipeline breaks. Meanwhile the entry you added keeps authorizing whichever unrelated tenants currently occupy that address. It is the worst of both worlds: unreliable for you, generous to people you have never met.

Two patterns actually work:

Use credentials in ephemeral compute. Store the proxy username and password in the platform's secret facility, the same place its other secrets live. This is the low-friction answer and the right default.
Give the ephemeral compute a fixed front door. Route the jobs' outbound traffic through an egress point you control (a cloud NAT gateway with a reserved address, or a self-hosted runner on a machine with a static IP) and whitelist that single address. This costs setup and money, and is mainly worth it when many jobs share one egress anyway.

What does not work is treating the observed runner address as stable because it survived a week. Pools shuffle without notice; the failure is deferred, not avoided.

Containers, Kubernetes, and NAT

A container's own address is internal fiction: what the proxy sees is the egress of whatever host or gateway the traffic leaves through. On a single Docker host, that means one whitelist entry covers every container on the machine, which is convenient and is also a grant to every container on the machine, including ones that have nothing to do with proxies. Worth being deliberate about on shared hosts.

Kubernetes sharpens the problem. Pod traffic typically egresses with the address of the node the pod happens to be scheduled on. Different nodes present different addresses, the scheduler moves pods freely, and cluster autoscaling mints brand-new nodes, with brand-new egress addresses, precisely when load rises. The resulting failure signature is nasty: proxy authentication succeeds or fails apparently at random, and the failure rate climbs under load, because that is when new nodes appear. If you have ever chased an intermittent authentication failure that correlated with traffic, check whether your pods egress per-node.

The clean fix is the same shape as for CI: give the cluster one stable front door (an egress gateway or cloud NAT with a reserved address) so every pod presents the same IP, and whitelist that. Failing that, use credentials from inside the cluster and let the topology do whatever it likes.

Is it drift, or a bad password? Reading a 407 in whitelist mode

Whitelist failures and credential failures produce the same 407 status, but they are distinguishable in about two minutes:

Establish which mode the failing client is in. If its configuration contains no username, it is relying on the whitelist, and password theories are off the table entirely. This sounds obvious and skips the most common hour of wasted debugging.
Compare fresh egress against the list. Run the discovery command above on the failing machine and hold the answer up against your whitelist entries in the dashboard. A mismatch is drift: add or correct the entry, and you are done.
Cross-test with credentials. From the same machine, retry the request with a valid username and password attached. If it succeeds, the machine, network, and proxy are all fine, and the only variable left is that the source address is not recognized. If it also fails, your problem is not the whitelist; work through the broader ladder in connection issues.
Use the clock. Drift arrives after reboots, outages, lease renewals, or overnight; a wrong credential fails from the very first attempt. "It worked yesterday, untouched" points at the address, not the configuration.

A wider walkthrough of 407 in credential mode (quoting bugs, invisible characters, wrong-product credentials) is in fixing 407 errors; almost none of it applies in whitelist mode, which is exactly why step one matters.

The honest tradeoff against credentials

Whitelisting earns its keep in a narrow, real set of cases: software that cannot attach proxy credentials at all, and fixed infrastructure (a dedicated box, a static office line) where removing the stored secret genuinely removes a risk. In those places it is the simpler and arguably safer mode.

Everywhere else, the ledger favors credentials. Whitelisting couples your proxy access to network topology, which you often do not control; it consumes a finite slot budget against a fleet that may grow; it extends access to everyone sharing an address; and its failures arrive silently, on someone else's schedule. Credentials cost you secret management (storage, rotation, leak risk), but they work identically from any address, which is the property every dynamic, ephemeral, or autoscaled environment actually needs.

One subtlety closes the loop. If you find yourself automating whitelist updates (a boot script that discovers its egress and registers it through the API), notice what you have built: a machine holding an API key, which is a secret, to avoid holding a proxy password, which is a secret. Sometimes that is still worth it (the key can be scoped to whitelist writes only), but the "no secrets to manage" argument has quietly evaporated, and the key now deserves the handling described in API key security.

Whitelisting is at its best paired with static products consumed from static places: a fleet of datacenter proxies worked from a server you control is the canonical fit. A free account includes 1 whitelist slot alongside its proxies, which is enough to find out whether your egress address holds still before anything depends on it.