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:

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.

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).
• 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.