IP whitelist

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 for the shared basics.

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 instead, because these endpoints do not apply to them.

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

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"
  }'

ttl is in seconds, not minutes. It defaults to 0, so set it explicitly if the lifetime of the entry matters to you.

Deleting cuts access immediately

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.

curl -X DELETE https://api.nodemaven.com/api/v2/base/whitelist/ip/WHITELIST_IP_ID \
  -H "Authorization: x-api-key YOUR_API_KEY"

IP whitelist is the dashboard view of the same feature.
ISP authentication covers how ISP proxies authenticate, since whitelisting does not apply to them.

Platform API

Product APIs

Endpoints

One endpoint creates and updates

WhitelistIPRequest

Deleting cuts access immediately

​Endpoints

​One endpoint creates and updates

​WhitelistIPRequest

​Deleting cuts access immediately

​Related reading

Endpoints

One endpoint creates and updates

WhitelistIPRequest

Deleting cuts access immediately

Related reading