# Gerenciando suas chaves de API

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

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.

[Video: Configure chaves de API e teste 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)

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

1. **Faça login no Console de Negócios**

   Acesse [business.didit.me](https://business.didit.me) e faça login.

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

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

![A página Chaves de API no console da 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 você criou.*

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

1. **Clique em Criar chave**

   Em **Desenvolvedores → Chaves de API**.

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

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

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

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

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

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

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

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