Understanding your personal API key — scopes, rotation and what not to do

Every Nodetonet account ships with one personal API key — a single string that authenticates every automated request you make to the platform. Hand it to curl, Postman, a scraper, or any backend script and it can list, create, modify, or delete every proxy and token under your account. Think of it as a password that never expires unless you rotate it. This guide covers where to find it, exactly what it can and cannot do, how rotation works, and the habits that keep it out of trouble.

TL;DR: treat the personal key like a root password — store it in an environment variable, never commit it to git, rotate it the instant you suspect a leak, and issue scoped customer tokens to anyone else who needs API access.

Where the key lives

Open your dashboard. The Personal API Key card sits near the top right. Click the eye icon to reveal the string — it looks like ntn_live_a8c3...f2e1, roughly forty characters with a recognisable prefix that makes it easy to spot in logs or grep output. Click the copy icon to put it on your clipboard without ever displaying it in full on screen.

You can also reach it at /tokens, where you will also find the Rotate button and a log showing every previous rotation — including the timestamp and the originating IP address.

What the key can and cannot do

Send the key as Authorization: Bearer YOUR_KEY on any request to /api/v1/*. There are no per-endpoint scopes on the personal key — it has full account access. Specifically it lets you:

• List, create, modify and delete mobile proxies, rotating proxy groups, and SOCKS5 / HTTP proxies
• List, create and revoke device pairing tokens
• Read live device status (online / offline, last seen, carrier)
• Read billing history and current prepaid balance
• Create and revoke customer API tokens — the scoped credentials you hand to downstream consumers (see below)
• Configure geo-targeting modifiers, IP allow/deny lists, and per-client quotas

There are a handful of things the key cannot do by design: it cannot change your account password, change the billing email, or trigger an off-session card charge. Those operations require an active browser session with a fresh login — a deliberate gate that limits the damage if the key is ever stolen.

Personal key vs customer API tokens — choosing the right credential

The personal key is powerful but broad. If you resell proxies through WISECP white-label or expose an API to any third party, you should never share it. Instead, go to /api-tokens and mint a customer API token. The table below shows how the two credentials differ:

A useful mental model: the personal key is your root password, customer tokens are the API user accounts you create for everyone else. Read the full comparison in personal API keys vs customer tokens.

How rotation works — and why it is instant

On the dashboard API Key card, the Rotate button does exactly one thing: it generates a new 40-character key and immediately invalidates the previous one. There is no grace window, no overlapping validity period — the old key returns 401 Unauthorized on the very next request, even if that request is already in flight.

If you suspect a leak, rotate first, patch your scripts second. A few minutes of broken automation is a far smaller cost than someone draining your prepaid balance or listing your devices.

After rotating, update the value in every service that holds it — environment variables in CI/CD, secrets managers, .env files on your servers — then redeploy. The rotation log at /tokens keeps a permanent record: every rotation timestamp and the IP that issued it, so you can audit whether a rotation you did not initiate has occurred.

Calling the API: a minimal example

Once you have the key, your first call can be as simple as listing your proxies. The endpoint is GET /api/v1/proxies and the only required header is Authorization:

curl -s https://app.nodetonet.com/api/v1/proxies   -H "Authorization: Bearer ntn_live_YOUR_KEY_HERE"

The response is a JSON array of proxy objects. For a full walkthrough including creating a proxy, checking device status, and reading balance, see your first REST API call. If you want to drive the same operations from Python, see programmatic tunnel creation in Python.

Five rules to keep the key safe

1. Never commit it to git. Put it in .env, add .env to .gitignore, and use a secrets scanner in CI. If a commit does slip through, rotate the key immediately — public repositories are indexed within seconds.
2. Never paste it into public places. Stack Overflow answers, screenshots, screen recordings, Slack channels, support tickets — use a placeholder like $NTN_KEY or redact it before sharing. Even "private" channels can be screenshot and leaked.
3. Do not ship it inside browser extensions or mobile apps. Anything that runs client-side is essentially public. Build a small backend that holds the key and exposes only the narrow endpoint your front-end needs.
4. Rotate on a schedule — at least quarterly. Put it in your calendar. Even without a known leak, the cost is one redeploy; the benefit is that a silent, unknown leak stops working.
5. Use customer tokens for all downstream consumers. Their blast radius is bounded to the proxies you attach them to, they carry optional quotas and expiry dates, and revoking one never touches your own automation. See per-customer auth for the full pattern.

Storing the key safely in common environments

Here are the canonical approaches for the most common environments:

• Local development: .env file loaded by dotenv (Node) or python-dotenv. Never committed; listed in .gitignore.
• Docker / container: pass as an environment variable at runtime (docker run -e NTN_KEY=...), never bake it into the image layer.
• CI/CD (GitHub Actions, GitLab CI): store as an encrypted secret in the platform's secret store; reference it as secrets.NTN_KEY in workflow YAML files.
• Cloud functions (AWS Lambda, Cloudflare Workers): use the provider's secret manager (AWS Secrets Manager, Workers Secrets) and inject at runtime.

Whichever environment you use, the pattern is identical: the key lives in a secret store, reaches the process as an environment variable, and never appears in source code or container image layers. You can verify your proxy connection is working with our free proxy checker tool after any reconfiguration.

What to do if the key is compromised

1. Rotate it immediately via the dashboard or POST /api/v1/account/rotate-api-key.
2. Check the rotation log at /tokens for any rotations you did not initiate.
3. Review your billing history for unexpected usage or balance changes.
4. Audit any customer tokens that were created during the exposure window — revoke any you do not recognise.
5. Update the key everywhere it is stored and redeploy.

For questions or if you believe your account has been accessed without authorisation, reach the team at support@nodetonet.com or Discord.

Next steps

• Your first REST API call — list proxies in five lines of curl.
• Customer API tokens vs personal key — when to use which.
• Per-customer proxy auth — issue scoped credentials to reseller clients.
• All Nodetonet features — see the full platform at a glance.