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

```bash
curl -x http://helo_s1a2b3c4d5e-type-res-region-us:PASSWORD@gate.helodata.io: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.

```bash
curl -x http://helo_s1a2b3c4d5e-type-res-region-us@gate.helodata.io: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](/api-reference/whitelists.md) and [Sub-users API](/api-reference/sub-users.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/products/overview/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.