> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/dashboard/whitelisting-ips.md).

# 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](/api-reference/whitelists.md).

## 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):

```bash
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

```bash
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](/api-reference/whitelists.md).

## 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).