Chaves de API¶

Para: Adm · Dev — Conferido em 2026-10-18.

Na tela Chaves e IPs o Administrador do tenant pede chaves novas, revela o segredo uma única vez, acompanha o uso de cada chave e revoga as que não servem mais. Pedir uma chave exige a aprovação de outra pessoa e uma espera de 24 horas; revogar é imediato.

O que é¶

Uma chave é um par de credenciais da operação: o identificador público (key_test_… em operação Teste, key_live_… em operação Real) e o segredo (sk_test_… ou sk_live_…), que assina cada chamada HMAC. Veja Autenticação HMAC. A chave de um tipo não vale no outro: chave key_live_ numa operação de Teste, ou o inverso, recebe 401 com unknown_key.

Cada chave leva um ou mais escopos, que limitam o que ela faz. Uma chamada sem o escopo da rota recebe 403 com insufficient_scope.

Quem usa a tela: só o Administrador do tenant abre Chaves e IPs. Os outros papéis recebem "Não encontrado". O limite é de 2 chaves ativas por operação; o título da seção mostra "Chaves de API (N de 2 ativas)".

Quando usar¶

• Para dar a um componente novo (conector, job de reconciliação) uma chave própria, com o menor escopo possível.
• Para rotacionar uma chave, sem parar a integração.
• Para revogar uma chave que vazou ou que não é mais usada.
• Para decidir o que revogar: a tabela mostra o último uso e as recusas de cada chave.

Escopos mínimos por componente (recomendação): o conector de depósitos usa deposits:write e read; o de saques usa withdrawals:write e read; um job só de conferência usa apenas read.

Como fazer¶

Pedir uma chave nova¶

1. Em Criar chave de API, marque os escopos (de 1 a 4, sem repetir).
2. Escreva o motivo (de 10 a 1000 caracteres).
3. Clique em Pedir chave. Se a confirmação de identidade estiver vencida, use Confirmar identidade agora antes.
4. O pedido aparece em Pedidos em andamento como Aguardando aprovação.
5. Outro Administrador abre o pedido, escreve o motivo da decisão e clica em Aprovar (ou Recusar). Quem pediu não aprova o próprio pedido.
6. Aprovado, o pedido passa a Aprovado, no time-lock e mostra "Xh XXmin para valer". A chave só nasce 24 horas depois da aprovação.
7. Quando a espera termina, o Dracma cria a chave e a linha dela aparece na tabela como Ativa, segredo ainda não revelado.

Se a operação já tem 2 chaves ativas, o botão Pedir chave fica desabilitado e a tela avisa: revogue uma antes.

Revelar o segredo¶

• O botão Revelar segredo (uma vez) aparece só para quem pediu a chave, na linha dela. Para as outras pessoas, a linha mostra "Segredo aguardando quem pediu a chave (até …)".
• Revelar exige confirmação recente. O segredo aparece na tela com o aviso Copie o segredo agora; recarregar a página o apaga e o Dracma não o mostra de novo.
• A janela para revelar é de 24 horas a partir do momento em que a chave nasce (não do pedido). Passado o prazo, o Dracma revoga a chave sem que o segredo tenha sido mostrado e libera a vaga.
• O escopo da chave não muda quem revela: vale para chave de leitura e para chave de escrita.

A primeira chave de uma operação segue outro caminho: ela nasce junto com a operação e é revelada pelo botão Revelar chave da tela Tenants e operações, também uma vez e em até 24 horas.

Rotacionar sem parar a integração¶

A rotação é manual. Com o limite de 2 chaves ativas, o roteiro é:

1. Com a chave antiga ainda ativa, peça a chave nova (aprovação + 24 h).
2. Quando a chave nova nascer, revele o segredo e guarde no cofre.
3. Coloque a chave nova no conector e implante.
4. Confira na tabela: a chave nova mostra Último uso; a antiga deve parar de aparecer em uso.
5. Revogue a chave antiga.

Revogar uma chave¶

1. Na linha da chave, escreva o motivo da revogação (de 10 a 1000 caracteres).
2. Clique em Revogar agora. É preciso confirmação recente. Uma pessoa basta, sem espera.
3. A tela confirma: "Chave revogada. Deixa de valer em até 30 segundos em todas as réplicas."

Depois disso, toda chamada com a chave recebe 401 com unknown_key. A revogação não tem volta; para voltar a usar, peça uma chave nova. Você pode revogar a última chave ativa, mas a integração fica sem credencial até a próxima nascer (24 horas).

Perdi o segredo¶

Não há como recuperar um segredo: o Dracma não o guarda em claro. Se a janela venceu, se a página foi recarregada antes de copiar ou se o segredo vazou:

1. Se a operação tem 2 chaves ativas, revogue a que perdeu o segredo (ou uma que não usa).
2. Peça uma chave nova, com outro ciclo de aprovação e 24 horas.
3. Atualize o conector.

Respostas da tela para segredo indisponível: "Não há segredo a revelar: já foi mostrado, a janela venceu ou o pedido não é seu."

Uso por chave¶

A tabela de chaves mostra, para cada uma:

O último uso e as recusas vêm de um registro por amostragem: use-os para decidir se uma chave ainda é usada, não como contagem exata. Se uma chave ativa acumula recusas 403, a tela mostra o banner Chave usada de IP fora da lista, com a contagem e o último IP. Sem IP liberado na operação (veja IPs do conector), nenhuma chamada é recusada por origem e esse contador fica em zero.

Exemplos¶

Rotação planejada para uma terça-feira, com dois Administradores (Ana e Bruno), todos os horários de Brasília:

Erros e casos de borda¶

Casos de borda:

• Só um Administrador no tenant. Ninguém pode aprovar o pedido: inclua uma segunda pessoa em Equipe e papéis antes de precisar de uma chave.
• Pedido "Falhou". O histórico recente mostra o motivo no fim da linha. O mais comum é o limite de 2 chaves atingido durante a espera.
• Chave nova sem uso. Se, depois do deploy, a chave nova não aparece com "Último uso", o conector ainda usa a antiga ou está recebendo 401. Confira o relógio do servidor e a assinatura em Autenticação HMAC.

Veja também¶

• IPs do conector
• Webhooks no painel
• Tenants e operações
• Autenticação HMAC
• Segredos e vazamento