IP allowlist
Every Developer API key is bound to the addresses it may be called from.
A Developer API key only works from addresses you register against it. This is required — you cannot create a key without at least one — and it is the reason the API key can safely travel in a header on every request.
Why it exists
Authentication here has two factors:
| Factor | What it does | What it defends against |
|---|---|---|
x-api-key | The credential — identifies and authenticates your key | A caller who does not have the key |
| The IP allowlist | Bounds where the key may be presented from | A caller who does have the key |
There is no signature, so the API key on its own is a working credential. The allowlist is what makes that safe: someone who lifts your key from a log, a leaked config or a screenshot still has to be calling from one of your registered addresses. That is why a key in a proxy log is a reason to rotate, not a breach.
An empty allowlist does not mean unrestricted
The dashboard requires at least one address, and Medos also refuses a key that
somehow has none — every request from every address gets a 403. There is no
way to make a Developer API key callable from anywhere, by design.
What to register
The public address your servers go out on — not your office, not your laptop. For most backends that is a NAT gateway or load balancer address, and it is often different from anything you'd find by searching "what is my IP" in a browser.
You can register a single address or a range:
203.0.113.10 stored as 203.0.113.10/32
198.51.100.0/24 a whole /24
2001:db8::1 IPv6, stored as /128Up to 50 entries per key. A bare address is stored as a single-host range, so
everything ends up in the same form. 0.0.0.0/0 is rejected — an allow-everything
range removes the factor entirely.
Check IPv4 against IPv6 before anything else
A dual-stack server often reaches us over IPv6 even when you expected IPv4. If
you registered 203.0.113.10 and your server arrives as 2001:db8::1, it is
refused — the two are unrelated addresses, not two spellings of one.
This is the single most common cause of a 403 on a key that looks correct.
The error names the address we saw, so you can compare directly.
When a request is refused
{
"message": "This API key is not allowed from 203.0.113.9. Add it to the key's allowed IPs.",
"statusCode": 403
}The address in the message is the one that reached us. Either add it, or route
your traffic through an address already on the list. Note this is a 403 — a
429 is the rate limit, which is a different
mechanism that happens to also count by IP.
Running in the cloud
Egress addresses move more than people expect, and this is where the allowlist causes real friction:
- Autoscaling — new instances can go out on new addresses unless egress is pinned. Register the NAT gateway's range rather than individual instances.
- Managed platforms — serverless and container platforms often publish a broad egress range rather than a stable address. Register the range they document.
- Multi-region — each region usually egresses separately. Register all of them.
If you cannot pin egress at all, register the provider's published range. A wide range is weaker than a single address but still far better than nothing — it keeps a leaked credential unusable from outside your provider's network.
Changing the list
The allowlist is set when the key is created and is part of the key. To change it, rotate the key: create a replacement with the new addresses, move your traffic across while both are live, then deactivate the old one.
Always add before you migrate. Register the new addresses on a new key and confirm it works before you move traffic — the reverse order means an outage the moment your egress changes.