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

> ## Agent Instructions
> Consulte o contrato Bunni antes de sugerir chamadas. Valores monetários são inteiros em centavos. Não invente endpoints ou respostas de sucesso para recursos ainda indisponíveis. Nunca solicite chaves reais no chat nem exponha credenciais no cliente.

# Autenticação

> Como usar X-API-Key, os 9 escopos disponíveis e como gerenciar chaves no painel da Bunni Pay.

A API pública da Bunni Pay aceita autenticação por chave de API no cabeçalho `X-API-Key`. A chave pertence a uma conta e so pode acessar os recursos dessa conta. Nao ha autenticação Bearer para a API publica.

## Cabeçalho X-API-Key

Envie a chave em toda requisição a `/v1/*`:

```bash theme={"theme":"github-dark-default"}
curl "https://api.bunnipay.com.br/v1/account" \
  -H "X-API-Key: SUA_CHAVE"
```

Nunca envie a chave em URLs, páginas públicas ou código executado no navegador.

## Escopos disponíveis

Cada chave pode ter um ou mais escopos. Selecione apenas os que sua aplicação precisa.

| Escopo | Para que serve |
| - | - |
| `account:read` | Consultar dados da conta, limites e taxas em `/v1/account` e `/v1/account/fees-limits`. |
| `wallets:read` | Listar carteiras e saldos em `/v1/wallets`. |
| `wallets:write` | Criar carteiras secundárias em `POST /v1/wallets`. |
| `payments:read` | Listar pagamentos, extrato, estatísticas e pagadores. |
| `payments:create` | Emitir cobranças Pix em `POST /v1/payments`. |
| `payouts:read` | Consultar cotação, histórico e situação de saques. |
| `payouts:create` | Solicitar saques Pix em `POST /v1/payouts`. |
| `links:read` | Listar e consultar links de pagamento da conta. |
| `links:write` | Criar e editar rascunhos de links de pagamento. |

A rota `GET /v1/status` exige autenticação, mas nenhum escopo adicional.

## Gerenciamento de chaves no painel

As chaves sao gerenciadas na área API Keys do painel da Bunni Pay. No backend, as rotas de gerenciamento exigem sessão do painel e confirmacao adicional recente para criacao e revogacao.

> [!WARNING]
>
> A chave completa so é exibida no momento da criacao. O servidor armazena apenas o hash. Guarde a chave em um cofre seguro imediatamente.

## Limite de chaves ativas

Cada conta pode manter ate **20 chaves ativas** simultaneamente. Chaves revogadas deixam de autenticar imediatamente. Permissao de criacao nao substitui a habilitacao financeira da conta.

## Erros de autenticação

| HTTP | Código | Significado |
| - | - | - |
| 401 | `UNAUTHORIZED` | Chave ausente, inválida ou revogada. |
| 403 | `SCOPE_REQUIRED` | A chave nao possui o escopo necessário para a rota. |
| 403 | `ACCOUNT_NOT_ENABLED` | Conta sem habilitacao financeira. |

Para mais detalhes sobre o envelope de erro, consulte [Erros e envelope](https://docs.bunnipay.com.br/errors.md).


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