API key IP whitelisting

A leaked API key works from any network. An IP whitelist limits the key to addresses you control, such as an office NAT, a VPN egress, or a server.

Create and assign the whitelist in the IP Whitelisting tab. For when the control helps, and when it blocks your own traffic, see When to use IP whitelisting.

Create a whitelist

1. Open the IP Whitelisting tab.
2. Start a new whitelist.
3. Enter a Name, such as production-egress.
4. Add each IPv4 or IPv6 address as its own row.
5. Assign the whitelist to specific keys, or apply it account-wide.
6. Leave Enabled on if you want the restriction to start after you save.
7. Select Create whitelist.

The dashboard stores each row as an exact host. It does not accept CIDR ranges. If you need a range, contact support.

You cannot enable an empty whitelist. You also cannot assign it or apply it account-wide.

To edit a whitelist later, open it and select Save whitelist. Changes take effect within two minutes.

The Dwellir CLI cannot create or assign IP whitelists.

Apply account-wide or per key

Select Apply account-wide to all current and future API keys if every key in the account should inherit the whitelist. New keys get the same restriction when you create them.

To cover only some keys, leave that checkbox off. Then pick those keys in Assigned API keys.

If you assign more than one whitelist, a request is allowed when the source IP matches an address on any of them.

If you turn account-wide off later, inherited assignments go away. Manual per-key assignments stay.

Delete a whitelist to remove it from the keys that used it.

How enforcement works

A key stays unrestricted by IP until it has at least one enabled assignment to an enabled whitelist.

After that, the requester IP must match at least one enabled entry from those whitelists.

A disabled whitelist does not restrict traffic. A disabled assignment does not restrict traffic.

Dwellir checks the source IP before body parsing, usage accounting, rate limiting, and routing. Blocked requests never reach a node. They do not count toward usage, quotas, or rate limits.

The API key table shows the state:

• Unrestricted means no policy applies.
• Inactive policy means the assigned whitelist is disabled.
• The whitelist name means the policy is active.

What a blocked request looks like

HTTP, WebSocket, and gRPC-Web denials return HTTP 403. Native gRPC denials return PermissionDenied. WebSocket denials happen on the upgrade request.

Every protocol uses this message:

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

Unrelated 403 responses stay generic. Only this denial links to the IP Whitelisting tab.

Add observed source IPs

The create and edit dialog lists source IPs seen in the last 30 days. Each row shows a request count and how many keys saw that IP.

If you add an observed IP, the dashboard creates an exact-host entry. It never adds those addresses on its own. Confirm the address belongs to you before you add it. A leaked key puts someone else's address on that list too.

The list shows recent source IPs for your keys. It may not include every request. Treat your own inventory as the source of truth.

Before you enable it

An incomplete list blocks your own production traffic. Inventory every address that uses the key before you enable a whitelist on a live key. Include every NAT gateway, every region, and both IPv4 and IPv6. Test the policy on a second key first.

• Browser and mobile clients cannot be whitelisted. Whitelist the backend that proxies their requests instead.
• Dynamic egress breaks the list. Autoscaling workers, serverless platforms, and consumer ISP connections change addresses. Route them through a fixed egress, or leave those keys unrestricted and bound by a quota.
• IPv6 counts separately. A host that reaches Dwellir over IPv6 needs its IPv6 address on the list even when the IPv4 address is already there.
• If your own proxy sits in front of Dwellir, Dwellir sees the proxy. Do not rely on a client-supplied X-Forwarded-For header.

If a key already leaked, restrict it first, then rotate it. An IP whitelist limits where an old key still works. It does not replace rotation.

Troubleshooting

Related pages

• When to use IP whitelisting
• API authentication
• Rate limits
• API key management