Authentication

helodata residential proxies support two authentication models. You can switch between them per sub-user — they are not mutually exclusive at the account level.

Model A — User + password (default)

Pass the proxy username and password with the request. The username carries all targeting parameters; the password is the static value from the sub-user.

curl -x http://helo_s1a2b3c4d5e-type-res-region-us:[e-mail]:7777 \
     https://example.com

Behind the scenes the client encodes username:password as Base64 and sends:

Proxy-Authorization: Basic aGVsb19zMWEyYjNjNGQ1ZS10eXBlLXJlcy1yZWdpb24tdXM6UEFTU1dPUkQ=

Pros

• Works from any source IP — no infrastructure setup
• Targeting changes per request (just change the username)
• Easy to scope per-customer with separate sub-users

Cons

• Credentials sit in your code or config — protect accordingly

Where to put the credentials

• URL form http://user:pass@host:port — most HTTP clients understand it
• Proxy-Authorization header — best when the URL form is awkward (e.g. browser CDPs)
• Environment variables HTTP_PROXY=http://user:pass@host:port HTTPS_PROXY=... — works for curl, wget, requests, and most Unix tools

Model B — IP whitelist

Register your egress IPs in the dashboard. Requests from those IPs are accepted with no Proxy-Authorization header. The sub-user is still required in the username so targeting and billing work.

curl -x http://[e-mail]:7777 \
     https://example.com

To enable:

1. Open Dashboard → Residential → {Sub-user} → Whitelisted IPs.
2. Add up to 50 IPv4 addresses or CIDR ranges per sub-user.
3. Changes take effect within 60 seconds.

Pros

• No secret to leak
• Cleaner code (no inline credentials)

Cons

• Useless for clients with dynamic egress (laptops, mobile, ephemeral CI)
• Targeting still has to be encoded in the username, so it's not fully credential-free

Choosing between them

Scenario	Recommended
Server with static egress IP	IP whitelist
Container in autoscaling group (variable IP)	User + password
Local development from a laptop	User + password
Headless browser farm behind a NAT	IP whitelist for the NAT IP

You can use both: whitelist your production servers and keep username/password active for dev machines.

Rotating credentials

To rotate a sub-user password:

1. Dashboard → Residential → {Sub-user} → Reset password.
2. The old password keeps working for 60 seconds, then begins returning 407.
3. Update your deployment.

API

Whitelisted IPs and sub-user credentials are also managed via the Whitelists API and Sub-users API.