A Nodetonet token is the credential that lets a paired phone or PC connect into the platform as a proxy exit. It is also, naturally, a secret — anyone who holds it can stand up an agent on their own hardware and impersonate your device. So at some point you will need to rotate a token: invalidate the old one and issue a fresh secret to the same (or a replacement) device.
This guide covers every rotation trigger you are likely to encounter, what the rotation operation does on the wire, a quick comparison of your options, and the exact procedure for the worst case — "the device is gone and I can't touch it."
What is a Nodetonet token?
When you add a device to Nodetonet, the panel creates a token — a unique string that the Android agent app or the Windows .exe agent presents at connection time. The platform validates it, associates the connection with your account, and begins routing proxy traffic through that device's cellular or network connection.
Tokens are long-lived by default. That makes setup easy, but it also means a leaked token stays dangerous until you act. Rotation is how you act.
To understand what the token is protecting, see our post on what a mobile proxy is and how your first token and Android pairing works from day one.
When should you rotate a token?
There is no universal timer, but the following events should trigger an immediate rotation:
| Trigger | Risk level | Action |
|---|---|---|
| Token string exposed (Slack, screenshot, Git commit) | Critical | Rotate immediately |
| Team member with panel access left the organisation | High | Rotate all tokens they could read |
| Device stolen, lost or unaccounted for | Critical | Rotate (or delete) immediately |
| Device behaving abnormally — suspected malware | High | Rotate, factory-reset, re-pair |
| Routine hygiene (90-day policy) | Low | Rotate on schedule |
| Handover to a new operator or reseller | Medium | Rotate before handing credentials |
If you are a reseller running a white-label panel, a rotation policy is especially important — treat each customer's token as their own secret, and rotate on any access change. See the reseller and white-label overview for context.
What rotation actually does
Go to /tokens, find the row, and hit Rotate. In sequence the platform:
- Generates a new cryptographically random token string and writes it to the database in a single atomic transaction. The old string is immediately invalidated — there is no grace period.
- Sends a revocation message on the existing WebSocket connection to the agent: the device is told to disconnect.
- The agent disconnects within a second. The token row flips to
OFFLINE. - Any rotating proxy whose token group contained that device skips it in pool selection. Single-device proxies tied to the old token enter an error state until re-paired.
- The panel shows the new token string exactly once, in a modal. Copy it before closing.
Rotation is instant from the panel's perspective. If the device was offline at the moment you rotated, the revocation is enforced the next time it tries to connect — it will never get back in with the old string.
After copying the new token, open the agent on the paired phone or PC, replace the old token with the new one, and reconnect. Any proxies dependent on that token resume within seconds. If you manage many devices, see bulk operations for scripting approaches.
Rotate vs Delete — which to choose?
Rotation keeps the token row (and all proxy configurations that reference it) while swapping the secret. Deletion removes the row entirely.
- Rotate when you plan to re-pair the device — the same phone, freshly reset, or the same PC with the agent reinstalled. All proxy and group settings survive.
- Delete when you are writing off the hardware entirely and have no plan to re-pair. Dependent proxies are detached automatically; clean up proxy configurations afterward. See automatic failover to understand how rotating pools recover from a missing member.
The "device is stolen" procedure
This is the scenario rotation was built for. You cannot reach the phone; you do not want the thief running your proxy exit. Act in this order:
- Open the Tokens page and hit Rotate on the stolen device's row. The edge server force-disconnects the agent on the stolen device. The old token is permanently dead — it cannot reconnect.
- Check Audit logs and filter by the token ID. Look for suspicious traffic in the hours before you noticed the loss. If the device was used to route requests against your clients, you will see it here. Our post on audit logs explains how to read the output.
- Decide whether to re-pair a replacement device (Rotate path) or retire the slot entirely (Delete path).
- If the token group that contained the stolen device is used for a customer-facing proxy client, verify that client still has live devices in its pool — check its online member count before the customer notices degraded service.
Doing rotation from the API
Both rotation and deletion are available via the REST API, useful for automated hygiene scripts:
# Rotate — keeps the token row, replaces the secret
curl -X POST -H "Authorization: Bearer $KEY" https://nodetonet.com/api/v1/tokens/<id>/rotate
# Delete — removes the token row and detaches dependent proxies
curl -X DELETE -H "Authorization: Bearer $KEY" https://nodetonet.com/api/v1/tokens/<id>For scripting first steps, see your first REST API call. If you issue tokens to customers rather than operating devices yourself, read customer API tokens vs personal for the scoped-token model that limits blast radius on any single rotation.
Preventing token leaks in the first place
- Never paste token strings into shared channels. Use environment variables or a secrets manager in any automation that needs the token.
- Scope access by role. Only accounts that genuinely need to read tokens should have operator-level panel access. Read-only roles cannot extract token strings.
- Audit on offboarding. Make a team-member departure checklist: rotate every credential they had access to on their last day, not a week later.
- Use IP allowlists. Restricting which IPs can present a token does not replace rotation, but it narrows the window an attacker has to use a leaked string. See IP allow/deny lists.
Get started
Token rotation is available on all plans at no extra cost — it is a core part of credential hygiene. If you haven't already, create your free account, explore the full feature set, and check the proxy glossary for any concept above. Questions? Reach the team at support@nodetonet.com or on Discord.