> ## Documentation Index
> Fetch the complete documentation index at: https://developers.soax.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> How to authenticate with SOAX proxies using username/password or IP Auth. Includes connection string format, where to find credentials, and working examples.
SOAX supports two ways to authenticate your proxy requests: **username/password** and **IP Auth**. Both are configured per proxy package in the dashboard.
## Where to find your credentials
Each proxy package has its own credentials. To find them:
1. Log in to the [dashboard](https://platform.soax.com).
2. Open **Quick Connect** or go to your proxy package settings.
3. Your **package key** (password) is displayed there. Copy it exactly as shown. Package keys look like `pk_abc123…`.
You can regenerate your package key at any time from the dashboard. This immediately invalidates the old key, so make sure to update it everywhere you use it before regenerating.
## Username/password authentication
This is the most common way to connect. You send your credentials with every request as part of the proxy connection string.
The format is:
```
{rules}:{package_key}@proxy.soax.com:1337
```
The **username** field carries your rules (country, session, network type, rotation, error handling). The **password** field is your package key. They are separated by a colon.
Here's a basic example that routes through a US residential proxy:
```bash theme={null}
curl -x proxy.soax.com:1337 -U "country-us:pk_abc123" https://checker.soax.com/api/ipinfo
```
You should get a response like this:
```json theme={null}
{
"status": true,
"data": {
"ip": "185.123.45.67",
"country_code": "US",
"country_name": "United States",
"region": "California",
"city": "Los Angeles",
"isp": "Spectrum",
"carrier": ""
}
}
```
You need at least one targeting rule in the username. If you want the full global pool without any geographic filter, use `country-any`:
```bash theme={null}
curl -x proxy.soax.com:1337 -U "country-any:pk_abc123" https://checker.soax.com/api/ipinfo
```
### Adding more rules
You can chain multiple rules in the username field using hyphens as delimiters. Multi-word values use underscores instead of hyphens (the hyphen is the rule delimiter).
Here are some examples:
**Target a specific country and city:**
```
country-us-city-new_york:pk_abc123@proxy.soax.com:1337
```
**Use mobile network in a specific region:**
```
network-mob-country-us-region-california:pk_abc123@proxy.soax.com:1337
```
**Add a session to keep the same IP across requests:**
```
country-us-session-job42:pk_abc123@proxy.soax.com:1337
```
Rules can appear in any order. The full list is covered in the [Residential proxies](/proxies/residential) and [Mobile proxies](/proxies/mobile) reference pages.
### Supported protocols
Username/password authentication works with all proxy protocols on the same gateway port:
| Protocol | Supported | Port |
| -------- | --------- | ---- |
| HTTP | Yes | 1337 |
| HTTPS | Yes | 1337 |
| SOCKS5 | Yes | 1337 |
## IP Auth
If you don't want to send credentials with every request, you can authenticate by IP instead. Once your client IP is on the package's allowlist, SOAX authenticates based on where the request comes from.
### Setting up IP Auth
1. In the dashboard, open your proxy package settings.
2. Find the **IP Allowlist** section.
3. Add the public IP address of the machine that will send requests.
Once added, you can connect without sending a username and password. With Quick Connect, the rules go in the subdomain instead.
### Quick Connect with IP Auth (HTTPS only)
```
https://{rules}.proxy.soax.com:1337
```
For example, to route through a US proxy:
```bash theme={null}
curl --proxy "https://country-us.proxy.soax.com:1337" https://checker.soax.com/api/ipinfo
```
This works at the start of the TLS handshake (SNI), which is why it's HTTPS-only — there is no equivalent field for SOAX to read with IP Auth on plain HTTP or SOCKS5.
Subdomains are subject to a 63-character DNS label limit (RFC 1035). If your rule string is long (combining country, city, ISP, session, and rotation rules), you may hit this limit. Use the [parameter shortcuts](/proxies/residential#parameter-shortcuts) (e.g. `c-us-ci-new_york-s-job1` instead of `country-us-city-new_york-session-job1`) to keep it short, or switch to username/password authentication, which has no rule-length limit.
### IP Auth over HTTP and SOCKS5
There is no way to pass runtime rules with IP Auth on plain HTTP or SOCKS5. HTTP has no username field and no SNI, and SOCKS5 has no username field under IP Auth. IP Auth carries rules over HTTPS only, via the subdomain (SNI), as shown above.
If you need runtime rules on HTTP or SOCKS5, use **username/password** authentication instead — the rules go in the username field, and all three protocols support it.
### Protocol support summary
| Auth method | HTTP | HTTPS | SOCKS5 |
| ---------------------------- | ---- | ----- | ------ |
| Username / password | Yes | Yes | Yes |
| IP Auth (rules in subdomain) | No | Yes | No |
## Which method should I use?
For most use cases, **username/password** is the simplest option. It works with all protocols, has no rule-length limits, and doesn't need any dashboard setup beyond copying your package key.
**IP Auth** is useful when your tool or integration doesn't support proxy credentials (some browser automation tools and legacy HTTP clients fall into this category), or when you want to avoid embedding credentials in configuration files.
You can use both methods on the same package. Adding an IP to the allowlist doesn't disable username/password authentication.
## Errors
If authentication fails, the proxy returns an error with two response headers: `X-SOAX-Error` (a machine-readable code) and `X-SOAX-Detail` (a plain explanation). The common ones:
| HTTP | X-SOAX-Error | Meaning |
| ---- | ------------------- | ------------------------------------- |
| 407 | `AUTH_FAILED` | Invalid or missing package key |
| 407 | `IP_NOT_ALLOWED` | Your client IP isn't on the allowlist |
| 407 | `PACKAGE_SUSPENDED` | Account suspended or disabled |
See [Error codes](/troubleshooting/error-codes) for the full list.
## Next steps
Full rule reference for residential proxy configuration.
Full rule reference for mobile proxy configuration.
Generate connection strings from the dashboard without memorizing the format.
What to do if you get a 407 AUTH\_FAILED or IP\_NOT\_ALLOWED error.