Username reference

The proxy username is a versioned routing instruction. It chooses how an exit is selected and optionally restricts the eligible geography. The proxy key secret belongs in the password field.

Use the same username grammar for HTTP proxy Basic authentication and SOCKS5 username/password authentication.

Grammar

v1_rotate[_regions_<regions>][_countries_<countries>][_exclude_<countries>]
v1_sticky_session_<id>[_regions_<regions>][_countries_<countries>][_exclude_<countries>]
v1_fixed_session_<id>[_regions_<regions>][_countries_<countries>][_exclude_<countries>]

Square brackets mark optional clauses. They are documentation notation and must not appear in your actual username. Replace angle-bracket placeholders with values.

The version and strategy come first. Optional clauses may follow in any order, but each clause can appear only once.

Strategies

Strategy	Required session clause	Behavior
v1_rotate	None; a session clause is rejected	Select an eligible exit for each new connection
v1_sticky	_session_<id>	Reuse the session binding; allow failover when its exit is unreachable
v1_fixed	_session_<id>	Reuse the session binding; do not fail over an unreachable bound exit

Rotation does not guarantee a different exit or IP on every connection. Connection reuse also does not trigger another exit selection. See Sessions and rotation.

Clauses

Clause	Format	Example
session	ASCII letters, digits, dots, or hyphens; not empty	_session_checkout-42
regions	Supported region codes separated by hyphens	_regions_NA-EU
countries	ISO 3166-1 alpha-2 codes separated by commas	_countries_US,GB
country	Alias for countries	_country_US
exclude	ISO 3166-1 alpha-2 codes separated by commas	_exclude_RU,BY

country and countries refer to the same clause. Using both in one username is rejected.

The parser accepts version, strategy, clause names, region codes, and country codes without regard to letter case. Session IDs preserve their spelling and case. Use consistent lowercase strategy names and uppercase geographic codes in application configuration.

Supported regions

Code	Region
NA	North America
SA	South America
AF	Africa
AS	Asia
EU	Europe

Only these five region codes are accepted. Country-code validation does not imply that an exit is currently available in that country. See Geographic targeting.

Examples

# Any eligible exit, selected for each new connection
v1_rotate

# US or United Kingdom
v1_rotate_countries_US,GB

# Europe, excluding Russia and Belarus
v1_rotate_regions_EU_exclude_RU,BY

# Reuse a session with US routing and permit exit failover
v1_sticky_session_checkout-42_countries_US

# Reuse a session in Europe without exit failover
v1_fixed_session_audit-42_regions_EU

The comments above explain the examples; copy only the username line into your client.

Validation rules

• The complete username must be between 1 and 255 UTF-8 bytes.
• The version must be v1; the previous unversioned grammar is rejected.
• Session IDs use ASCII letters and digits; they cannot contain underscores, spaces, slashes, accented letters, or other punctuation beyond . and -.
• Lists cannot contain empty or duplicate values.
• Country codes must be recognized two-letter ISO country codes: use GB, not UK.
• Region lists use -; country and exclusion lists use ,.
• Unknown clauses, including city, ASN, and duration clauses, are rejected.

These invalid examples produce HTTP 407 invalid_credentials, or a SOCKS5 username/password authentication failure. SOCKS5 does not return the HTTP JSON error code:

v1_rotate_session_demo
v1_sticky
v1_fixed_session_demo_1
v1_rotate_regions_EU,NA
v1_rotate_countries_US,US
v1_rotate_country_US_countries_GB
v1_rotate_city_london