Autenticação

A chave de API: formato, escopo, onde ela pode aparecer e como rotacionar sem downtime.

A API pública autentica por chave, no header X-API-Key.

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

A chave tem o prefixo lz_ e é criada em Integrações → Segurança → Chaves de API.

Onde a chave pode aparecer

Pode

No header X-API-Key, 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.

A API recusa a chave no corpo e na query. Não é uma convenção: é o comportamento da rota.

Chave em query string entra no log de qualquer proxy, CDN ou balanceador no caminho, e em log, ela fica. Se isso já aconteceu, rotacione; apagar o log não resolve.

Escopo

Uma chave não é um passe geral. Ela carrega um conjunto de permissões, escolhido na criação.

Para criar verificações, a chave precisa só da permissão de criar verificação. Conceder mais que isso amplia o estrago de um vazamento sem trazer nenhum benefício.

Uma chave válida sem a permissão certa responde 403 E_FORBIDDEN, diferente de 401, que é chave ausente, inválida, expirada ou revogada.

Chaves, escopos e permissões

O modelo completo no dashboard.

A chave pertence a uma integração

Cada integração tem as próprias chaves. Uma chave da integração de homologação não cria verificação na de produção.

É o que faz o vazamento de uma credencial não alcançar os outros canais do seu produto, e é o motivo de criar uma integração por canal, em vez de reaproveitar uma.

Rotacionar sem downtime

A chave aparece uma única vez, na criação. Não há como recuperá-la depois.

1. Crie a chave nova

   Com o mesmo escopo da atual. As duas convivem.

2. Publique o valor novo

   Atualize o cofre de segredos e faça o deploy. Não troque a variável no mesmo instante em que revoga a antiga.

3. Confirme que a nova está em uso

   A coluna Criado em e o status na tela de chaves mostram qual está ativa.

4. Revogue a antiga

   A partir da revogação, qualquer chamada com ela responde 401.

Rotacione quando alguém com acesso à chave sair do time, quando houver 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, ela está no histórico do git para sempre.
3. Revise as verificações criadas no período.

Próximo passo

Criar verificação

A chamada que usa a chave.

Erros

Como distinguir 401, 403 e 422.