Proxy Authentication: Credentials, IP Whitelist, API Keys

Credentials or a whitelisted address for the proxies, an n4k_ key for the REST API: what each mode does and how to avoid crossing them.

node4 runs two separate authentication systems, and most of the confusing failures we see trace back to feeding one system the other's secret. The proxies decide whether to carry your traffic based on either a username and password or the address your connection arrives from. The REST API (the thing you script against to list proxies, read usage, or manage your account) ignores both of those and wants an API key in a header. This guide covers each mechanism in turn, then the ways they get crossed.

Proxy authentication: two modes, and which products take each

Before a proxy carries a single byte for you, it has to recognize you. There are two ways of doing that, and only one of them works everywhere:

Whitelisting applies to every product: the static datacenter products (shared and dedicated), all three rotating gateways (shared, premium and unmetered) and the residential gateway.

On rotating there are two ways to use it. Send no credentials at all and you get an untargeted exit. Or send your username with an empty password: the username is where your country, city and sticky-session controls are carried, so this keeps your targeting while leaving the secret out of config files and shell history.

The residential gateway takes whitelisting too, with one difference. There you must send no username and no password at all, and what you get back is an untargeted exit that rotates freely across the pool. Targeting rides in the username on residential, so there is no empty-password halfway option the way there is on rotating: any request that pins a country, city or session authenticates with credentials.

On the products where both apply, the important word is or. These are alternatives, not layers. You pick whichever fits a given workflow, and nothing about the service expects you to combine them. A connection presenting valid credentials is carried no matter where it originates; a connection presenting none is carried only if its source address is on your list. When neither condition holds, the proxy answers 407, and the full diagnostic walkthrough for that error lives in fixing 407 errors.

Mode one: username and password

This is the default, and the right choice for most setups. The secret travels inside the request, so it works identically from your laptop, a cloud server, a CI job, or a machine that did not exist five minutes ago.

curl -x http://USERNAME:PASSWORD@HOST:PORT https://api.ipify.org

Mechanically, your client encodes the pair into a Proxy-Authorization header. For plain HTTP requests that header rides on the request itself; for HTTPS it is sent during the CONNECT handshake with the proxy, before any encrypted traffic flows. Either way the credential is consumed at our edge; the target website never sees it and cannot log it.

The strength of this mode is portability. Its cost is that you now hold a secret, and anyone who obtains it can spend your metered bandwidth from anywhere on earth until you change it. Treat a proxy credential with the same care as a database password: keep it in environment configuration rather than source code, and prefer copy-paste over retyping, since a transcription error produces the same 407 as a revoked login.

Credentials belong to a product, not to your account

There is no single account-wide proxy password. Every product you hold (shared datacenter, private datacenter, any rotating gateway tier, residential) displays its own username and password pair on its own row of the Proxies page in the dashboard. A pair authenticates only against the product it was issued for; presenting your residential login to a datacenter endpoint fails exactly as if the password were wrong, which makes this the most misleading 407 of them all.

A free account is issued 1 credential pair. Paid accounts can hold up to 5, which is worth using: separate pairs for separate machines or teammates mean you can revoke one without interrupting the others.

On the gateway products the username carries extra duty as a control channel. Targeting instructions (a country, a city, a sticky session) are appended to it as hyphen-separated segments, so two usernames that differ only in their suffix reach very different exits. The grammar is documented in country and city targeting; get a segment wrong and the whole username stops matching.

Mode two: IP whitelisting

Under Auth & IP Access you can store the public address your machines call out from. From then on, connections arriving from a stored address are accepted with no login attached at all.

Two situations make this attractive. Some software genuinely struggles to send proxy credentials: legacy tools, certain embedded environments, applications whose proxy support was an afterthought. Whitelisting sidesteps the problem entirely. And removing the secret removes the ways a secret goes wrong: nothing to leak into a repository, nothing to rotate, nothing to mistype.

The trade is that your network's outward-facing address becomes the key, and addresses are less stable and less private than they appear. A whitelist entry authorizes everyone who shares that address, and consumer connections change addresses without asking you. A free account gets 1 whitelist slot; paid plans include 3. The operational realities (rotating home lines, CI runners, containers behind NAT) are a subject of their own, covered in IP whitelisting best practices.

Picking a mode

A reasonable default: use credentials everywhere, and switch a specific workflow to whitelisting only when both of these are true: the traffic leaves from an address you control and expect to keep (a dedicated server, an office line with a static allocation), and there is a concrete reason credentials are awkward there. Never whitelist an address you merely happen to have today, such as a hotel network, a shared CI pool, or a home line without a static-IP arrangement.

The REST API: a different lock entirely

Everything above concerns the data path, traffic through the proxies. node4 also has a management plane: a REST API for automating what the dashboard does by hand, mounted at https://node4.io/api/v1. It does not accept proxy credentials, and proxies do not accept API keys.

You create keys under Settings → API Keys. Every key begins with the prefix n4k_, and the full value is shown exactly once, at creation. After that the dashboard retains only a short identifying fragment, so copy the key into your secret storage at the moment you mint it. Send it as a bearer token:

curl -H "Authorization: Bearer n4k_YOUR_KEY_HERE" \
  "https://node4.io/api/v1/proxies"

Two corrections to older documentation. Earlier versions of this article gave the API base as https://api.node4.io/v1/. That hostname does not resolve; code written against it fails at DNS before authentication is even attempted. The API lives on the main domain at the path shown above. Those versions also described a rate limit that varied by plan tier; no such tiers have ever existed in the service.

The rate limit is flat

Every key is allowed 60 requests per minute, and that number is the same for every account: free, paid, anything. Upgrading a plan buys proxies and bandwidth; it does not buy API throughput. Exceeding the allowance returns 429, and the correct response is to back off rather than retry immediately. If you find yourself pressed against the ceiling, you are almost always polling something that changes rarely: cache proxy lists and subscription state instead of re-fetching them each cycle.

Scopes limit what a key can do

At creation you choose the key's permissions, and requests outside them are refused with a 403 naming the missing scope:

Grant only what the integration uses. A read-only monitoring script holding write scopes is pure downside: no extra capability on a good day, much more damage on a bad one. The full endpoint catalog lives in the proxy management API reference, and the operational side of holding keys (storage, rotation, what to do when one leaks) is covered in API key security.

When the systems get crossed

Because the three secrets look superficially similar (opaque strings you paste into configuration), they end up in each other's slots constantly. The failures are consistent, so you can usually read the mistake straight from the symptom:

None of these errors explain themselves, by design: an authentication layer that describes exactly what almost worked is a gift to whoever is probing your account. Keeping a note of which secret belongs to which system is cheaper than rediscovering it from a terse status code.

If you are still deciding what to authenticate to, the features overview maps the product line, and the free tier described on the pricing page provisions 3 free shared proxies with 1 GB/month bandwidth and 10 concurrent threads, enough to exercise both proxy modes and the API against a real workload before anything is paid for.