IP allowlist / whitelisting
IP allow list (also known as IP White listing) lets you restrict your Partner API credentials to the servers you actually call Airalo from. Once your allowlist has at least one entry, a request carrying your token from any other address is refused.It is optional and off by default. We strongly recommend turning it on: a leaked token is far less useful to an attacker who cannot call the API from their own infrastructure.
Quick start setup#
1.
On the server that calls the Airalo API, run: 2.
Copy the address it prints.
3.
In the Partner Platform, open API Integration and find the Allowed IP addresses card
below your API credentials. 4.
Type or paste the address and press Enter, or click +. It does not save immediately.
5.
Repeat for every server, region, NAT gateway or proxy your integration calls out through.
6.
Hit the Save button to successfully enable the Allow list on those IP addresses.
Empty list vs populated list#
| Your allowlist | What happens |
|---|
| Empty | No IP restriction. Your token works from any address. This is a supported state, not an error, but it is also the state a stolen token can be used from! |
| One or more entries | Only requests from a listed address (or inside a listed range) are accepted. Everything else is refused. The safest operational model! |
Two things worth knowing:One list covers sandbox and production - The allowlist is the same for both sandbox and production modes.
This is separate from Partner Platform login restrictions - If your company also restricts which IPs may sign in to the Partner Platform, that is a different list (Your Airalo account manager can modify this for you). Adding an API egress IP here will not affect who can log in, and it cannot lock you out of the Partner Platform.
Which IP should I add?#
The public outbound (egress) IP of the server that calls the Airalo API.Not the IP of the laptop you are browsing the Partner Platform from. Those are almost never the same address, and adding your browsing IP will not let your integration through.If you are unsure, run curl <https://api.ipify.org on the calling server hosting your integration, not on your own machine. The address it returns is what Airalo Partner API sees and needs to be in the allow list.If your integration runs somewhere you cannot open a shell (a managed platform, a serverless runtime, a provider’s hosting service), ask your hosting manager for the full list of egress IP addresses.
The Allowed IP addresses field appears in two places, and both write to the same list:Step 13 of the API Go live checklist, if you are still in Sandbox Mode.
How the field behaves:#
Adding an address does not save it immediately. IP addresses allowed are only enabled once the Save button is clicked. The field is briefly disabled while the change is being stored.
An incomplete address is never allowed, the field guides you what is missing.
You can paste a list. Addresses separated by commas, spaces, semicolons, tabs, newlines or pipes are all split correctly, duplicates are dropped, and surrounding text is ignored. Pasted URLs are reduced to the address, so http://203.0.113.24:8443/webhook is stored as 203.0.113.24.
Removing every entry is allowed and switches enforcement off again for your company, only after clicking the Save button. The card warns you that this leaves your token usable from any address.
Don't see the card?
Either your Partner Platform role does not include permission to view the allowlist, or the feature is not yet enabled for your account. Your account manager can sort out both.
| Form | Example | Notes |
|---|
| Single IPv4 address | 203.0.113.24 | The most common entry |
| Single IPv6 address | 2001:db8::1 | Fully supported |
| IPv4 range (CIDR) | 203.0.113.0/24 | Covers all 256 addresses in that block |
| IPv6 range (CIDR) | 2001:db8::/32 | Fully supported |
A few rules to be aware of:#
/32 is optional. 203.0.113.24 and 203.0.113.24/32 mean the same thing. The plain address is shorter, and it is the form we suggest for a single host.
A range must be written from its first address. 198.51.100.22/24 is refused, because it is ambiguous: a /24 prefix covers 198.51.100.0–198.51.100.255, so the entry would quietly allow 256 addresses while the screen kept showing one. Enter 198.51.100.0/24 if you meant the
whole range, or 198.51.100.22 if you meant that single host. The error message names both options for you.
Duplicates are refused. The same address cannot be added twice.
Add as many entries as you need. There is no product limit; a ceiling of 100 entries per company exists purely as an abuse guard.
CIDR quick reference#
If you have not used CIDR notation before: the number after the slash is how many leading bits are fixed. The smaller the number, the wider the range.| Notation | Addresses covered | Use when |
|---|
203.0.113.24 or /32 | 1 | One server — prefered |
203.0.113.24/31 | 2 | A pair |
203.0.113.24/30 | 4 | A small NAT pool |
203.0.113.24/29 | 8 | A slightly larger pool |
203.0.113.0/24 | 256 | A whole subnet you control |
2001:db8::1/128 | 1 | One IPv6 host |
2001:db8::/64 | a single IPv6 subnet | An IPv6 egress range |
Anything wider than /24 on IPv4 is almost certainly broader than you intend.
What a blocked request looks like#
A request from an address that is not on your allowlist is refused with HTTP 403:{
"code": 89,
"reason": "Your IP address is not permitted to access the Partner API. Add it to your API IP allowlist in the Partner Platform, or contact your account manager."
}
89 means exactly one thing — the calling address is not on the list. Your token is still
valid; nothing has been revoked. Add the address in the Allow List and retry.
When changes take effect#
Immediately after hitting the Save button.
The next request after you add or remove an entry is evaluated against the new list. There is no propagation delay to wait out and nothing to flush.
NAT, load balancers, proxies and multiple regions#
Airalo sees the address your traffic leaves from, which in most production setups is not the
address of the machine running your code.Add every egress address your integration can use:Behind a NAT gateway, add the gateway's public address, not the instance's private one.
Behind an outbound proxy or egress load balancer, add the proxy's public address.
Running in more than one region or availability zone, add each region's egress address — this is the single most common cause of intermittent blocks.
Running more than one server without shared egress, add each one.
Autoscaling with per-instance public IPs: either pin a static egress path (recommended) or add the whole range those instances draw from.
Cloud providers#
On every major cloud, the egress address is usually a gateway address rather than your instance's own IP:| Provider | What to add | How to keep it stable |
|---|
| AWS | NAT Gateway's Elastic IP, or the instance's Elastic IP if it egresses directly | Attach an Elastic IP; a public IP assigned at launch changes on stop/start |
| Google Cloud | Cloud NAT's external address | Reserve a static external IP on the NAT, rather than letting it auto-allocate |
| Azure | NAT Gateway's public IP, or the Load Balancer outbound address | Use a static (not dynamic) public IP; default SNAT addresses are not guaranteed stable |
| Serverless / FaaS | The NAT address of the VPC the function runs in | Attach the function to a VPC with a NAT gateway. Without one, egress addresses are not predictable and cannot be allowlisted |
If a provider only gives you a large, shifting range, allowlisting is not a good fit for that component — front it with a fixed-IP proxy instead.
Private addresses have no effect#
These ranges are internal to your own network and are never what Airalo sees:IPv4: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16
IPv6: fc00::/7 (unique local), fe80::/10 (link-local), ::1 (loopback)
network. But they can never match an incoming request, so an allowlist containing only private
addresses blocks your entire integration while looking populated.If curl https://api.ipify.org returns one of the above, you ran it somewhere without direct internet egress. Run it from the host that actually reaches Airalo.
Common pitfalls#
Using the browsing machine's IP instead of the calling server's. The most frequent mistake.
Using a private address — see above section.
Forgetting a second region, zone or worker - Requests fail intermittently, which looks like a flaky API rather than an allowlist gap.
A dynamic egress IP that changed - Everything worked for weeks, then stopped after a
redeploy or instance restart.
Writing a range from the middle, e.g. 198.51.100.22/24. Refused on purpose — pick the network address or the single host.
Leaving an address typed but not Saved - After entering your IP addresses, ensure to hit the Save button for changes to immediately take effect.+.
Don't assume sandbox is exempt - The same list of IPS applies to both Sandbox and Production modes.
Troubleshooting#
My requests are suddenly returning 403 with code 89.
Your calling address is not on the list. Run curl https://api.ipify.org on the server that issued the request and compare it against the entries. A redeploy, a scale-out into a new zone, or an ISP change are the usual causes.My token request succeeds but every API call returns 403.
That is the signature of an allowlist mismatch rather than a credentials problem — check the calling address, not the token.Our egress IP changed.
Add the new address, confirm traffic flows, then remove the old one. Both can coexist during a migration; there is no need to have a gap.We use serverless / dynamic IPs. What do we do?
Put the function inside a VPC with a NAT gateway holding a static address, and allowlist that. Failing that, route Airalo calls through a fixed-IP proxy you control. Allowlisting a provider's entire dynamic range defeats the purpose.How many IPs can I add?
As many as you need. Partners routinely have eight or more. A 100-entry ceiling exists as an abuse guard.Can I lock myself out of the Partner Platform with this?
No. This list only governs Partner API traffic. Partner Platform sign-in is controlled separately.I want to switch the restriction off.
Remove every entry. Your token then works from any address again — which is worth doing deliberately rather than by accident.
Security best practices#
Be as narrow as your network allows - A single address per server (203.0.113.24) beats a range; a /29 beats a /24.
Pin your egress address so the allowlist does not silently go stale. A reserved static or Elastic IP is cheaper than an outage.
Review the list periodically and remove entries for servers you have decommissioned. Every stale entry is an address an attacker could end up occupying.
Rotate your API credentials on a schedule, and immediately if you suspect exposure. The allowlist limits where a leaked token can be used; it does not make the leak harmless.
If you suspect a compromise, use the Partner Platform control to disable API ordering while you investigate, then reset your credentials.
Turn it on before go-live, not after the first incident.
Need help?#
Contact your account manager or Airalo support with the calling server's public IP and the timestamp of a blocked request. Modified at 2026-08-19 14:17:24
