# Lista de IPs permitidos

Um segredo de cliente ou uma chave de API que vaza pode ser usado por qualquer pessoa que a possua, de qualquer lugar. Uma **lista de IPs permitidos** restringe isso: você lista os endereços IP dos quais seus servidores chamam o Pluggy, e a API recusa as credenciais dessa aplicação de qualquer outro endereço.

A lista de permitidos é opcional e desativada por padrão. Uma aplicação sem uma aceita solicitações de qualquer IP, como sempre fez.

<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="Configurando IPs Permitidos no Dashboard"
>
  Um tour de 30 segundos sobre IPs Permitidos no Dashboard. O texto na tela está em português.
</Video>

## Como funciona

Cada aplicação tem sua própria lista. Quando a lista não está vazia, a API verifica o IP público de cada solicitação:

- `POST /auth`, que troca o ID do cliente e o segredo do cliente por uma chave de API, é aceito apenas de um IP listado.
- Cada solicitação autenticada com uma chave de API dessa aplicação (`X-API-KEY`) é aceita apenas de um IP listado. Isso inclui a criação de um Connect Token com `POST /connect_token`.

Uma solicitação de qualquer outro IP é recusada com `403` e `CLIENT_IP_NOT_ALLOWED` (veja [O erro](#o-erro)). A mudança entra em vigor assim que você a salva.

Solicitações autenticadas com um **Connect Token** não são verificadas. O Pluggy Connect roda nos navegadores e telefones dos seus usuários, cujos IPs você não pode conhecer, então o widget continua funcionando onde quer que seus usuários estejam.

## O que é e o que não é restrito

| Solicitação | Restrito pela lista de permitidos |
| --- | --- |
| `POST /auth` com o ID do cliente e o segredo do cliente da aplicação | Sim |
| Qualquer solicitação com uma chave de API da aplicação em `X-API-KEY` | Sim |
| `POST /connect_token` (é chamado com uma chave de API) | Sim |
| Solicitações feitas com um Connect Token, incluindo Pluggy Connect | Não |
| Um Connect Token que já foi emitido | Não: continua funcionando até expirar |
| O [Dashboard](https://dashboard.pluggy.ai) | Não: você pode sempre editar ou remover a lista lá |

## Configure

Apenas `OWNER`s e `ADMIN`s de uma equipe podem editar a lista. `MEMBER`s a veem como somente leitura (veja [Acesso à equipe](/docs/security/team-access)).

1. Abra o [Dashboard](https://dashboard.pluggy.ai), vá para **Aplicações** e abra a aplicação.
2. Encontre o cartão **IPs Permitidos**, entre as credenciais e os webhooks. Ele está disponível para cada aplicação, em desenvolvimento e em produção.
3. Adicione os IPs públicos dos quais seus servidores chamam o Pluggy: endereços únicos ou intervalos CIDR, IPv4 ou IPv6. Você pode colar vários de uma vez, separados por vírgulas, espaços ou novas linhas.
4. Salve e confirme. A lista se aplica imediatamente, então certifique-se de que todos os servidores que usam as credenciais dessa aplicação estejam nela antes de confirmar.

Para desativar a restrição, use **Remover restrição** no mesmo cartão. A lista é limpa e a aplicação aceita qualquer IP novamente.

### O que você pode listar

| Regra | Detalhe |
| --- | --- |
| Formatos | Endereços IPv4 ou IPv6, ou intervalos CIDR: `203.0.113.10`, `198.51.100.0/24`, `2001:db8::/32`. |
| Tamanho | Até 50 entradas por aplicação. |
| Não aceito | Intervalos `/0` (`0.0.0.0/0`, `::/0`): eles permitiriam todos os endereços. |
| Duplicatas | Eliminadas. |
| Normalização | A lista armazenada é normalizada: um intervalo escrito com bits de host definidos é salvo como seu endereço de rede, então `10.0.0.5/8` é armazenado como `10.0.0.0/8`. |

Cada alteração na lista é registrada no log de atividades da sua equipe, com quem a fez.

## Qual IP listar

A API vê o IP **público** do qual sua solicitação chega ao Pluggy, não o endereço da máquina que a fez.

- Se seus servidores saem para a internet através de um gateway NAT, um proxy ou a saída do seu provedor de nuvem, liste os IPs de saída (por exemplo, um IP estático ou elástico do gateway NAT).
- Endereços privados (`10.x`, `172.16.x`–`172.31.x`, `192.168.x`) nunca chegam ao Pluggy, então listá-los não tem efeito.
- Se seus servidores não têm um IP público fixo, configure um antes de ativar a lista de permitidos. Com um endereço que muda, a próxima alteração bloqueia seus servidores.

Para encontrar o IP de saída, chame um serviço de eco de IP do próprio servidor ou verifique os IPs estáticos do seu gateway NAT ou proxy no console do seu provedor de nuvem.

## O erro

Uma solicitação de um IP que não está na lista recebe:

```json
{
  "code": 403,
  "codeDescription": "CLIENT_IP_NOT_ALLOWED",
  "message": "O endereço IP da solicitação não está na lista de IPs permitidos configurados para esta aplicação."
}
```

Baseie-se em `codeDescription`, não em `message`. Tentar novamente do mesmo IP retorna o mesmo erro: a solução é chamar de um IP listado ou adicionar o IP à lista. Veja também [Códigos de erro](/reference/error-codes#authentication-and-access).

## Boa prática

- **Use IPs de saída estáticos.** Uma lista de permitidos é tão estável quanto os endereços nela.
- **Adicione o novo IP antes de migrar.** Quando você se mudar para uma nova região, conta de nuvem ou gateway NAT, adicione seus IPs primeiro, implemente e remova os antigos apenas depois que o tráfego tiver mudado.
- **Uma aplicação por ambiente, uma lista por aplicação.** Seus servidores de CI ou staging usam sua própria aplicação com sua própria lista, então a lista de produção permanece curta. Veja [Credenciais e chaves de API](/docs/security/credentials#separate-development-production-and-tenants).
- **Combine com as outras camadas.** Uma lista de permitidos limita onde uma credencial vazada funciona; não substitui manter segredos fora do código e rotacioná-los ([Rotacionar o segredo do cliente](/docs/security/credentials#rotate-the-client-secret)), nem verificar seus webhooks ([Segurança do webhook](/docs/developer-tools/webhook-security)).

## Solução de problemas

### Estou recebendo `403 CLIENT_IP_NOT_ALLOWED`

A aplicação tem uma lista de permitidos e a solicitação veio de um IP que não está nela. Encontre o IP público do qual o servidor realmente sai (veja [Qual IP listar](#qual-ip-listar)), e peça a um `OWNER` ou `ADMIN` para adicioná-lo no cartão **IPs Permitidos**. As causas usuais são um novo servidor, uma mudança de gateway NAT ou região, uma implantação em uma plataforma sem IPs de saída fixos, ou um script executado de um laptop.

### Qual IP eu listarei?

O IP público do qual seus servidores alcançam o Pluggy: o IP de saída do seu gateway NAT, proxy ou rede de nuvem, não um endereço privado. Veja [Qual IP listar](#qual-ip-listar).

### Isso afeta o widget Connect?

Não. Solicitações feitas com um Connect Token não são restritas, então o Pluggy Connect continua funcionando de qualquer dispositivo do usuário. Criar o Connect Token é restrito: seu backend chama `POST /connect_token` com uma chave de API, então precisa ser executado de um IP listado.

### Eu me bloqueei

O Dashboard nunca é bloqueado pela lista de permitidos. Um `OWNER` ou `ADMIN` pode abrir a aplicação, adicionar o IP ausente ou usar **Remover restrição**, e a mudança se aplica imediatamente.

### Isso é o mesmo que permitir os IPs do webhook do Pluggy?

Não, é a direção oposta. Esta página restringe quem pode chamar a API do Pluggy com suas credenciais. Para aceitar notificações de webhook apenas do Pluggy, veja [Permitir apenas os IPs de origem do Pluggy](/docs/developer-tools/webhook-security#2-allow-only-pluggys-source-ips).

## Não protege contra

- Uma credencial usada de um dos seus próprios servidores listados: se um atacante controla uma máquina na lista, a lista de permitidos não os impede.
- Um Connect Token que vaza: Connect Tokens não são restritos por IP. Eles têm vida curta e escopo limitado, veja [Connect Tokens](/docs/security/connect-tokens).

Próximo: [Connect Tokens](/docs/security/connect-tokens).