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

# Autenticação

> Como autenticar as chamadas: formato da chave de API, permissões (escopos), IPs liberados, validade e revogação.

Toda chamada leva a chave no cabeçalho `Authorization`:

```http theme={null}
Authorization: Bearer bk_live_7KQ2M9XP4RZT_X1Y2Z3...
```

A chave tem o formato `bk_live_<id>_<segredo>`. A WyzeCash guarda só um resumo do segredo: depois de criada, ninguém consegue vê-la de novo, nem o suporte. Perdeu? Revogue e crie outra.

## Criar, editar e revogar

Só no painel, em **Integrações e API › Chaves de API** (com o código do app autenticador, se essa opção estiver ligada em Segurança › 2FA):

* **Nome**, para você reconhecer (ex.: "Site de vendas", "ERP").
* **Permissões** (escopos), uma ou mais. Dê só as que o sistema usa.
* **IPs liberados** (IP ou faixa CIDR, até 20). Obrigatório para chaves que sacam ou enviam Pix; recomendado para todas. Chamada de outro IP responde `403 IP_NOT_ALLOWED`.
* **Validade** opcional, de 1 a 730 dias. Vencida, responde `401 INVALID_API_KEY`.

Revogar para na hora. A lista mostra prefixo, últimos 4 caracteres, permissões, IPs e o último uso de cada chave.

## Permissões (escopos)

| Escopo | Libera |
| - | - |
| `balance:read` | `GET /v1/balance`, `GET /v1/fees/preview` |
| `transactions:read` | extrato, cobranças, links, saques, MED e subcontas (leitura) |
| `payments:write` | criar cobranças no Pix e links de pagamento |
| `card:write` | criar cobranças no cartão de crédito (e links que aceitam cartão) |
| `crypto:write` | criar cobranças em cripto (e links que aceitam cripto) |
| `withdrawals:write` | saques para a chave enviada no pedido, inclusive da subconta (IP liberado obrigatório) |
| `subaccounts:write` | criar, alterar e excluir subcontas; enviar da conta principal, transferir entre subcontas e devolver à principal |
| `customers:read`, `customers:write` | clientes |

Chamar uma rota sem a permissão responde `403 FORBIDDEN`. Cada forma de pagamento tem o seu escopo: uma chave só com `payments:write` cria cobrança no Pix, mas a mesma chamada com `method: "card"` responde `403` até a chave ganhar `card:write`.

> [!WARNING]
>
> **Chaves que movem dinheiro** (`withdrawals:write`, `pix:write`) só nascem com o 2FA ligado na conta e com pelo menos um IP liberado: como o saque e o Pix vão para a chave enviada no pedido, quem tiver a chave de API e um desses IPs consegue mandar dinheiro. Guarde-a bem.

## Boas práticas

* Guarde a chave num cofre de segredos ou variável de ambiente do servidor. Nunca no front-end, em app para celular ou em repositório.
* Uma chave por sistema. Assim dá para revogar uma sem parar as outras.
* Use `Idempotency-Key` em tudo que cria dinheiro ou movimentação ([Convenções](https://docs.wyzecash.com.br/convencoes.md)).
* Chame pelo servidor, sempre em HTTPS. Pedido sem HTTPS não chega.

## O que a chave não faz

Por segurança, ficam só no painel: criar ou editar chaves de API, configurar webhooks, cadastrar chaves Pix favoritas, transferir entre contas WyzeCash, estornar e responder um MED.

## Limites de chamadas

Há um teto de chamadas por IP e por conta; passou, `429 RATE_LIMITED`. A tabela completa está em [Limites de requisição](https://docs.wyzecash.com.br/limites.md).


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