Chaves de API

Crie a chave que autentica o seu servidor, conceda só o escopo necessário e rotacione sem downtime.

A chave de API autentica o seu servidor na Legitimuz. Ela fica em Integrações → Segurança → Chaves de API, dentro da integração a que pertence.

Uma chave de uma integração não cria nem lê verificação de outra. Isso limita o vazamento de uma chave ao canal dela. Veja permissões de leitura.

Criar uma chave

1. Clique em Nova Chave
2. Conceda só o escopo necessário

   Uma chave carrega um subconjunto das permissões da conta. Para criar verificações, ela precisa de uma só: criar verificação.

   A listagem mostra o escopo como N de 27 Permissões. Quanto menor o N, menor o alcance de um vazamento.

3. Copie o valor agora

   A chave aparece uma única vez. Não há como recuperá-la depois, só criar outra. Guarde-a no cofre de segredos do seu backend, nunca no repositório.

A chave tem o prefixo lz_. Na listagem ela aparece mascarada, e assim permanece.

Permissões de leitura

Além de criar verificações, a chave pode ler dados e imagens pelas rotas listar verificações e baixar imagens. As três permissões de leitura nascem desmarcadas: conceda só as que o seu backend usa. O dashboard só deixa conceder o que o seu papel já tem.

Permissão	O que libera
Ver verificações	Listar verificações.
Ver mídia da verificação	Baixar a selfie e o documento. Só vale junto de Ver verificações.
Ver dados cadastrais desmascarados	Receber CPF, nome, nome da mãe e nascimento sem máscara.

Fora do dashboard, a chave também precisa do IP de saída do seu servidor liberado pela Legitimuz. Fale com o suporte e informe o endereço fixo ou a faixa CIDR.

A chave de leitura alcança CPF e imagens de todos os titulares da integração dela. Use uma chave só para leitura, e se alguma chave sua já tem Ver verificações, revise o escopo dela e desmarque a permissão nas que não a usam. A chave lê só as verificações da própria integração: as de outra integração da conta não aparecem, e uma chave de sandbox lê só sandbox.

Usar a chave

curl -X POST https://api-core.legitimuz.com/public/verifications \
  -H "X-API-Key: $LEGITIMUZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "schema_version": "1.0", "...": "..." }'

A API aceita a chave apenas no header X-API-Key. Corpo e query string são recusados.

Pode

No header, a partir do seu servidor, lida de uma variável de ambiente ou de um cofre de segredos.

Não pode

No corpo, na query string, no código do browser, no app, no repositório, em log ou em URL.

Ciclo de vida

Status	O que significa
Ativa	autentica chamadas normalmente
Revogada	qualquer chamada com ela responde 401
Arquivada	revogada e fora da listagem principal

Rotacionar sem downtime

1. Crie a chave nova com o mesmo escopo

   As duas convivem. Nada quebra.

2. Publique o valor novo e faça o deploy

   Deixe a antiga ativa até confirmar que a nova está em uso.

3. Revogue a antiga

   A partir daí, qualquer chamada com ela responde 401.

Rotacione quando alguém com acesso à chave sair do time, na suspeita de vazamento, e periodicamente.

Se uma chave vazou

1. Crie uma chave nova e publique-a.
2. Revogue a vazada. Apagar o arquivo onde ela estava não basta: se ela chegou a um repositório, está no histórico para sempre.
3. Revise as verificações criadas no período.

Autenticação na API

O contrato do lado do código, com os erros 401, 403 e 422.

Próximo passo

5. Domínios

Autorize onde a verificação pode abrir.