# 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`](https://hodlproxy.com/docs/api#get-v1-credentials). The username carries the [targeting parameters](https://hodlproxy.com/docs/username-parameters); the password never changes with them.

```bash
# HTTP(S) target through the residential gateway
curl -x http://USER-cc-us:PASS@res.hodlproxy.com:9000 https://api.ipify.org

# Same thing over SOCKS5 (socks5h = resolve the hostname at the exit)
curl --proxy socks5h://USER-cc-us:PASS@res.hodlproxy.com:9001 https://api.ipify.org
```

Under 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.

> Info: Passwords are generated from letters and digits, so they never need URL-encoding. If you set your own and it contains `@`, `:` or `/`, percent-encode those characters in proxy URLs (`@` becomes `%40`).


## 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.

1. Find the address the target will see from your server: `curl https://api.ipify.org` **without** a proxy.
2. Add it under **Settings → Whitelist**, or call [`POST /v1/whitelist`](https://hodlproxy.com/docs/api#post-v1-whitelist).
3. Connect without a username and password. With no username the exit is chosen worldwide and rotates on every connection.
4. To target, keep sending a username with the parameters you need and any password: a whitelisted address is trusted regardless of the password.

```bash
# From a whitelisted server: no credentials at all
curl -x http://res.hodlproxy.com:9000 https://api.ipify.org

# Still whitelisted, but with targeting: any password works
curl -x http://USER-cc-fr-city-paris:x@res.hodlproxy.com:9000 https://api.ipify.org
```

> Warn: Whitelisting needs a stable public IP. Machines behind carrier NAT, home connections with dynamic addresses and most serverless platforms should use the password method instead.


## Dedicated 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.

```text
203.0.113.42:8000:u7f3a9c:kq2Lm8Pz1r        # HTTP(S)
203.0.113.42:8001:u7f3a9c:kq2Lm8Pz1r        # SOCKS5, same credentials
```


## Sub-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`](https://hodlproxy.com/docs/api#post-v1-subusers).


## Rotating a password

Regenerate from the dashboard or with [`POST /v1/credentials/rotate`](https://hodlproxy.com/docs/api#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.


Source: https://hodlproxy.com/docs/authentication