Skip to content
Faturei Hoje API

Allowed IPs

The allowed IP list is a per-key lock: only a caller arriving from an address on the list authenticates. An empty list accepts any IP.

It is the easiest lock to turn on and the one that most often takes an integration down with nobody understanding why. This page exists so you can decide with clarity.

When to use it

Section titled “When to use it”

Use the list when the outbound address of the caller is fixed and under your control:

  • a dedicated server or a virtual machine with its own IP;
  • egress through a NAT gateway with a fixed address;
  • your own proxy in front of the integration.

Do not use the list when the caller is a serverless function, an autoscaling container, managed hosting, an office computer on a residential link or one person’s machine. In those cases the address changes without notice.

The list does not replace taking care of the key. It limits the damage of a leaked key, because the key alone stops being enough.

Which address the API compares

Section titled “Which address the API compares”

The address the call arrives from. In practice it is the outbound IP of the server making the call, not the IP of your end user and not your office network, unless the call goes out from there.

When the call comes through our edge, the address considered is the one the edge reports as the origin. When it arrives directly, it is the address the server sees on the connection.

If the API cannot determine the address with confidence and the list is not empty, the call is refused. A key without a list is not affected by this.

Accepted format

Section titled “Accepted format”

Each key accepts up to 20 entries, IPv4 and IPv6, a bare address or a range:

198.51.100.7
198.51.100.0/24
2001:db8::1
2001:db8::/32

A bare address means that exact machine (/32 on IPv4, /128 on IPv6).

IPv4 and IPv6 live in the same list. If your server goes out sometimes through one and sometimes through the other, both addresses have to be there.

The mask is applied on save

Section titled “The mask is applied on save”

If you type 203.0.113.5/24, the entry is stored as 203.0.113.0/24, because that is what the range means. The comparison always looked at the prefix bits only; storing the address as typed made the screen say one thing and the effect be another.

The panel shows the normalised value. What is on screen is exactly what applies. If the address came out different from what you typed, that was the mask.

Entries that become the same value after normalisation count as one.

An invalid entry does not get through

Section titled “An invalid entry does not get through”

An entry outside the format is neither accepted nor silently dropped: the form refuses the whole change. Dropping it silently could empty the list, and an empty list allows any IP.

How to edit the list

Section titled “How to edit the list”

Under the key menu, in Edit name and IPs. The form asks for your password, and only the OWNER and ADMIN can edit. Editing widens access, because clearing the list allows any address, so the action requires the same role as issuing the key.

The list you save replaces the previous one in full. To add one address, save the complete list with it included.

The OWNER and ADMIN get an email about the change.

When the call is refused

Section titled “When the call is refused”

A call from an address outside the list gets the same 401 of an invalid key. The response does not say the reason was the IP, on purpose: a different response per reason would tell someone testing keys at random when they got the key right and only missed the address.

The panel is what tells you. The attempt shows up under View usage, with the address that arrived and the time.

Checklist for when the integration stops with 401 and the key has a list:

  1. Open View usage on the key and read the address of the refused call.
  2. Compare it with the list, already normalised, on the key screen.
  3. If it is an address of yours you did not know about, add it. If it is not yours, revoke the key and follow Key best practices.

If no line shows up under View usage, the problem is not the IP: the API did not get as far as recognising which key it was. The full 401 checklist is in Authentication.

Next step

Section titled “Next step”