> ## Documentation Index
> Fetch the complete documentation index at: https://documentacao.legitimuz.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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](/platform/tokens).

## Onde a chave pode aparecer

<Columns cols={2}>
  <Card title="Pode" icon="circle-check">
    No header `X-API-Key`, a partir do seu servidor, lida de uma variável de ambiente ou de um cofre
    de segredos.
  </Card>

  <Card title="Não pode" icon="circle-xmark">
    No corpo, na query string, no código do browser, no app, no repositório, em log ou em URL.
  </Card>
</Columns>

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

<Warning>
  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.
</Warning>

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

<Card title="Chaves, escopos e permissões" icon="key" href="/platform/tokens" horizontal>
  O modelo completo no dashboard.
</Card>

## A chave pertence a uma integração

Cada [integração](/platform/integrations#criar-uma-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.

<Steps>
  <Step title="Crie a chave nova">
    Com o mesmo escopo da atual. As duas convivem.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Confirme que a nova está em uso">
    A coluna **Criado em** e o status na tela de chaves mostram qual está ativa.
  </Step>

  <Step title="Revogue a antiga">
    A partir da revogação, qualquer chamada com ela responde `401`.
  </Step>
</Steps>

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

<Columns cols={2}>
  <Card title="Criar verificação" icon="plus" href="/api/create-verification">
    A chamada que usa a chave.
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/api/errors">
    Como distinguir 401, 403 e 422.
  </Card>
</Columns>