Pular para o conteúdo principal

Chaves de API

Chaves de API autenticam integrações com a API v1. Elas são criadas em Configurações → Segurança, apenas por administradores.

Chaves de API

Criando uma chave​

O formulário pede:

  • Nome (obrigatório) e descrição (opcional) — identifique o sistema que vai usar a chave.
  • Nível de acesso (os escopos da chave).
  • Expiração e e-mails para aviso de vencimento.

O token completo é exibido uma única vez, na criação, com botão de copiar. Guarde-o num cofre de segredos: depois disso só o prefixo (kb_ + últimos 8 caracteres) aparece na listagem. Perdeu o token? Revogue a chave e crie outra.

Níveis de acesso​

NívelAlcance
TotalTodos os recursos, inclusive administração da conta
Leitura e escritaToda a operação de negócio (clientes, cobranças, réguas, acordos, disputas, tarefas, webhooks...), sem administração da conta: membros, roles, chaves de API, configurações, estrutura e auditoria ficam de fora
Somente leituralist/show de todos os recursos, nenhuma escrita

Os níveis são presets sobre o mesmo catálogo dunning.dashboard.<recurso>.<ação> dos roles de equipe. Independentemente do nível, chamadas a recursos administrativos com chave de API respondem 403 API_KEY_FORBIDDEN: uma chave vazada não cria administradores nem outras chaves.

Expiração e avisos​

Expiração opcional: nunca (padrão), 30, 90 ou 365 dias. Para chaves com prazo:

  • A listagem mostra a data ("expira em 12/08/2026"), com badge âmbar quando faltam 7 dias ou menos e vermelha quando expirada.
  • Um job diário envia e-mail de aviso quando a chave entra na janela de 7 dias, para os e-mails cadastrados no campo de aviso (até 10). Campo vazio: avisa quem criou a chave.
  • O mesmo aviso chega como notificação in-app (o sino), com severidade urgente quando faltam 2 dias ou menos.
  • O aviso é enviado uma única vez por chave (nada de spam diário).

Prefira chaves com expiração: rotação periódica limita o estrago de um vazamento.

Acompanhando o uso​

A tabela mostra, por chave: nome e descrição, badge do nível de acesso, prefixo, origem, último uso ("Nunca", se ainda não usada) e criação. "Último uso: nunca" numa chave antiga é candidata a revogação.

Revogar​

O ícone de lixeira revoga a chave (com confirmação). A revogação é imediata e definitiva para o token: requisições passam a responder 401. O registro da chave permanece para fins de histórico e auditoria; edição posterior só de nome e descrição.

Ligações úteis​