# Gerir as tuas chaves de API

Source: https://help.didit.me/pt-PT/account-organization/api-keys
Updated: 2026-10-12

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.

[Video: Configurar chaves de API e testar os seus webhooks - Didit Academy](https://www.youtube.com/watch?v=thOMIGbNLP0&t=38)

[Video: Integração da API KYC em 5 passos, com um prompt de configuração de IA para o Cursor - Didit Academy](https://www.youtube.com/watch?v=kTAarcImy7E)

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

1. **Inicia sessão na Consola de Negócio**

   Vai a [business.didit.me](https://business.didit.me) e inicia sessão.

2. **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.

3. **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.

![A página Chaves de API na consola Didit com a lista de chaves](https://help.didit.me/screenshots/api-keys-light.webp)

*Todas as chaves desta aplicação: primeiro a chave Principal, depois as que criaste.*

## 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.

1. **Prime Criar chave**

   Em **Programadores → Chaves de API**.

2. **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.

3. **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.

4. **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.

> **Warning:** 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](https://docs.didit.me/getting-started/api-authentication).

## 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](https://help.didit.me/pt-PT/getting-started/sandbox-and-testing).

## 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](https://help.didit.me/pt-PT/integration/api-errors).

## 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](https://help.didit.me/pt-PT/account-organization/team-members-and-roles).

## 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](https://help.didit.me/pt-PT/account-organization/audit-logs).