Residential proxy providers solved a UX problem a long time ago: their gateway is a single host (gate.smartproxy.com:7000), but their customers need to express dozens of routing decisions per request — country, city, ASN, sticky session ID, session TTL, and more. The answer everyone landed on is encode it in the username. The proxy auth header becomes a tiny query string.
When you put a provider behind a Nodetonet upstream forwarding tunnel, those modifiers keep working unchanged. Nodetonet does not parse, rewrite or strip the upstream username — it opens a TCP connection to the upstream and sends whatever you saved, byte-for-byte. This guide covers every modifier pattern worth knowing, how to paste them correctly, and how to combine upstream stickiness with Nodetonet's own session layer.
What is a username modifier?
A username modifier is a structured key-value pair appended to your base username, separated by a hyphen, underscore or colon depending on the provider. Collectively they form an instruction set that the provider's gateway reads on every new TCP connection to decide which exit IP to hand you.
The modifier pattern matters because you never change the proxy endpoint itself (host:port stays constant). Instead you embed all routing logic in the credentials, so a single Nodetonet proxy can target dozens of different exit locations just by editing its upstream string. That makes it straightforward to manage large fleets — see bulk proxy operations.
Shape of a modifier-laden username
The general pattern is baseuser-KEY-VALUE-KEY-VALUE.... Here are real examples from the four largest providers Nodetonet customers commonly chain upstream:
| Provider | Example username | What it means |
|---|---|---|
| Bright Data | brd-customer-c_XXXX-zone-residential-country-de-session-abc123 |
Residential zone, exit Germany, sticky session abc123 |
| Smartproxy / Decodo | user-myacct-country-de-session-abc123-sessionduration-30 |
Exit Germany, sticky 30 min TTL |
| Oxylabs | customer-acct-cc-de-city-berlin-sessid-abc123-sesstime-30 |
Exit Berlin, sticky 30 min |
| IPRoyal | myacct_country-de_streaming-1_lifetime-10m |
Exit Germany, streaming allowed, 10 min sticky |
What every example has in common: the base username is recognisable, the rest is parameters the provider's gateway knows how to parse. You don't need to understand the grammar — copy it from your provider's dashboard "Endpoint generator" and paste it as-is.
Where to paste it on Nodetonet
Open your proxy in the Nodetonet panel, scroll to Upstream Proxy, and fill the field in host:port:user:pass format:
gate.smartproxy.com:7000:user-myacct-country-de-session-abc123-sessionduration-30:YOUR_PASSWORDThe colon-separated parser splits only on the first three colons, so even if your provider's username contains colons (rare but possible), URL-encode them as %3A. Hyphens, underscores, and dots all pass through cleanly. The full upstream string is stored encrypted at rest and forwarded verbatim to the provider — Nodetonet never inspects or logs credential values.
If you're unsure what your provider expects, their dashboard's "Endpoint generator" builds the modifier string for you. Paste that output directly — then you know it's syntactically valid before Nodetonet ever sees it.
Country, state and city targeting
Two-letter ISO country codes are nearly universal across providers: country-de, country-us, country-tr. Most providers also accept state- and city- modifiers, though city pools are thinner — if a provider has no IPs in a specific city right now, you'll get a connection error or a silent fallback to country level.
ASN targeting (asn-XXXXX) lets you pick a specific network operator within a country — useful when you need to match a particular mobile carrier or ISP brand. Read more about what an ASN is and why it matters for proxy trust.
For Nodetonet's own geo-targeting modifiers (separate from upstream) — country tags, city tags and carrier selection applied directly to your mobile device pool — see geo-targeting.
Sticky vs rotating on the upstream
The session-XXX modifier tells most providers "give me the same exit IP for a while". As long as the same session ID stays in the username, the same exit IP is returned. Change the ID and the next request picks a fresh IP from the pool — this is the rotating mode.
Some providers also accept a sessionduration value in minutes to extend the default TTL (often 10 minutes). A useful pattern: rotate only the session ID while keeping country fixed, giving you fresh IPs in the same geo on every call:
# Bash — new random session ID per request, country pinned to DE
curl -x "gate.smartproxy.com:7000" -U "user-myacct-country-de-session-$(cat /dev/urandom | tr -dc 'a-z0-9' | head -c8):PASS" https://httpbin.org/ipThis is distinct from Nodetonet's own sticky session layer (the -session-XXXX suffix on your proxy username). The two layers interact: if you append a Nodetonet sticky token, Nodetonet pins the same mobile device to your session; the upstream username that device uses can still rotate or be pinned independently. The interplay is covered fully in sticky upstream sessions.
Editing the modifier without rebuilding the proxy
The upstream string lives in the proxy's edit dialog. Open the proxy, change the modifier, save — the tunnel rebinds in about a second with no re-pairing of devices needed. That makes it practical to update targets programmatically. Using the Nodetonet API:
curl -X PATCH -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"upstream":"gate.smartproxy.com:7000:user-acct-country-us-session-xyz:pass"}' https://nodetonet.com/api/v1/proxies/PROXY_IDThis makes it straightforward to build scripts that rotate the upstream session ID on a schedule or swap the target country without any panel interaction. Pair this with webhook events to notify downstream systems when the exit IP changes.
Troubleshooting: when modifiers stop working
If the provider's gateway returns a 407 or the exit IP isn't in the expected country, work through this checklist:
- Wrong separator. Providers use hyphens, underscores or colons — check their docs. A hyphen where an underscore is expected silently breaks the parse.
- Unknown modifier key. Not all providers support
city-orasn-. Try removing the offending token to see if it unblocks the connection. - Expired session. Most sticky TTLs are 10–30 minutes. If you're seeing the session ID but getting different IPs, the TTL expired and the provider rotated.
- Colon in username. URL-encode as
%3A; the Nodetonet four-field parser splits on colons and a raw colon shifts every field. - Credentials mis-pasted. The upstream field is
host:port:user:pass— four fields. A missing colon sends the entireuser:passblock as the host.
A full walk-through of 407 and connection errors is in debugging upstream auth failures.
Combining upstream with Nodetonet's own controls
When you chain an upstream provider, Nodetonet's per-client controls still apply on top — IP allowlists, domain allow/deny lists, quota limits, thread caps, and expiry dates are enforced before a request reaches the upstream. That means you can hand a client a credential that can only reach traffic through a provider's German residential pool, with a 50 GB monthly quota and domain restrictions, all from one proxy entry. See per-client auth and quota limits for the full setup.
What's next
- Forwarding through a residential provider — the full upstream setup guide.
- Sticky upstream sessions — how Nodetonet's sticky map and the provider's own session semantics interact.
- Debugging upstream auth failures — when 407 starts coming back, this is your checklist.
- What is a mobile proxy? — if you're newer to proxies and want the foundations first.