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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/dashboard/whitelisting-ips.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.