Gerenciando suas chaves de API
Encontre sua chave de API em API e Webhooks no console, mantenha-a só no servidor, use uma aplicação sandbox separada para testes e corrija os erros 401 e 403.
API e Webhooks, restrito à aplicação que você tem selecionada. Uma chave por aplicação, e a chave é o ambiente - não existe uma chave de teste separada em uma aplicação de produção. É um segredo de servidor: nunca deve estar em código de frontend ou no pacote de um aplicativo.
Sua chave de API fica em API e Webhooks, na barra lateral do console, restrita à aplicação em que você está trabalhando. Trate-a como uma senha - ela concede acesso total à API em nome dessa aplicação.
#Encontrando sua chave
- Faça login no Console de Negócios
Acesse business.didit.me e faça login.
- Selecione sua aplicação
Escolha a aplicação desejada no menu suspenso no topo do console. Cada aplicação tem sua própria chave.
- Abra API e Webhooks
Sua chave de API está aqui, junto com seus destinos de webhook e os respectivos segredos de assinatura.
- Create API key emite uma nova chave; as chaves são por aplicação.
- O segredo é mostrado aqui uma única vez - copie-o para o seu próprio gerenciador de segredos.
- Rotate secret substitui o segredo sem alterar o nome da chave.
- Last used é como você distingue uma chave ativa de uma esquecida antes de revogá-la.
#A chave de API e o segredo de assinatura são coisas diferentes
Vale dizer isso claramente, porque confundir os dois produz erros confusos:
| Para que serve | Onde | |
|---|---|---|
| Chave de API | Autenticar suas chamadas à Didit, no cabeçalho x-api-key | Por aplicação |
| Segredo de assinatura do webhook | Verificar que um webhook recebido realmente veio da Didit | Por destino |
Enviar o segredo de assinatura como se fosse sua chave de API gera um 401. Verificar um webhook com sua chave de API gera uma incompatibilidade de assinatura. Os dois erros são comuns.
Sua chave de API é um segredo. Nunca a coloque em código de frontend, em um repositório público ou no pacote de um aplicativo móvel - mantenha-a só no servidor. Uma chave dentro do pacote de um app publicado é uma chave que um invasor já tem. Veja autenticação da API.
#Obtendo uma chave para testes
Não teste contra produção. Crie uma aplicação separada em modo sandbox - as sessões de sandbox simulam todas as verificações externas, nunca são cobradas e não tocam em dados reais de usuários. Use a chave dela enquanto você desenvolve, e mantenha uma aplicação de produção separada para as verificações reais.
Não existe uma "chave de teste" em uma aplicação de produção. A chave é o ambiente, então vale a pena nomear suas chaves sem ambiguidade em onde quer que você guarde seus segredos. Veja testando em sandbox.
#Rotacionando sua chave
Se uma chave pode ter sido exposta, regenere-a na mesma página de API e Webhooks. Regenerar invalida a chave antiga imediatamente, então atualize-a antes em todos os lugares onde ela é usada - caso contrário, seu tráfego de produção começa a falhar no momento em que você clica no botão.
Rotacionar em uma programação regular é uma boa prática. Planeje isso como um deploy, não como um clique.
#Corrigindo os erros 401 e 403
| Erro | Causa | Correção |
|---|---|---|
401 | A chave está ausente, malformada ou foi regenerada | Copie a chave atual em API e Webhooks para essa aplicação. Verifique se não há espaços em branco ou aspas indevidas, e se você não colou um segredo de assinatura por engano |
403 | A chave é válida, mas essa chamada não é permitida | Geralmente é a aplicação errada, um campo exclusivo de sandbox em uma chave de produção (ou o contrário), uma permissão que falta à sua chave, ou um recurso não habilitado na sua conta |
Um 403 em um fluxo de trabalho específico quase sempre significa que a chave pertence a uma aplicação diferente daquela dona desse fluxo de trabalho. Troque de aplicação no console e copie a chave dela. Detalhamento completo: erros da API e o que significam.
#Restringindo o que uma chave pode fazer
Se a sua necessidade é limitar quais categorias de dados uma chave pode acessar - por exemplo, para impedir que um serviço recupere imagens de documentos - isso é uma questão de permissões, não uma configuração da chave, e o que está disponível depende da sua conta. Pergunte ao suporte em vez de presumir que uma chave não tem restrições ou que tem; as duas suposições são arriscadas em direções opostas.
#Quem da sua equipe pode ver as chaves
A visibilidade das chaves segue a função de cada pessoa. A função Desenvolvedor abrange as chaves de API; a função Leitor, não. Se um colega não conseguir encontrar a página, verifique a função dele antes de reportar o problema. Veja como convidar membros da equipe e definir funções.
#Toda chamada é registrada
As solicitações feitas com chave de API aparecem em Registros de Auditoria atribuídas à aplicação, não a uma pessoa - e é exatamente por isso que uma chave compartilhada entre vários serviços torna um incidente mais difícil de investigar. Uma chave por consumidor é mais fácil de acompanhar. Veja como usar os registros de auditoria.