Proxy authentication

Authenticate each new proxy connection with a routing username and the complete proxy key secret as the password. HTTP proxies carry these credentials in Basic authentication; SOCKS5 carries them in its username/password handshake. Both protocols use the same credentials and routing rules.

Credentials at a glance

Field	Value	Purpose
Proxy endpoint	Your assigned proxy URL	Connects your client to the proxy service
Username	v1_rotate, or another valid routing username	Selects rotation, a session, and optional geographic filters
Password	Your complete rp1_... secret	Authorizes proxy connections for its workspace

The example prefix rp1_... is a placeholder. Supply the complete secret, without extra whitespace or a newline. A key’s display name, ID, or visible suffix cannot be used as its password.

Make an authenticated request

Configure your assigned endpoint and a secret in your environment, then let the client construct the protocol’s authentication exchange:

curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_rotate:$PORTS_PROXY_KEY" \
  --connect-timeout 15 \
  --max-time 30 \
  https://example.com/

PORTS_PROXY_URL and PORTS_PROXY_KEY are application variables used in this example. Their values must come from your service configuration and key creation flow. Include the assigned scheme, hostname, and port; do not infer a SOCKS port from an HTTPS proxy URL.

For curl, use an assigned http:// or https:// proxy URL for HTTP proxying, or socks5h:// for SOCKS5 with remote DNS. An HTTPS destination establishes the corresponding tunnel and then negotiates TLS with the destination. See Protocols and limits for transport details.

HTTP wire format

Clients send one Proxy-Authorization header on the initial proxy request:

CONNECT example.com:443 HTTP/1.1
Host: example.com:443
Proxy-Authorization: Basic <base64-of-username:password>

The Base64 input is the UTF-8 string username:password. Use the standard Basic authentication encoder in your HTTP library. Do not send the key in an origin Authorization header, a URL query parameter, or a custom bearer header.

Basic authentication encoding does not encrypt the credentials. Use the proxy transport supplied for your environment and protect the key as a secret.

SOCKS5 authentication and remote DNS

Configure SOCKS5 username/password authentication (RFC 1929) with the routing username and full key. Do not Base64-encode the password or send an HTTP Proxy-Authorization header inside the SOCKS handshake. The gateway does not accept anonymous authentication.

With curl or Python Requests, set PORTS_PROXY_URL to the assigned SOCKS endpoint using socks5h://. This sends the destination hostname to the proxy for the exit to resolve. Their socks5:// mode sends a locally resolved IP address, which is refused because destinations must be hostnames. The h selects remote DNS; it does not encrypt the proxy connection.

The username and password are each limited to 255 UTF-8 bytes. Send the complete key. See the curl, Python, or JavaScript guide for client-specific configuration.

Change routing without replacing the key

The same key can authenticate different routing usernames:

v1_rotate
v1_rotate_countries_US
v1_sticky_session_checkout-42_countries_US
v1_fixed_session_audit-42_regions_EU

The username never needs an account or workspace ID. The verified password identifies the workspace automatically. See Username reference for the complete grammar.

Authentication failures

HTTP authentication failures return 407 with Proxy-Authenticate: Basic. The error code distinguishes invalid_credentials, key_expired, key_revoked, and account_disabled.

SOCKS5 authentication failures return an RFC 1929 failure status, without HTTP headers or a JSON error body. Invalid usernames, invalid keys, expired or revoked keys, and disabled workspaces use the same failure status. A client that does not offer username/password authentication receives a no-acceptable-methods reply before authentication starts.

Check the whole username and password together: an unsupported username is also an authentication failure. Modified or wrong-environment secrets are rejected. If an unchanged key suddenly fails across otherwise valid requests, use the troubleshooting guide before creating replacement keys. Revocation and workspace status changes have a propagation interval.

Protect credentials

• Store secrets in a secret manager or environment configuration.
• Keep them out of source code, browser-delivered applications, request logs, screenshots, and support messages.
• Use separate keys for applications that need independent revocation.
• Replace a leaked or lost key using the key lifecycle guide.

A proxy key grants proxy connection access. It is not a management API token.