# Username reference

> The complete grammar, its clauses, and the validation rules.
>
> Web page: https://ports.io/docs/reference/username-reference/
> Documentation index: https://ports.io/llms.txt

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

```text
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](https://ports.io/docs/reference/sessions.md).

## 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](https://ports.io/docs/reference/targeting.md).

## Examples

```text
# 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:

```text
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
```