> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyxpag.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestão de chaves da NyxPag

> Crie, restrinja, troque e revogue API Keys da NyxPag com permissões mínimas, IP allowlist e rotação sem indisponibilidade.

A API Key é como a sua integração prova quem é. Esta página mostra como criar chaves com as permissões certas, trocar sem derrubar nada e revogar uma chave comprometida. Para saber como **enviar** a chave em cada requisição, veja [Autenticação](/guides/autenticacao).

## Permissões disponíveis

Cada chave tem uma ou mais permissões. Escolha só as que o serviço usa.

| Permissão | No dashboard | Endpoints |
| - | - | - |
| `balance:read` | Saldo | `GET /balance` |
| `payments:write` | Pagamentos | `POST /transactions` |
| `transactions:read` | Transações | `GET /transactions`, `GET /transactions/{id}`, `GET /meds`, `GET /meds/{id}` |
| `transfers:write` | Saques | `POST /transfers` |

## Criar uma chave

<Steps>
  <Step title="Abra Chaves de API">
    Acesse [Dashboard → Chaves de API](https://nyxpag.com.br/dashboard/credentials).
  </Step>

  <Step title="Clique em Nova chave">
    Dê um nome que diga **onde** a chave vai viver, como `checkout-producao` ou `financeiro-saques`. Ajuda muito quando você precisar revogar.
  </Step>

  <Step title="Marque as permissões">
    Só o necessário para aquele serviço. Veja a tabela abaixo.
  </Step>

  <Step title="Confirme a verificação e crie">
    A criação passa por uma verificação de segurança. Depois, copie a chave: ela aparece **uma única vez**.
  </Step>

  <Step title="Guarde no cofre">
    Variável de ambiente ou gerenciador de segredos. Se perder, não há como recuperar: crie outra.
  </Step>
</Steps>

## Menor privilégio

Combine as permissões de acordo com o que o serviço faz. Se uma chave vazar, o estrago fica limitado ao que ela podia fazer.

| Serviço | Permissões | Por quê |
| - | - | - |
| Checkout que gera Pix | `payments:write` | Só precisa criar cobranças |
| Conciliação e relatórios | `balance:read`, `transactions:read` | Só lê, nunca movimenta |
| Saques automáticos | `transfers:write` | Isole: é a única que tira dinheiro da conta |
| Assistente de IA (MCP) | `balance:read`, `transactions:read` | O MCP é somente leitura |
| Tudo junto | as quatro | Só em ambiente controlado e com IP restrito |

<Tip>
  Mantenha `transfers:write` numa chave só dela. É a permissão que **envia dinheiro**, e quanto menos lugares a tiverem, menor a superfície de risco.
</Tip>

## IP allowlist

A API sabe restringir uma chave a IPs específicos: uma chamada de outro endereço recebe `403` com `ip_not_allowed`. É uma camada forte, porque mesmo uma chave vazada não funciona fora do seu servidor.

<Note>
  Hoje não existe tela no dashboard para cadastrar a lista de IPs. Para restringir uma chave a IPs fixos, fale com o [suporte](mailto:suporte@nyxpag.com.br) informando a chave (pelo nome) e os IPs de saída.
</Note>

Ao montar a lista, inclua todos os IPs de **saída** dos servidores de produção e dos pipelines que chamam a API, e evite IPs dinâmicos de máquinas de desenvolvimento. Em ambiente serverless, verifique o IP de saída do NAT ou da VPC.

## Rotação sem indisponibilidade

Troque a chave a cada 90 dias, ou na hora em que suspeitar de vazamento.

<Warning>
  O botão **Renovar chave** invalida a chave antiga **imediatamente**. Ele mantém nome, permissões e lista de IPs, e entrega um valor novo. Use quando há vazamento. Para uma troca planejada, não renove: crie uma segunda chave, como abaixo.
</Warning>

<Note>
  Cada conta tem um limite de chaves ativas. Ao atingi-lo, a criação retorna `api_key_limit_reached`: revogue uma chave que não usa mais antes de criar outra. Se você precisa de duas chaves ao mesmo tempo para a troca, confira que há espaço antes de começar.
</Note>

<Steps>
  <Step title="Crie uma nova chave">
    Com as mesmas permissões da atual.
  </Step>

  <Step title="Atualize os consumidores">
    Troque a variável de ambiente ou o segredo em todos os serviços e faça o deploy. A chave antiga continua funcionando.
  </Step>

  <Step title="Confirme que ninguém usa a antiga">
    Acompanhe o tráfego e confira que as chamadas já usam a chave nova.
  </Step>

  <Step title="Revogue a antiga">
    Só depois de confirmar, use **Revogar chave**.
  </Step>
</Steps>

## Revogação

Depois de revogar, qualquer requisição com a chave recebe:

```json theme={"dark"}
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "API key ausente ou inválida."
  },
  "requestId": "req_01H..."
}
```

Revogue na hora se:

* a chave foi parar num repositório, mesmo que privado;
* alguém com acesso a ela saiu da empresa;
* você vê chamadas que não reconhece.

<Note>
  Antes de revogar, confira em [Dashboard → Webhooks](https://nyxpag.com.br/dashboard/webhooks) se há um endpoint de webhook vinculado a essa chave. Cada endpoint pertence a uma chave, então planeje a troca para não ficar sem receber eventos.
</Note>

<Warning>
  Nunca coloque uma API Key em repositório de código, nem em branch privada. Use variáveis de ambiente e um cofre de segredos. Se uma chave vazou, trate como comprometida e revogue.
</Warning>

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key-round" href="/guides/autenticacao">
    Como enviar a chave e entender cada erro.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Segredo de assinatura e endpoints por chave.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.