Skip to main content
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.

​
Permissões disponíveis

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

​
Criar uma chave

1

Abra Chaves de API

Acesse Dashboard → Chaves de API.
2

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.
3

Marque as permissões

Só o necessário para aquele serviço. Veja a tabela abaixo.
4

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.
5

Guarde no cofre

Variável de ambiente ou gerenciador de segredos. Se perder, não há como recuperar: crie outra.

​
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.
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.

​
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.
Hoje não existe tela no dashboard para cadastrar a lista de IPs. Para restringir uma chave a IPs fixos, fale com o suporte informando a chave (pelo nome) e os IPs de saída.
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.
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.
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.
1

Crie uma nova chave

Com as mesmas permissões da atual.
2

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.
3

Confirme que ninguém usa a antiga

Acompanhe o tráfego e confira que as chamadas já usam a chave nova.
4

Revogue a antiga

Só depois de confirmar, use Revogar chave.

​
Revogação

Depois de revogar, qualquer requisição com a chave recebe:
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.
Antes de revogar, confira em 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.
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.

Autenticação

Como enviar a chave e entender cada erro.

Webhooks

Segredo de assinatura e endpoints por chave.