Start here · Authentication
Two ways to prove it is you: a password, or the address you connect from.
Both methods work on every network and on both protocols. Pick per server, mix them freely.
Choosing a method#
| Username and password | IP whitelist | |
|---|---|---|
| Works from | Any IP, including dynamic and cloud ones | The public IPv4 addresses you registered |
| Targeting parameters | Appended to the username | Send any username to pass them; the password is ignored |
| Credentials in transit | Base64 in the Proxy-Authorization header | None |
| Best for | Laptops, containers, serverless, browsers | Fixed servers, anti-detect browsers that cannot store a password, Chrome flags |
| Rotation | Regenerate the password at any time | Add or remove addresses at any time |
Username and password#
Your account has one credential pair for the shared gateways. It is shown in the dashboard under Credentials and returned by GET /v1/credentials. The username carries the targeting parameters; the password never changes with them.
# HTTP(S) target through the residential gateway
curl -x http://USER-cc-us:[email protected]:9000 https://api.ipify.org
# Same thing over SOCKS5 (socks5h = resolve the hostname at the exit)
curl --proxy socks5h://USER-cc-us:[email protected]:9001 https://api.ipify.orgUnder the hood an HTTP client sends Proxy-Authorization: Basic base64(username:password) on the request or on the CONNECT; a SOCKS5 client uses the username/password sub-negotiation (RFC 1929). Every mainstream client does this for you when the credentials are in the proxy URL.
IP whitelist#
Register the public IPv4 addresses of the machines that will connect, and they can use every endpoint without credentials. Up to 50 addresses per account; changes apply within a minute.
- Find the address the target will see from your server:
curl https://api.ipify.orgwithout a proxy. - Add it under Settings → Whitelist, or call
POST /v1/whitelist. - Connect without a username and password. With no username the exit is chosen worldwide and rotates on every connection.
- To target, keep sending a username with the parameters you need and any password: a whitelisted address is trusted regardless of the password.
# From a whitelisted server: no credentials at all
curl -x http://res.proxshift.com:9000 https://api.ipify.org
# Still whitelisted, but with targeting: any password works
curl -x http://USER-cc-fr-city-paris:[email protected]:9000 https://api.ipify.orgDedicated ISP, datacenter and mobile devices#
Each dedicated address comes with its own username and password, printed in your list as ip:port:user:pass. The whitelist applies to them too: from a registered server you connect to ip:8000 with no credentials at all. Parameters are not needed on a dedicated address, since its location is fixed.
203.0.113.42:8000:u7f3a9c:kq2Lm8Pz1r # HTTP(S)
203.0.113.42:8001:u7f3a9c:kq2Lm8Pz1r # SOCKS5, same credentialsSub-users#
A sub-user is an extra credential pair on the shared gateways with its own traffic limit and its own usage line. Create one per client, per project or per teammate so a leaked password only exposes a bounded budget and you can read consumption per line of business. Sub-users are managed in the dashboard and through POST /v1/subusers.
Rotating a password#
Regenerate from the dashboard or with POST /v1/credentials/rotate. The previous pair keeps working for ten minutes so running jobs can pick up the new one without failing.
Keeping credentials out of the wrong places#
- Read them from environment variables or a secret store, never from source control.
- Prefer the whitelist on shared or untrusted networks: the hop from you to the gateway is plain HTTP, so a Basic header can be read on the path.
- Give each tool a sub-user; revoke the sub-user instead of the account password when a tool is retired.
- Strip proxy URLs from logs. Most clients print the full URL, credentials included, on errors.