Whitelisting IPs

IP whitelisting lets requests from registered source IPs skip Proxy-Authorization — easier for servers in fixed-egress environments. This page is the dashboard flow; for the API see Whitelists API.

Where the whitelist lives

The scope depends on the product:

Product	Whitelist scope
Residential	Per sub-user
Mobile	Per sub-user
ISP	Per batch

A single source IP can be whitelisted in many places independently. There's no "global" whitelist.

Add an IP

Sub-user whitelist (gateway products)

1. Left nav → {Product} → Sub-users → {Sub-user} → Whitelisted IPs.
2. Add IP.
3. Enter:

   • IP or CIDR (max /24 for IPv4, /64 for IPv6)
   • Label (your description, e.g. prod-eu-west-1)
4. Save.

Active within 60 seconds.

[screenshot: Whitelisted IPs panel with one entry]

ISP batch whitelist

1. Left nav → ISP → My IPs → {Batch} → Whitelisted IPs.
2. Add IP — same form.

The batch whitelist applies to every IP in that batch.

Remove

Click the trash icon next to an entry. Effective within 60 seconds.

CIDR vs single IP

Whitelist supports /24 (IPv4) or /64 (IPv6) at most.

Source pattern	Use
One static server	Single 203.0.113.5
Container fleet behind NAT	The NAT IP (single entry)
Kubernetes egress	The NAT IP of the cluster's egress gateway
Multiple ASN-issued IPs from a single ISP	Several singles (or a /24 if contiguous)
Dynamic egress (laptops, autoscaling without NAT)	Don't use whitelist — use user/password auth

Limits

Scope	Max entries
Per sub-user (per product)	50
Per ISP batch	50

A /24 counts as one entry; the gateway expands it server-side.

Finding your egress IP

To find what to whitelist, run from the source machine (without the proxy):

curl https://ipv4.icanhazip.com

That's your source IP. Note that if your machine is behind a NAT or a load balancer, this returns the egress IP, which is what the gateway sees.

Mix whitelist and password

You can run both modes simultaneously per sub-user — whitelisted IPs skip auth, anyone else gets prompted for credentials. Useful when migrating a fleet to whitelisting in stages.

API alternative

curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{
       "subuser":"sub_01HX...",
       "product":"residential",
       "ip":"203.0.113.5",
       "label":"prod-eu-west-1"
     }' \
     https://api.helodata.com/v1/whitelists

Full schema: Whitelists API.

Common pitfalls

• Whitelisted the wrong IP — when you curl ipv4.icanhazip.com from your laptop you get the laptop's egress, not the production server's. SSH to the actual production machine first.
• CIDR too wide — /16 is rejected. Split into multiple /24 entries or rethink whether you need that much.
• Forgot batch whitelist after a sub-user re-bind — moving an ISP batch to a new sub-user doesn't carry over the batch whitelist (it's per-batch, not per-sub-user, so it stays).