When to use IP whitelisting on your Dwellir API keys

Most teams turn on IP whitelisting for one reason: a key leaked, or they read about someone else's leaking, and they want the next leak to be harmless. That is the headline case, and it is a good one. But it is not the only reason, and a few of the others are more useful day to day than the security story.

This guide goes through the situations where restricting a Dwellir API key to known source addresses pays off, the situations where it will just block your own traffic, and how to combine it with the other per-key controls. For the mechanics of creating and assigning a whitelist, see the API key IP whitelisting.

What you will learn

• Why a whitelisted key is worth less to an attacker than an unrestricted key with a quota
• How whitelisting stops a leaked key from burning your usage before you notice
• Ways to use per-key whitelists to keep staging traffic off production keys and partner traffic on partner keys
• How the suggested source IP list doubles as a leak detector, even before you enforce anything
• Which workloads cannot be whitelisted, and what to do for those instead

Prerequisites

• A Dwellir account with at least one API key at dashboard.dwellir.com/api-keys
• A rough inventory of where your requests come from: NAT gateways, VPN exits, office ranges, or fixed worker hosts

How the control works

A whitelist is a named list of source addresses. You assign it to a key, and from then on that key only works from addresses on the list. Everything else gets an HTTP 403 with a message that names the rejected address. Dwellir performs this check before body parsing, usage accounting, rate limiting, and routing, so blocked requests never touch a node and never count against anything. A key with no active whitelist is unrestricted. That last point matters later: whitelisting is opt-in per key, so you can be selective about where you apply it.

Reason 1: A leaked key stops being a working key

API keys leak through boring channels. A .env file gets committed and force-pushed away, but the key is still in the reflog. A CI job prints its environment on failure. A Docker image with a baked-in key gets pushed to a public registry. A contractor's laptop is wiped a year after the engagement ended, with the key still in a shell history.

An unrestricted RPC key is immediately useful to whoever finds it. RPC access has resale value, and scanners look for exactly this pattern in public repositories. With a whitelist in place, the same key returns a 403 from every address you did not list. The finder learns your account exists and nothing else.

This does not mean you can skip rotation. It means the gap between a leak and your discovery of it is no longer a window of free usage on your bill. Disable or delete the exposed key, create a replacement, and move traffic over, in that order. The CLI key management page has the commands for scripting that.

Reason 2: Abuse cannot consume your quota or your rate limit

Compare two keys that both leak. One has a daily quota. One has a whitelist.

The quota key still serves every request the attacker sends until the quota is exhausted. You have bounded the cost, but you have also handed the attacker your entire daily allowance, and once it is gone your own traffic receives 429s until the reset. On a busy day you find out about the leak because production stops.

The whitelisted key rejects the attacker's requests before accounting. Nothing is consumed, nothing is rate limited, and your traffic is unaffected. You find out about the leak when you look at the suggested source IP list and see an address you do not recognize, or when you never notice at all, because it did not cost you anything.

Both controls have a place. The quota is a ceiling on what a key can ever consume, which protects you from your own bugs as much as from attackers. The whitelist is a fence around who can consume it. On a production key, use both.

Reason 3: Staging traffic stays off production keys

Once a team has more than one environment, keys drift. Someone copies the production key into a staging config because it was the one in their clipboard. A load test that was meant to hit staging hits production. A developer runs the integration suite from a laptop with the wrong environment file sourced.

Per-key whitelists make these mistakes fail loudly instead of silently succeeding. Assign a production-egress list to the production key and a staging-egress list to the staging key. A production key used from a staging host returns a 403 naming the staging address, and the person reading the error knows within seconds what they did. Without the whitelist, that same mistake shows up weeks later as an unexplained bump on the production usage graph.

This is the reason most teams end up keeping whitelisting on after a leak scare has faded. It is an environment guardrail as much as a security control.

Reason 4: Partner and contractor keys are scoped to the partner

If you hand a key to an agency, an integration partner, or a contractor, you want it to work from their infrastructure and nowhere else. Create a key for the engagement, create a whitelist with the addresses they give you, and assign one to the other.

Two things fall out of this. First, the key cannot be repurposed. If the partner's engineer keeps a copy, it does nothing once they are off the partner's network. Second, offboarding is a list edit. Remove their addresses, or delete the key outright, and you never have to wonder where else the key ended up.

The same pattern works for internal platform teams that hand out keys to other teams. An account-wide baseline whitelist covering the company's egress ranges means every new key starts out restricted to company infrastructure, and per-key assignments narrow it further where that is warranted.

Reason 5: The suggested source IP list is a free audit

The whitelist editor shows every source address that has used your organization's keys over the last 30 days, ranked by request volume, with a count of how many keys each address touched. You do not have to enable enforcement to read it.

Open that list once and check every address against your inventory. Addresses you recognize become whitelist entries. Addresses you do not recognize are either infrastructure you forgot about, which is worth knowing, or someone else using your key, which is worth knowing more. Either way, you have learned something about your traffic that usage graphs do not show.

Treat suggestions as observations, not endorsements. A leaked key means the attacker's address appears in that list too, sorted by however much they have been sending. Do not click "add" on anything you cannot place.

Reason 6: Compliance asks for it

Security questionnaires and audit frameworks regularly ask whether third-party credentials are restricted at the network level. Being able to answer "yes, every production key is bound to our egress addresses, and here is the per-key policy in the dashboard" is easier than explaining compensating controls. The API Keys table shows the active policy on each key, which is the screenshot an auditor wants.

When not to whitelist

Whitelisting assumes the source address is stable and yours. Two common workloads break that assumption.

Browser and mobile clients. Every end user connects from their own address. You cannot list them, and you should not be shipping a key to them in the first place. Put a backend in front of Dwellir, whitelist the backend, and see API authentication for keeping keys out of client code. If a key must be exposed directly, give it its own strict quota and rotate it on a schedule.

Dynamic egress. Serverless functions, autoscaled workers without a NAT gateway, consumer ISP connections, and developer laptops all change addresses without warning. A whitelist on those keys will block real traffic the first time an address rotates. Either route them through a fixed egress point, or leave those keys unrestricted and bound by a quota.

Two more that catch people out. A host that reaches Dwellir over IPv6 needs its IPv6 address listed, even when its IPv4 address already is. And if your own proxy sits between the caller and Dwellir, Dwellir sees the proxy's address, not the caller's, so list the proxy.

Pick the right control per key

Turn it on safely

1. Read the suggested source IP list and reconcile it against your inventory.
2. Create a whitelist with only the addresses you can place.
3. Create a throwaway key and assign the whitelist to it.
4. From inside your network, confirm a request succeeds:

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "X-Api-Key: ${DWELLIR_TEST_KEY}" \
  -H "Content-Type: application/json" \
  https://api-ethereum-mainnet.n.dwellir.com \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

5. From outside it, confirm the same request returns a 403 whose body names the rejected address:

Request blocked: source IP 203.0.113.7 is not whitelisted for this API key. Review or update IP whitelisting at https://dashboard.dwellir.com/api-keys?tab=ip-whitelisting.

6. Assign the same whitelist to the key that serves production. Changes take effect within two minutes.
7. Alert on 403 responses that carry the source-IP message. After rollout, each one is either a new egress address you forgot, or a key being used from somewhere it should not be. Both are worth a page.

A 403 without that message is not a whitelist denial. Check the key and the endpoint entitlement instead.

Related pages

• API key IP whitelisting
• API authentication
• Rate limits
• API key management