Token groups — building a rotating proxy pool (complete setup guide)

A single token represents a single paired device: one phone, one cellular exit IP, one tunnel through your panel. That is exactly what you want for a single-device proxy. The moment you need rotation, however, the model breaks down — you cannot spread load, survive a device going offline, or change carrier on a whim with just one token. That is the problem token groups solve.

A token group is a named membership list of tokens. Create one, add N devices to it, and any rotating proxy that points at that group will automatically round-robin (or pick by least-connections) across every device in the bag, apply shared rotation settings, and fail over instantly when a device drops. This guide walks through every step of the setup.

Why token groups exist

Without groups you would have to hardcode individual token IDs every time you create a rotating proxy. Add a new phone? Update every proxy. Retire a SIM? Same. The indirection that groups provide is the same idea as a load-balancer backend pool: proxies point at the group name, the group holds the live membership, and you edit devices in one place.

Groups also carry group-level settings that override per-proxy defaults, giving each pool its own personality:

• Sticky TTL — how many seconds a single client session stays pinned to one device before the router can move it. 0 means rotate every request; a higher value suits stateful flows like logins. See sticky sessions explained for the full picture.
• Selection mode — round-robin distributes sessions evenly; least-connection sends new sessions to whichever device has the fewest active tunnels at that moment. The round-robin algorithm is explained in depth in round-robin device selection.
• Health threshold — minimum success-rate a device must hold to stay in the rotation. Devices that dip below it are temporarily sidelined without manual intervention.
• Failover — if a pooled device goes offline mid-session, the router picks the next healthy member instead of returning an error. The mechanics are covered in automatic failover for mobile proxies.

Step 1 — Create the group

Navigate to Token Groups in the panel sidebar and click + New group. Choose a name that is meaningful to your workflow — scraping-pool-tr, android-fleet-eu, social-accounts. The form returns a group ID and an empty membership list.

If you have not paired any devices yet, do that first on the Tokens page. The end-to-end pairing walkthrough is in your first token and Android pairing. Each Android phone you pair with the Nodetonet agent app becomes one poolable unit.

Step 2 — Add tokens to the group

On the group detail page click Add token. The picker shows every token under your account that is not already in another group (a token belongs to at most one group at a time). Select the tokens you want and save. They immediately flip to POOLED status on the Tokens page, and the group membership count updates.

There is no hard ceiling on group size — you can add as many tokens as you have paired devices. Larger pools mean more exit IPs, higher aggregate throughput, and lower per-device request pressure. If you are running many devices at once, consider reading bulk operations for managing large proxy fleets.

Step 3 — Set the sticky TTL override

By default a rotating proxy uses whatever sticky TTL you configured when creating it. The group can override that value for all proxies pointing at it — useful when you run multiple pools with different session requirements.

On the group settings page, set Sticky TTL to the number of seconds a session should pin to one device:

• 0 — rotate on every new connection request. Best for high-volume crawls where each URL is independent.
• 30 to 300 — short sticky window. Enough for a search-results page with a few pagination requests, but refreshes frequently.
• 600 to 1800 — longer pin, suited to multi-step login and checkout flows that must keep the same exit IP throughout.

Stickiness is per-client, not global. Two scrapers hitting the same rotating proxy simultaneously each get their own pinned session, probably on different devices. You can also force a new session from code by appending -session-XXXX to the proxy username (any random string works as the session key).

Step 4 — Point a rotating proxy at the group

Go to Proxies and click New Proxy. In the type selector choose Rotating (not single-device). The token picker now shows groups instead of individual tokens. Select the group you just created and click Create.

The resulting connection string looks like any other proxy:

http://u8x2:p7q1@sub42.nodetonet.com:48888

but every new client session is dispatched to a different device from the pool. Verify rotation by issuing several requests through different session identifiers:

for i in 1 2 3 4 5; do
  curl -x http://u8x2:p7q1@sub42.nodetonet.com:48888        -H "X-Session: $RANDOM"        https://api.ipify.org
done

The X-Session header is one of the supported rotation signals: it forces a new sticky bucket, so you will see a different exit IP for each value even when requests originate from the same source IP.

Both HTTP/HTTPS and SOCKS5 are supported from the same group, so you can route a browser-based scraper over HTTP and a non-HTTP tool over SOCKS5 to the exact same device pool. See HTTP vs SOCKS5 — which to pick for guidance on when each matters.

Step 5 — Per-client controls on top of the pool

Rotating proxies built from a token group still support all the per-client controls the panel provides. You can create multiple sub-credentials pointing at the same group, each with independent:

• Username/password auth — hand each downstream customer or team a unique credential.
• IP whitelist — only traffic from specific source IPs is accepted; everything else is dropped at the edge.
• Domain allow/deny list — restrict which target hostnames the credential may reach. Covered in domain restrictions.
• Quota and expiry — cap total bandwidth or set a hard expiry date. See quota limits per client and time-limited proxy clients.
• Thread limits — cap concurrent connections per credential. Details in thread limits per client.

This makes token groups the right foundation for reseller and white-label setups: one shared device pool, many isolated client credentials, all managed from one panel.

Step 6 — Geo and carrier targeting through the group

If your pool contains devices across different carriers or cities, you can steer traffic to a specific subset using geo-targeting username modifiers without changing the endpoint. Append a country tag, city tag, or carrier name to the proxy username, and the router will only consider pool members that match.

For example, to request only a Turkcell exit from a multi-carrier Turkish pool, use a modifier like -carrier-turkcell in the username. The same works for Vodafone, Turk Telekom, or a specific city such as Istanbul. Devices that do not match are silently excluded from selection for that request.

Programmatic group management

Everything available in the panel is also available over the REST API. The examples below use curl but the calls translate to any HTTP client:

# List all token groups
curl -H "Authorization: Bearer $KEY"   https://nodetonet.com/api/v1/token-groups

# Create a new group
curl -X POST -H "Authorization: Bearer $KEY"   -H "Content-Type: application/json"   -d '{"name":"scraping-pool-tr"}'   https://nodetonet.com/api/v1/token-groups

# Add a token to a group
curl -X POST -H "Authorization: Bearer $KEY"   -H "Content-Type: application/json"   -d '{"tokenId":"<tk_id>"}'   https://nodetonet.com/api/v1/token-groups/<id>/tokens

# Remove a token from a group
curl -X DELETE -H "Authorization: Bearer $KEY"   https://nodetonet.com/api/v1/token-groups/<id>/tokens/<tk_id>

For a broader overview of the API surface, start with REST API — your first call.

When to use a group vs a single token

What to read next

• When to actually use a rotating mobile proxy — and when a single-device setup is the better answer.
• Sticky sessions explained — every setting that affects how long a session pins to one device.
• Automatic failover for mobile proxies — how the panel handles a device going offline mid-session.
• Proxy clients and per-customer auth — how to issue isolated credentials on top of a shared pool.
• Token rotation — when and why — when to rotate the token itself, not just the exit IP.

Ready to build your first pool? Create a free account, pair your first Android device, and group it in minutes.