Crie e gerencie chaves de API em Desenvolvedores, Chaves de API, uma por serviço e com o acesso de que ele precisa. Mantenha-as no servidor e rotacione.
Desenvolvedores → Chaves de API, restrito à aplicação que você tem selecionada. Toda aplicação tem uma chave Principal, e você pode criar mais, uma por serviço, cada uma com seu próprio acesso e sua própria expiração. Uma chave é um segredo de servidor: nunca deve estar em código de frontend ou no pacote de um aplicativo.
Suas chaves de API ficam em Desenvolvedores → Chaves de API no console, restritas à aplicação em que você está trabalhando. Trate cada chave como uma senha: ela concede acesso à 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 no cartão de aplicação, no topo da barra lateral. Cada aplicação tem suas próprias chaves.
- Abra Desenvolvedores e depois Chaves de API
A aba Chaves lista todas as chaves, começando pela chave Principal, com o acesso de cada uma, quando foi usada pela última vez e quando expira.
#Criando uma chave
Dê a cada serviço que chama a Didit sua própria chave, para que você possa ver o que cada um faz e revogá-la isoladamente.
- Clique em Criar chave
Em Desenvolvedores → Chaves de API.
- Dê um nome e escolha o ambiente
Dê à chave o nome do serviço que vai usá-la, escolha Produção (verificações reais, cobradas) ou Sandbox (dados de teste, nunca cobrados; a chave é criada na aplicação Sandbox da sua organização), e escolha quando ela expira: nunca, depois de 30 dias, 90 dias ou um ano, ou em uma data que você escolher.
- Escolha o acesso
Acesso total lê e grava tudo, para o seu próprio backend. Somente leitura vê sessões, decisões e mídia, mas não pode alterar nada, para um parceiro que só precisa dos resultados. Personalizado permite escolher, recurso por recurso. Desmarque Incluir mídia quando o serviço só precisar da decisão, e não de imagens de documentos, selfies, vídeos ou relatórios em PDF.
- Revise e copie o segredo
O segredo completo é mostrado uma única vez, quando a chave é criada. Copie-o direto para o seu gerenciador de segredos.
A chave Principal é o segredo original da aplicação. Ela sempre tem acesso total e pode ser rotacionada, mas não revogada.
#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, quantas você precisar |
| Segredo de assinatura do webhook | Verificar que um webhook recebido realmente veio da Didit | Por endpoint de webhook |
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. Mude o console para Sandbox e crie uma chave lá, ou escolha Sandbox como ambiente ao criar uma. 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.
Uma chave pertence a uma aplicação e, com ela, ao ambiente dessa aplicação: uma chave de sandbox nunca cria uma verificação de produção, e uma chave de produção nunca cria uma de sandbox. 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, abra-a e escolha Rotacionar chave. Você recebe um novo segredo, e o antigo continua funcionando por 24 horas, para que você possa implantar o novo segredo sem tempo de inatividade. Depois disso, toda solicitação com o segredo antigo retorna um 401.
Se uma chave precisa parar de funcionar agora mesmo, use Revogar chave. Revogar interrompe a chave na hora e não pode ser desfeito. A chave Principal só pode ser rotacionada.
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, expirada, revogada ou foi rotacionada há mais de 24 horas | Confira a chave em Desenvolvedores → Chaves de API 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), um acesso que não foi dado à chave (uma chave somente leitura tentando gravar, por exemplo), 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 use uma das chaves dela. Detalhamento completo: erros da API e o que significam.
#Restringindo o que uma chave pode fazer
Escolha o acesso ao criar a chave e altere-o depois com Editar acesso (o segredo continua o mesmo; o acesso da chave Principal não pode ser editado). Somente leitura impede que um parceiro altere qualquer coisa, Personalizado define Nenhum, Leitura ou Escrita por recurso (sessões, decisões, mídia, pessoas, empresas e mais), e deixar Incluir mídia desativado impede que um serviço baixe imagens de documentos, selfies, vídeos e relatórios em PDF. Em Limites, uma chave também pode ser restrita a alguns fluxos de trabalho, apenas a sessões aprovadas ou a uma lista de endereços IP: uma solicitação de fora da lista responde 403, e uma sessão fora dos fluxos de trabalho ou dos status da chave responde 404. Abra uma chave para ver exatamente o que ela pode fazer; uma chave nunca pode fazer mais do que o seu acesso permite.
#Quem da sua equipe pode ver as chaves
A visibilidade das chaves segue a função de cada pessoa: ver a página exige permissão para ler chaves de API, que a função Desenvolvedor inclui. Os segredos ficam mascarados no console. 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 no Registro de auditoria atribuídas à chave, não a uma pessoa. É 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.
Ainda com dúvida? Fale com uma pessoa.
Inclua o ID da sua organização e o ID da sessão sobre a qual você está perguntando.