A client secret or an API key that leaks can be used by anyone who holds it, from anywhere. An IP allowlist narrows that down: you list the IP addresses your servers call Pluggy from, and the API refuses that application's credentials from every other address.
The allowlist is optional and off by default. An application without one accepts requests from any IP, as it always has.
A 30-second tour of Allowed IPs in the Dashboard. The on-screen text is in Portuguese.
How it works#
Each application has its own list. When the list is not empty, the API checks the public IP each request comes from:
POST /auth, which exchanges the client ID and client secret for an API key, is accepted only from a listed IP.- Every request authenticated with an API key of that application (
X-API-KEY) is accepted only from a listed IP. That includes creating a Connect Token withPOST /connect_token.
A request from any other IP is refused with 403 and CLIENT_IP_NOT_ALLOWED (see
The error). The change takes effect as soon as you save it.
Requests authenticated with a Connect Token are not checked. Pluggy Connect runs on your users' browsers and phones, whose IPs you cannot know, so the widget keeps working wherever your users are.
What is and isn't restricted#
| Request | Restricted by the allowlist |
|---|---|
POST /auth with the application's client ID and client secret | Yes |
Any request with an API key of the application in X-API-KEY | Yes |
POST /connect_token (it is called with an API key) | Yes |
| Requests made with a Connect Token, including Pluggy Connect | No |
| A Connect Token that was already issued | No: it keeps working until it expires |
| The Dashboard | No: you can always edit or remove the list there |
Set it up#
Only a team's OWNERs and ADMINs can edit the list. MEMBERs see it read-only (see
Team access).
- Open the Dashboard, go to Applications and open the application.
- Find the Allowed IPs card, between the credentials and the webhooks. It is available for every application, in development and in production.
- Add the public IPs your servers call Pluggy from: single addresses or CIDR ranges, IPv4 or IPv6. You can paste several at once, separated by commas, spaces or new lines.
- Save, and confirm. The list applies immediately, so make sure every server that uses this application's credentials is on it before you confirm.
To turn the restriction off, use Remove restriction on the same card. The list is cleared and the application accepts any IP again.
What you can list#
| Rule | Detail |
|---|---|
| Formats | IPv4 or IPv6 addresses, or CIDR ranges: 203.0.113.10, 198.51.100.0/24, 2001:db8::/32. |
| Size | Up to 50 entries per application. |
| Not accepted | /0 ranges (0.0.0.0/0, ::/0): they would allow every address. |
| Duplicates | Dropped. |
| Normalization | The stored list is normalized: a range written with host bits set is saved as its network address, so 10.0.0.5/8 is stored as 10.0.0.0/8. |
Every change to the list is recorded in your team's activity log, with who made it.
Which IP to list#
The API sees the public IP your request reaches Pluggy from, not the address of the machine that made it.
- If your servers go out to the internet through a NAT gateway, a proxy or your cloud provider's egress, list the egress IPs (for example, a static or elastic IP of the NAT gateway).
- Private addresses (
10.x,172.16.x–172.31.x,192.168.x) never reach Pluggy, so listing them has no effect. - If your servers have no fixed public IP, set one up before turning the allowlist on. With an address that changes, the next change locks your servers out.
To find the egress IP, call an IP echo service from the server itself, or check the static IPs of your NAT gateway or proxy in your cloud provider's console.
The error#
A request from an IP that is not on the list gets:
{
"code": 403,
"codeDescription": "CLIENT_IP_NOT_ALLOWED",
"message": "The request IP address is not in the list of allowed IPs configured for this application."
}Branch on codeDescription, not on message. Retrying from the same IP returns the same error:
the fix is to call from a listed IP or to add the IP to the list. See also
Error codesAPI.
Good practice#
- Use static egress IPs. An allowlist is only as stable as the addresses on it.
- Add the new IP before you migrate. When you move to a new region, cloud account or NAT gateway, add its IPs first, deploy, and remove the old ones only after the traffic has moved.
- One application per environment, one list per application. Your CI or staging servers use their own application with their own list, so production's list stays short. See Credentials and API keys.
- Combine it with the other layers. An allowlist limits where a leaked credential works; it does not replace keeping secrets out of code and rotating them (Rotate the client secret), nor verifying your webhooks (Webhook security).
Troubleshooting#
I'm getting 403 CLIENT_IP_NOT_ALLOWED#
The application has an allowlist and the request came from an IP that is not on it. Find the public
IP the server actually goes out from (see Which IP to list), and have an
OWNER or ADMIN add it in the Allowed IPs card. The usual causes are a new server, a
change of NAT gateway or region, a deploy to a platform without fixed egress IPs, or a script run
from a laptop.
Which IP do I list?#
The public IP your servers reach Pluggy from: the egress IP of your NAT gateway, proxy or cloud network, not a private address. See Which IP to list.
Does it affect the Connect widget?#
No. Requests made with a Connect Token are not restricted, so Pluggy Connect keeps working from any
user's device. Creating the Connect Token is restricted: your backend calls POST /connect_token
with an API key, so it has to run from a listed IP.
I locked myself out#
The Dashboard is never blocked by the allowlist. An OWNER or ADMIN can open the application,
add the missing IP or use Remove restriction, and the change applies immediately.
Is this the same as allowlisting Pluggy's webhook IPs?#
No, it is the opposite direction. This page restricts who may call the Pluggy API with your credentials. To accept webhook notifications only from Pluggy, see Allow only Pluggy's source IPs.
Does not protect against#
- A credential used from one of your own listed servers: if an attacker controls a machine on the list, the allowlist does not stop them.
- A Connect Token that leaks: Connect Tokens are not restricted by IP. They are short-lived and limited in scope, see Connect Tokens.
Next: Connect Tokens.
