# IP allowlist

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.

<Video
  src="/docs/videos/allowed-ips/allowed-ips-pt.mp4"
  poster="/docs/videos/allowed-ips/allowed-ips-pt-poster.jpg"
  captions="/docs/videos/allowed-ips/allowed-ips-pt.vtt"
  title="Setting up Allowed IPs in the Dashboard"
>
  A 30-second tour of Allowed IPs in the Dashboard. The on-screen text is in Portuguese.
</Video>

## 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 with `POST /connect_token`.

A request from any other IP is refused with `403` and `CLIENT_IP_NOT_ALLOWED` (see
[The error](#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](https://dashboard.pluggy.ai) | No: you can always edit or remove the list there |

## Set it up

Only a team's `OWNER`s and `ADMIN`s can edit the list. `MEMBER`s see it read-only (see
[Team access](/docs/security/team-access)).

1. Open the [Dashboard](https://dashboard.pluggy.ai), go to **Applications** and open the
   application.
2. Find the **Allowed IPs** card, between the credentials and the webhooks. It is available for
   every application, in development and in production.
3. 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.
4. 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:

```json
{
  "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 codes](/reference/error-codes#authentication-and-access).

## 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](/docs/security/credentials#separate-development-production-and-tenants).
- **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](/docs/security/credentials#rotate-the-client-secret)), nor
  verifying your webhooks ([Webhook security](/docs/developer-tools/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](#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](#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](/docs/developer-tools/webhook-security#2-allow-only-pluggys-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](/docs/security/connect-tokens).

Next: [Connect Tokens](/docs/security/connect-tokens).