How do I restrict API access to specific IP addresses?

You can limit which computers may call the Smoobu API with your account's keys by adding their public IP addresses to an allow list, often called an IP whitelist. Once the list has at least one entry, a request from any other address is rejected, even when its API key and signature are correct. The list is optional and adds a second layer on top of request signing. It is available on every Smoobu account with API access. You manage it yourself under Advanced, then API Keys.

Before you start

You need all of these before the list is worth setting up:

• Direct API access. This is for your own scripts, a custom integration, or an internal tool where you pasted your API key yourself. See use the Smoobu API and webhooks for getting a key and signing requests.
• Fixed public IP addresses. The list only works well when your requests come from a small, stable set of machines, such as a rented server, an office connection with a static IP, or a cloud instance with a reserved address.
• Signed requests already working. The whitelist does not replace signing. A request from a listed address still has to carry a valid timestamp, nonce and signature.

Tools you connected through the Smoobu Marketplace, such as a pricing tool or a check-in tool, are not affected by this list. Smoobu arranges any address restriction for those integrations directly with the partner, so there is nothing for you to set up.

If your integration runs from addresses that change often, for example serverless functions, a laptop on changing connections, or cloud workers without a fixed outbound address, leave the list empty and rely on signing alone. A list that keeps going out of date blocks more of your own requests than it protects.

An empty list means no restriction

The list is checked on every request made with any of your account's API keys, and it only takes effect once it has an entry:

• Empty list: every request is accepted from any address. This is the default.
• One or more entries: only requests from the listed addresses are accepted. Everything else is rejected.

There is no switch to block everything or allow everything. The protection comes entirely from the entries you add, so add every address you need. There is one list per Smoobu account, and it covers every current API key on that account, so you cannot restrict one key while leaving another open.

The whitelist does not apply to legacy API keys, only to current-generation API keys. If you are still using a legacy key, adding your IP address to this list has no effect on it.

Smoobu checks the address before it checks the signature. A request from an address that is not on the list gets a plain 401 Unauthorized response that does not mention the address. This is deliberate, so nobody can probe the list from outside. It also means that when your signing code has not changed and every request suddenly returns 401, your address is the first thing to check.

What you can add

Each entry can carry a short description, for example "Office server, Berlin", so you recognise it later.

Only add a range you fully control. A wider range than you need weakens the protection you are setting up.

Steps

1. Find the public IP address your integration uses for outgoing calls. It is often not the local address your machine reports to you. The reliable way is to send a request from the same machine and connection your integration uses and read the public address it reports back.

2. In Smoobu, open Advanced, then API Keys.

   

3. In the IP whitelist section, enter the address or range, add a short description, and save the entry.

   

4. Repeat step 3 for every machine, replica, scheduled job, and test or staging environment that calls the API. Add them all in one go, because your first entry immediately starts blocking every unlisted address.
5. Send a normal signed request from a listed machine and confirm it returns a normal (200) response.
6. If you can, send one from an address you did not list and confirm it returns 401 Unauthorized. That second test is what proves the list is working.

Changes take effect straight away. You can remove an entry at any time, and removing the last entry returns you to the default, where every address is accepted again.

Common problems

All of your requests started returning 401 at once

If every request fails at the same moment and your signing code has not changed, check your connection before your code. Outbound addresses change more often than people expect: an internet provider reassigns your address, you move to a new server or cloud region, or the network at your office changes. Look up your current outbound address and add it to the list. If you need the integration running again immediately, remove all entries to lift the restriction while you sort it out.

Some requests work and others do not

Requests are coming from more places than you listed. Typical causes: a second machine, replica, or scheduled job runs from a different address; your connection rotates between several addresses; you listed your production server but a test or staging environment also calls the API. Collect the addresses of everything that calls the API, not just your main machine, and add them all.

You added an IPv4 address but requests are still blocked

If your machine prefers IPv6, the address Smoobu sees is the IPv6 one, which does not match your IPv4 entry. Either add both addresses, or configure your integration to connect over IPv4.

You wanted to allow Smoobu's webhooks through your own firewall

This list restricts incoming calls to the Smoobu API. It has no effect on the outgoing webhook deliveries Smoobu sends to your server. Smoobu does not publish a fixed set of addresses that webhooks are sent from, so do not put an IP filter in front of your webhook endpoint. Verify webhook deliveries by their contents instead.

Do I still need HMAC signing?

Yes. IP whitelisting is an additional layer, not an alternative. Requests from a whitelisted address are still fully verified: timestamp, nonce and signature all have to be correct.

Related articles

• Use the Smoobu API and webhooks