Authentication
Username and password, or a whitelist of your own server IPs. Both are set per proxy user, and an account can have up to 100 proxy users.
The gateway needs to know two things on every connection: which account is paying for it, and what kind of IP to hand out. Both come from the proxy user. A proxy user has a name, a password, a default network, optionally a traffic cap, and optionally a list of IP addresses that may use it without a password.
Username and password
The default. Your client sends HANDLE-NAME, your account handle and the proxy user's name (with any targeting parameters appended), as the username and the proxy user's password as the password, using ordinary proxy authentication. Over HTTP and HTTPS that is the Proxy-Authorization: Basic header; over SOCKS5 it is the username/password method from RFC 1929. Every client library does this for you when the credentials are part of the proxy URL.
# The client base64-encodes user:pass into a Proxy-Authorization header
curl -x icn-01.gw.scalardata.ai:7777 \
-U "k7f3q2-acme-country-kr:PASSWORD" \
https://ipinfo.io/jsonPasswords are 16 to 128 printable ASCII characters without spaces or colons. The dashboard generates one and can regenerate it; through the API you can choose your own. The gateway never accepts your dashboard sign-in (an email link or Google), only proxy user passwords and whitelisted addresses.
IP whitelist
If your traffic comes from servers with fixed public addresses, attach those addresses to a proxy user instead of shipping a password around. A connection from a whitelisted IP skips the password check for the proxy user the address is attached to: send no credentials and the gateway routes the request as that proxy user, with its defaults, or send that proxy user's username without a password to carry targeting. A username of any other proxy user still needs its own password.
# From a whitelisted server: no password, username only carries targeting
curl -x icn-01.gw.scalardata.ai:7777 \
-U "k7f3q2-acme-country-kr:" \
https://ipinfo.io/json
# From a whitelisted server with no credentials at all:
# routed as the proxy user the IP is attached to, with that user's defaults
curl -x icn-01.gw.scalardata.ai:7777 https://ipinfo.io/jsonWhitelists accept single IPv4 and IPv6 addresses and CIDR ranges up to /24 (IPv4) or /64 (IPv6), at most 50 entries per account; private and reserved ranges cannot be whitelisted. Each entry belongs to one proxy user. Entries of your own proxy users may overlap; a connection then belongs to the most specific entry (a /32 inside a /24 wins). An address another account holds cannot be added. Manage the list on the dashboard's IP whitelist page, where each address is assigned to one of your proxy users, or with the whitelist endpoints.
Whitelisting does not work from home connections or cloud functions whose egress address changes, and NAT means every machine behind the same public IP shares the same proxy user.
Multiple proxy users
One account can hold up to 100 proxy users. Each has its own password, default network, whitelist and cap, and usage is reported per proxy user, so they double as cost centres. A typical layout:
acme-prod residential, password A, capped at the monthly budget
acme-staging residential, password B, small cap
acme-crawler datacenter, password C, whitelist onlyAll proxy users draw from the same account balance and subscriptions, so a datacenter proxy user such as acme-crawler carries traffic only while the account has a datacenter subscription. A cap limits the bytes the proxy user may move in a UTC month on any network; it does not buy separate traffic. Proxy users can be created from the dashboard or the API.
Rotating credentials
Change a proxy user's password from the dashboard or the API. The new password applies to new connections straight away; connections that are already open stay open. To cut them, disable the proxy user: its open connections close within seconds. Sticky sessions are keyed by proxy user and session ID, not by password, so an in-flight session keeps its IP across a rotation.
If a password may have leaked, disable the proxy user (this also closes its open connections), rotate the password, enable it again, then look at its usage by day to see whether anything unexpected ran. Two habits keep this rare:
- Use one proxy user per environment and per third party, so a rotation only touches the thing that leaked.
- Keep the proxy URL out of logs. Many HTTP libraries print the full URL, credentials included, on error. Prefer environment variables or a whitelist for long-running servers.