Skip to main content
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.
  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: 
curl -x proxy.soax.com:1337 -U "country-us:pk_abc123" https://checker.soax.com/api/ipinfo
You should get a response like this: 
{
  "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: 
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 and Mobile proxies reference pages.

​
Supported protocols

Username/password authentication works with all proxy protocols on the same gateway port:
ProtocolSupportedPort
HTTPYes1337
HTTPSYes1337
SOCKS5Yes1337

​
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: 
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 (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 methodHTTPHTTPSSOCKS5
Username / passwordYesYesYes
IP Auth (rules in subdomain)NoYesNo

​
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:
HTTPX-SOAX-ErrorMeaning
407AUTH_FAILEDInvalid or missing package key
407IP_NOT_ALLOWEDYour client IP isn’t on the allowlist
407PACKAGE_SUSPENDEDAccount suspended or disabled
See Error codes for the full list.

​
Next steps

Residential proxies

Full rule reference for residential proxy configuration.

Mobile proxies

Full rule reference for mobile proxy configuration.

Quick Connect

Generate connection strings from the dashboard without memorizing the format.

Error codes

What to do if you get a 407 AUTH_FAILED or IP_NOT_ALLOWED error.