Registre a chave pública
No portal, com um usuário administrador da conta: Integrações → Nova credencial de API.
| Campo | O que é |
|---|---|
| Nome | Identifica a integração na sua tela. Não concede acesso. |
| Perfil | read_only: extrato, consultas e leitura de cobranças. full_access: movimenta recursos |
| IPs permitidos | Obrigatório. Endereços IPv4 individuais (203.0.113.10), pelo menos um. Não emitimos credencial sem restrição de origem. Veja Fixando seus IPs. |
| Chave pública | Upload do publicKey.pem (≤ 4 KB) ou o botão Gerar chaves |
Você recebe client_id e kid. Nada disso é secreto, então pode consultar de novo quando quiser.
Sobre a lista de IPs
Só endereços IPv4 individuais. Faixas e IPv6 não são aceitos, e o IP de origem é conferido em toda requisição, contra o endereço do peer que chega até nós. Se você chama através de um proxy seu, registre os endereços de saída do proxy, não os da sua aplicação.
Fixando seus IPs mostra como dar um endereço de saída fixo ao seu workload em cada provedor, e como descobrir de qual endereço você realmente sai.
Perfis
Um perfil é um conjunto fixo de capacidades. Ele é assinado dentro da credencial, então a rota que você pode chamar é decidida pelo que o administrador aprovou, não por algo enviado em tempo de execução.
| Perfil | Pode | Não pode |
|---|---|---|
read_only | ler saldos, extratos, cobranças, locations, registros PIX e webhooks | escrever qualquer coisa |
full_access | tudo do read_only, mais criar cobrança, movimentar, devolver e transferir |
Consulte a lista viva no portal em vez de fixar no código. Perfis são versionados (read_only@1) e
uma versão nova pode aparecer.
Uma credencial = uma chave, uma conta, um perfil
Não existe "editar a chave". Para rotacionar, você cria uma credencial nova na mesma integração, migra a aplicação e revoga a antiga. Duas credenciais podem valer ao mesmo tempo durante a janela de rotação, e é isso que permite rotacionar sem parada:
Perfil e IPs permitidos podem ser editados: o portal substitui a credencial por uma versão nova
assinada, que mantém a mesma chave e o mesmo client_id. Sua aplicação não muda; a versão anterior
deixa de ser aceita.
Revogação
Revogar é irreversível e vale em cerca de um segundo. Não existe "desrevogar": se revogou por engano, crie outra credencial.
A criação e a revogação de cada credencial são gravadas numa trilha imutável, que só cresce.