IP whitelist and passwordless ports

The exact whitelist rules, how they relate to the Extract API, and which leg passwordless access actually skips.

The whitelist has one specific job on this platform: authorising the Extract API and serving as the access credential for passwordless ports. It is not a switch that makes port 58971 passwordless.

What the whitelist does

Whitelist rules

Only public, globally routable unicast IPv4 addresses are accepted.

Rejected: IPv6, private ranges, loopback, link-local, documentation ranges, CGNAT ranges.

CIDR is not supported — one IPv4 string per entry. Covering a subnet means adding entries one by one, or consolidating your egress IP.

Ten per proxy sub-account, not ten per user — each sub-account has its own allowance of ten.

Entries unused for 10 consecutive days are deleted by a maintenance job, along with their port bindings.

Adding an entry

First determine your current egress IP. The console has a /api/v1/client-ip endpoint, or simply:

shell

curl -s https://api.ipify.org

Then add it on the console's whitelist page, or via API:

POST/api/v1/proxy/ip-whitelist

shell

curl -X POST 'https://api.example.com/api/v1/proxy/ip-whitelist' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
  -H 'Origin: https://console.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"accountId":"YOUR_ACCOUNT_ID","ipAddress":"203.0.113.10"}'

Listing and deleting:

GET/api/v1/proxy/ip-whitelist

DELETE/api/v1/proxy/ip-whitelist/:id

Exceeding the limit

Adding an eleventh entry returns HTTP 409 with error code proxy_api_limit_reached. Delete an unused entry first.

How passwordless ports work

This is the whitelist's most valuable use. The flow:

Whitelist your egress IP

Passwordless ports identify you by the "source IP + port" combination, so the source IP must be registered first.

Call the Extract API for a batch of ports

shell

curl 'https://api.example.com/api/v1/proxy/extract?apikey=YOUR_KEY&num=5&country=US&session=sticky&time=10'

Response:

text

1.2.3.4:20001
1.2.3.4:20002
1.2.3.4:20003
1.2.3.4:20004
1.2.3.4:20005

Use them directly, no credentials

shell

curl -x http://1.2.3.4:20001 https://api.ipify.org

Each port is already bound in the control plane to your account and to the region and session configuration you specified at extraction time.

When passwordless ports stop working

The API key is revoked
The corresponding whitelist entry is deleted
The whitelist entry is auto-cleaned after 10 idle days
The gateway node serving that port becomes unhealthy — the stale binding is deleted and reassigned on the next extraction
The proxy account or API key record is deleted

Choosing between the two access methods

	Credentials on `58971`	Passwordless ports
Whitelist required	No	Yes
Egress IP changes	No effect	Everything breaks
Region/session config	Per request (via the username)	Fixed at extraction
ASN targeting	Supported	Not supported
Best for	Most scenarios	Server-side setups with a fixed egress IP and stable configuration

Port ranges

The passwordless port range is registered by each gateway node rather than fixed as a constant. Registration constraints:

Start port no lower than 1024
End port no higher than 65535
At most 4096 ports per node

So don't hard-code a port range in your firewall; follow whatever the Extract API actually returns.

More in this section