This guide covers the two common authentication models, how targeting headers differ from credentials, and the practices that keep secrets out of logs and source control.
Username and password
Most HTTP clients accept a proxy URL with embedded credentials. The client converts that into a Proxy-Authorization header using Basic authentication. It works everywhere, which is why it is the default in examples.
The weakness is operational. Credentials in a URL end up in shell history, process lists, and error messages. Prefer client configuration that stores the password separately, or use environment variables that are not echoed by the runtime.
import os
import requests
proxy = os.environ["GRAVIIX_PROXY_URL"]
proxies = {"http": proxy, "https": proxy}
response = requests.get(
"https://httpbin.org/ip",
proxies=proxies,
timeout=30,
)
print(response.json())IP whitelisting
Instead of sending credentials, you tell the proxy which source IPs may connect without a password. This removes secrets from the request path and simplifies configuration for fixed infrastructure such as an office or a cloud worker with a stable egress IP.
The trade-off is coupling. If the source IP changes, access breaks until the allowlist is updated. This model suits stable environments and is a poor fit for laptops on mobile networks.
Targeting headers are not authentication
Headers that select a country, city, ISP, or session are routing instructions. They do not prove identity on their own and should not be treated as secrets. Keep credentials separate, and send targeting headers only on requests that need them.
curl -x http://proxy.graviix.com:8080 \
-U "USERNAME:PASSWORD" \
-H "X-Graviix-Country: DE" \
-H "X-Graviix-City: berlin" \
https://httpbin.org/ipHandling a 407 correctly
A 407 means the proxy wants authentication and did not get valid credentials. Check three things in order: whether the client is sending proxy auth at all, whether the username or password contains characters that need encoding, and whether the credential is still active.
If a request works with curl but fails in an application, the client is usually ignoring proxy environment variables or is configured with a different auth scheme. Log the proxy host and port, never the password.
Authentication in CI and automated jobs
Automated jobs need credentials at runtime without exposing them to every log line. Store the proxy URL or the username and password in the platform secret store, inject them as environment variables, and avoid printing the full configuration at startup.
If a job runs from a fixed runner, IP allowlisting is often simpler than distributing credentials. Where runners are ephemeral, credentials are usually the practical choice. In both cases, separate development and production credentials so a leaked test credential cannot consume production bandwidth.
Rotating and revoking credentials
Treat proxy credentials like any other secret. Rotate them on a schedule, and immediately if a machine or repository is compromised. Keep the number of active credentials small enough that revocation is straightforward.
After rotation, update the secret store first, then restart the workers that consume it. Confirm with a test request from each environment. A credential that works locally but not in production usually means the deployment is still reading an old value from cache or from a stale environment file.
Debugging authentication failures
A 407 response means the proxy wants credentials; a 403 usually means it received them but refused the request. That distinction narrows the search immediately. Check the scheme first, then the encoding of special characters in the username or password.
Passwords containing @, :, or / must be URL-encoded when embedded in a proxy URL, or supplied through a separate authentication option. A credential that works in a browser extension may fail in code for this reason alone.
Confirm you are connecting to the hostname and port from the dashboard, not a generic endpoint from an older guide. Then verify from a second network, because local firewalls and corporate proxies sometimes intercept outbound connections and return their own error pages.
Log the status code and a short message, never the credential itself. Debugging should not require copying secrets into chat.
Key takeaways
- Use username and password for portability; use IP whitelisting for stable infrastructure.
- Keep secrets in environment variables or a secret manager, not in URLs committed to a repository.
- Treat targeting headers as routing hints, not credentials.
Frequently asked questions
Can I use both authentication methods at once?
Some deployments support both, but pick one primary model per environment. Mixing them makes failures harder to diagnose and increases the chance of leaving an unnecessary allowlist entry in place.
Why does my password work in one tool and fail in another?
Special characters in a URL must be percent-encoded, and some clients require the proxy auth to be configured separately from the destination URL. Check the client documentation for proxy-specific options.
Are targeting headers encrypted?
They travel to the proxy gateway over the connection you configure. Use HTTPS endpoints and avoid sending credentials over plain HTTP. For SOCKS5, authentication is handled by the protocol rather than an HTTP header.
Need proxies for this workflow?
Graviix provides residential, mobile, datacenter, and static ISP proxies with country and city targeting, rotating or sticky sessions, and a documented HTTP API.
