Gerir as tuas chaves de API
Encontra a tua chave de API em API e Webhooks na consola, mantém-na no lado do servidor, usa uma aplicação sandbox separada para testes, e resolve os erros 401 e 403.
API e Webhooks, limitado à aplicação que tens selecionada. Uma chave por aplicação, e a chave é o ambiente - não existe uma chave de teste separada numa aplicação em produção. É um segredo do lado do servidor: nunca em código de frontend ou num pacote de aplicação.
A tua chave de API está em API e Webhooks na barra lateral da consola, limitada à aplicação em que estás a trabalhar. Trata-a como uma palavra-passe - dá acesso total à 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 que queres na lista pendente no topo da consola. Cada aplicação tem a sua própria chave.
- Abre API e Webhooks
A tua chave de API está aqui, ao lado dos teus destinos de webhook e dos respetivos segredos de assinatura.
- Create API key emite uma chave nova; as chaves são por aplicação.
- O segredo é mostrado aqui apenas uma vez - copia-o para o teu próprio cofre de segredos.
- Rotate secret substitui o segredo sem alterar o nome da chave.
- Last used é como distingues uma chave ativa de uma esquecida antes de a revogares.
#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 |
| Segredo de assinatura do webhook | Verificar que um webhook recebido veio mesmo da Didit | Por destino |
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. Cria uma aplicação separada em modo sandbox - as sessões sandbox simulam todas as verificações externas, nunca são faturadas e não tocam em dados reais de utilizadores. Usa a sua chave enquanto constróis, e mantém uma aplicação em produção separada para verificações reais.
Não existe uma "chave de teste" numa aplicação em produção. A chave é o ambiente, por isso 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, gera-a de novo na mesma página API e Webhooks. Gerar de novo invalida a chave antiga imediatamente, por isso atualiza-a primeiro em todos os sítios onde é usada - caso contrário o teu tráfego em produção começa a falhar no momento em que clicas no botão.
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, ou foi gerada de novo | Copia a chave atual de API e Webhooks para essa aplicação. Verifica se há espaços em branco ou aspas a mais, e se 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), uma permissão que a tua chave não tem, 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 copia a chave dessa em vez disso. Detalhe completo: erros de API e o que significam.
#Restringir o que uma chave pode fazer
Se o que precisas é limitar a que categorias de dados uma chave consegue aceder - por exemplo, impedir que um serviço obtenha imagens de documentos - isso é uma questão de permissões e não uma definição de chave, e o que está disponível depende da tua conta. Pergunta ao suporte em vez de presumires que uma chave não tem restrições, ou de presumires que as tem; ambas as suposições são arriscadas em direções opostas.
#Quem na tua equipa pode ver chaves
A visibilidade das chaves segue a função de cada pessoa. A função Programador inclui as chaves de API; a Leitor não. 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 em Registos de Auditoria atribuídos à aplicação e não a uma pessoa - o que é exatamente a razão pela qual 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.