Skip to main content

IP rules

Each API key can carry a list of addresses it is allowed — or refused — to be used from. This is what bounds the damage of a leaked key: a key stolen from your office is useless from somewhere else.

Find them under Account Settings → Security → API keys, on the key's IP rules editor.

Two kinds of rule​

Allow rules — if a key has any allow rule, the key works only from those ranges. Everything else is refused. Use this when machines live at known addresses.

Block rules — the key works everywhere except the listed ranges. Use this for roaming machines, where you cannot enumerate the addresses in advance but you can name ones you never expect.

Block wins. Block rules are evaluated first, so an address that is both allowed and blocked is refused.

No rules means no restriction. A key with an empty list works from anywhere.

Write them as CIDR​

Rules are ranges in CIDR notation, IPv4 and IPv6:

203.0.113.0/24
198.51.100.42/32
2001:db8:1234::/48

A single address is a /32 for IPv4, or a /128 for IPv6.

Use a /64 for IPv6, not a single address

IPv6 privacy extensions rotate a machine's address within its /64 prefix, often daily. An allow rule naming one IPv6 address will start refusing the machine as soon as it rotates. Allow the /64 instead.

What the rules apply to​

Registration. A machine registering from an excluded address is refused and does not receive a credential. This is the point of the feature — without it, a key stolen from London would register a machine from anywhere and be handed a working credential.

Machines that already registered with the key. Changing the rules re-checks the machines registered through that key. Any that no longer pass are disconnected immediately, and reconnect attempts are refused while they stay out of range. A refused connection is recorded as a security event — see Security events.

That second point is the one to think about before you save. Tightening the rules on a key can take machines offline within seconds.

Finding an address to allow​

The console shows each machine's reported WAN address on its detail page — except that WAN address collection is not implemented yet, so the field is currently blank. Until it is, use whatever your site reports as its public address.

Remember that most machines share their site's public address, so allowing one machine's address usually allows the whole site.

A worked example​

You run agents in one office and on a handful of laptops that travel.

  • Office key — allow 203.0.113.0/24, the office's public range. A key copied off a machine and used elsewhere registers nothing.
  • Laptop key — no allow rules, since you cannot predict hotel wifi. Add block rules for regions you have no business in if you want a coarse guard.

Two keys rather than one, because a single key cannot be both strict about the office and permissive about laptops.