Chaves de API
As chaves de API autenticam suas solicitações à API DiffHook e identificam quais recursos da equipe você está acessando.
Criando uma chave
- Vá para Aplicativo → Configurações → Chaves de API
- Clique em Nova chave de API
- Dê um rótulo descritivo (por exemplo,
production-server,ci-pipeline) - Copie ID do cliente e Segredo do cliente imediatamente — eles são mostrados apenas uma vez
O ID do cliente é seu identificador público: começa com dh_live_. Após a criação, Configurações lista cada chave por rótulo e ID de cliente completo para que você possa copiar o ID a qualquer momento; o segredo nunca mais é mostrado.
Se você esquecer de copiar o segredo, exclua a chave e crie uma nova.
Permissões principais
Atualmente, todas as chaves têm acesso total aos recursos da sua equipe (monitores, logs, configurações). As chaves por escopo (somente leitura, somente logs etc.) estão no roteiro.
Se você precisar restringir o acesso hoje, crie uma equipe separada para integrações somente leitura e convide membros limitados para lá.
Assinando segredos
Seu segredo de assinatura é separado da sua chave de API. Ele é usado exclusivamente para assinar cargas úteis de webhook de saída para que seu servidor possa verificar se elas vieram do DiffHook.
Encontre-o em Aplicativo → Configurações → Chaves de API → Segredo de assinatura.
Consulte Verificar assinaturas para saber como usá-lo.
Girando uma chave
- Crie uma nova chave e atualize seus aplicativos para usá-la
- Verifique se a nova chave está funcionando em produção
- Exclua a chave antiga de Aplicativo → Configurações → Chaves de API
Não há atalho de rotação de chave que substitua automaticamente uma chave no lugar - sempre siga o fluxo criar → migrar → excluir para evitar tempo de inatividade.
Rotacionando seu segredo de assinatura
Vá para Aplicativo → Configurações → Chaves de API → Alternar segredo de assinatura.
Após rotação:
- Todos os futuros webhooks são assinados com o novo segredo imediatamente
- As entregas durante o voo ainda podem conter a assinatura antiga
- Atualize o segredo do seu servidor antes de revogar o antigo
Revogando uma chave
Exclua a chave de Aplicativo → Configurações → Chaves de API. A revogação é instantânea — a chave não pode mais ser usada para solicitar novos tokens.
No entanto, os tokens ao portador já emitidos com essa chave permanecem válidos até expirarem naturalmente (até 24 horas após terem sido gerados).
Principais práticas recomendadas de segurança
- Nunca confirme chaves para controle de origem. Use variáveis de ambiente ou um gerenciador de segredos (por exemplo, AWS Secrets Manager, Doppler, Vault).
- Use uma chave por ambiente. Mantenha chaves separadas para desenvolvimento, preparação e produção para que você possa revogar uma sem afetar outras.
- Alterne as chaves periodicamente. Trate qualquer chave com mais de 90 dias como candidata à rotação.
- Monitore vazamentos. Se uma chave aparecer em um repositório ou log público, revogue-a imediatamente e crie uma nova.
Solução de erros de autenticação
401 Unauthorized
- As credenciais estão faltando, estão malformadas ou a chave foi revogada
- Para chaves de API: use um JWT de
POST /api/oauth/token
403 Forbidden
- A chave é válida, mas não tem acesso ao recurso solicitado (por exemplo, um monitor pertencente a uma equipe diferente)