> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nodemaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IP whitelist

> Manage whitelisted IPs for Residential and Mobile proxies. The create and update call is a single upsert, which is why it can return either 200 or 201.

The whitelist endpoints manage IP whitelisting: letting a known IP address connect without sending proxy credentials on every request. You add an IP, retrieve it, and remove it when it is no longer yours.

All requests go to `https://api.nodemaven.com/api/v2/base/` and carry the header `Authorization: x-api-key YOUR_API_KEY`. See the [NodeMaven API overview](/proxy-api/overview) for the shared basics.

<Warning>
  **IP whitelisting is available for Residential and Mobile proxies only. It is not available for ISP proxies.** If you are working with ISP proxies, see [ISP authentication](/isp/authentication) instead, because these endpoints do not apply to them.
</Warning>

## Endpoints

| Method | Path | What it does | Request body | Responses |
| - | - | - | - | - |
| `GET` | `/whitelist/ips` | Retrieve whitelisted IPs | | 200, 403 |
| `POST` | `/whitelist/ip/upsert` | Create or update a whitelist IP | `WhitelistIPRequest` | 200, 201, 400, 403, 404 |
| `GET` | `/whitelist/ip/{id}` | Retrieve a whitelisted IP by ID | | 200, 404, 500 |
| `DELETE` | `/whitelist/ip/{id}` | Delete a whitelisted IP by ID | | 200, 404, 500 |

## One endpoint creates and updates

`POST /whitelist/ip/upsert` is an upsert, so it handles both cases:

* **Include `id`** and it updates the existing whitelist entry with that ID.
* **Omit `id`** and it creates a new entry.

That is why the endpoint lists both 200 and 201 as success responses: 201 for something newly created, 200 for something updated.

## WhitelistIPRequest

| Field | Type | Notes |
| - | - | - |
| `id` | uuid | For updates. Omit it to create |
| `ip` | string | The IP address to whitelist |
| `name` | string | Optional label to help you tell entries apart |
| `sticky` | boolean | Defaults to `false` |
| `ttl` | integer | In **seconds**. Defaults to `0` |
| `protocol` | enum | `HTTP` or `SOCKS5`. Defaults to `HTTP` |
| `type` | enum | `residential` or `mobile`. Defaults to `residential` |
| `quality_filter_enabled` | boolean | Defaults to `false` |
| `ports_count` | integer | How many ports to allocate |

```bash theme={null}
curl -X POST https://api.nodemaven.com/api/v2/base/whitelist/ip/upsert \
  -H "Authorization: x-api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "203.0.113.10",
    "name": "Office egress",
    "protocol": "HTTP",
    "type": "residential"
  }'
```

<Note>
  **`ttl` is in seconds, not minutes.** It defaults to `0`, so set it explicitly if the lifetime of the entry matters to you.
</Note>

## Deleting cuts access immediately

<Warning>
  **Deleting a whitelisted IP immediately cuts off access for anything relying on it.** Any machine that was connecting without credentials because its IP was whitelisted stops being able to connect as soon as the entry is removed. Make sure the client has credentials to fall back on, or a replacement whitelist entry, before you delete.
</Warning>

```bash theme={null}
curl -X DELETE https://api.nodemaven.com/api/v2/base/whitelist/ip/WHITELIST_IP_ID \
  -H "Authorization: x-api-key YOUR_API_KEY"
```

## Related reading

* [IP whitelist](/residential-mobile/ip-whitelist) is the dashboard view of the same feature.
* [ISP authentication](/isp/authentication) covers how ISP proxies authenticate, since whitelisting does not apply to them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.