Cria chaves de API em Programadores, Chaves de API: uma por serviço, só com o acesso necessário. Guarda-as no servidor, roda-as e resolve os erros 401 e 403.
Programadores → Chaves de API, limitado à aplicação que tens selecionada. Cada aplicação tem uma chave Principal, e podes criar mais, uma por serviço, cada uma com o seu próprio acesso e a sua própria expiração. Uma chave é um segredo do lado do servidor: nunca em código de frontend ou num pacote de aplicação.
As tuas chaves de API estão em Programadores → Chaves de API na consola, limitadas à aplicação em que estás a trabalhar. Trata cada chave como uma palavra-passe: dá acesso à API em nome dessa aplicação.
#Encontrar a tua chave
- Inicia sessão na Consola de Negócio
Vai a business.didit.me e inicia sessão.
- Seleciona a tua aplicação
Escolhe a aplicação no cartão de aplicação no topo da barra lateral. Cada aplicação tem as suas próprias chaves.
- Abre Programadores e depois Chaves de API
O separador Chaves lista todas as chaves, a começar pela chave Principal, com o seu acesso, quando foi usada pela última vez e quando expira.
#Criar uma chave
Dá a cada serviço que chama a Didit a sua própria chave, para poderes ver o que cada um faz e revogá-la isoladamente.
- Prime Criar chave
Em Programadores → Chaves de API.
- Dá-lhe um nome e escolhe o ambiente
Dá à chave o nome do serviço que a vai usar, escolhe Produção (verificações reais, faturadas) ou Sandbox (dados de teste, nunca faturados; a chave é criada na aplicação Sandbox da tua organização), e escolhe quando expira: nunca, ao fim de 30 dias, 90 dias ou um ano, ou numa data à tua escolha.
- Escolhe o seu acesso
Acesso total lê e escreve tudo, para o teu próprio backend. Só de leitura vê sessões, decisões e multimédia mas não pode alterar nada, para um parceiro que só precisa dos resultados. Personalizado permite-te escolher, recurso a recurso. Desmarca Incluir multimédia quando o serviço só precisa da decisão, e não de imagens de documentos de identidade, selfies, vídeos ou relatórios em PDF.
- Revê e copia o segredo
O segredo completo é mostrado uma única vez, quando a chave é criada. Copia-o diretamente para o teu gestor de segredos.
A chave Principal é o segredo original da aplicação. Tem sempre acesso total e pode ser rodada, mas não revogada.
#A chave de API e o segredo de assinatura são coisas diferentes
Vale a pena dizê-lo claramente, porque confundi-los produz erros confusos:
| Para que serve | Onde | |
|---|---|---|
| Chave de API | Autenticar as tuas chamadas à Didit, no cabeçalho x-api-key | Por aplicação, tantas quantas precisares |
| Segredo de assinatura do webhook | Verificar que um webhook recebido veio mesmo da Didit | Por endpoint de webhook |
Enviar o segredo de assinatura como se fosse a tua chave de API produz um 401. Verificar um webhook com a tua chave de API produz uma incompatibilidade de assinatura. Ambos são comuns.
A tua chave de API é um segredo. Nunca a coloques em código de frontend, num repositório público ou num pacote de aplicação móvel - mantém-na apenas no lado do servidor. Uma chave num pacote de aplicação distribuído é uma chave que um atacante já tem. Consulta autenticação de API.
#Obter uma chave para testes
Não testas contra produção. Muda a consola para Sandbox e cria lá uma chave, ou escolhe Sandbox como ambiente quando criares uma. As sessões sandbox simulam todas as verificações externas, nunca são faturadas e não tocam em dados reais de utilizadores.
Uma chave pertence a uma aplicação e, com ela, ao ambiente dessa aplicação: uma chave sandbox nunca cria uma verificação em produção, e uma chave de produção nunca cria uma em sandbox. Vale a pena dar às tuas chaves nomes inequívocos onde quer que guardes os teus segredos. Consulta testar em sandbox.
#Rodar a tua chave
Se uma chave pode ter sido exposta, abre-a e escolhe Rodar chave. Recebes um segredo novo, e o antigo continua a funcionar durante 24 horas, para poderes implementar o segredo novo sem interrupções. Depois disso, todos os pedidos com o segredo antigo devolvem um 401.
Se uma chave tem de deixar de funcionar já, usa antes Revogar chave. Revogar para-a de imediato e não pode ser anulado. A chave Principal só pode ser rodada.
Rodar a chave com regularidade é boa prática. Planeia-o como um deploy, não como um clique.
#Resolver os erros 401 e 403
| Erro | Causa | Solução |
|---|---|---|
401 | A chave está em falta, mal formada, expirada, revogada, ou foi rodada há mais de 24 horas | Verifica a chave em Programadores → Chaves de API para essa aplicação. Procura espaços em branco ou aspas a mais, e confirma que não colaste um segredo de assinatura por engano |
403 | A chave é válida mas esta chamada não é permitida | Normalmente a aplicação errada, um campo exclusivo de sandbox numa chave de produção (ou o inverso), um acesso que não foi dado à chave (uma chave só de leitura a tentar escrever, por exemplo), ou uma funcionalidade não ativada na tua conta |
Um 403 num fluxo de trabalho específico quase sempre significa que a chave pertence a uma aplicação diferente daquela a que pertence esse fluxo de trabalho. Muda de aplicação na consola e usa antes uma das chaves dessa aplicação. Detalhe completo: erros de API e o que significam.
#Restringir o que uma chave pode fazer
Escolhe o acesso quando criares a chave, e altera-o mais tarde com Editar acesso (o segredo mantém-se; o acesso da chave Principal não pode ser editado). Só de leitura impede um parceiro de alterar o que quer que seja, Personalizado define Nenhum, Leitura ou Escrita por recurso (sessões, decisões, multimédia, pessoas, empresas e mais), e deixar Incluir multimédia desligado impede um serviço de descarregar imagens de documentos de identidade, selfies, vídeos e relatórios em PDF. Em Limites, uma chave pode também ficar restrita a alguns fluxos de trabalho, apenas a sessões aprovadas, ou a uma lista de endereços IP: um pedido de fora da lista responde 403, e uma sessão fora dos fluxos de trabalho ou estados da chave responde 404. Abre uma chave para veres exatamente o que pode fazer; uma chave nunca pode fazer mais do que o seu acesso permite.
#Quem na tua equipa pode ver 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 Programador inclui. Os segredos ficam mascarados na consola. Se um colega de equipa não encontrar a página, verifica a sua função antes de reportares o problema. Consulta convidar membros da equipa e definir funções.
#Cada chamada é registada
Os pedidos feitos com chave de API aparecem no Registo de auditoria atribuídos à chave e não a uma pessoa. É exatamente por isso que partilhar uma chave entre vários serviços torna um incidente mais difícil de investigar: uma chave por consumidor é mais fácil de analisar. Consulta usar os registos de auditoria.
Continua com dúvidas? Fale com uma pessoa.
Inclua o ID da sua organização e o ID da sessão sobre a qual pergunta.