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

# 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 verificação em outra. É o que faz o vazamento de uma credencial
não alcançar os outros canais do seu produto.

## Criar uma chave

<Steps>
  <Step title="Clique em Nova Chave" />

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

  <Step title="Copie o valor agora">
    <Warning>
      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.
    </Warning>
  </Step>
</Steps>

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

## Usar a chave

```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 API aceita a chave apenas no header `X-API-Key`. Corpo e query string são recusados.

<Columns cols={2}>
  <Card title="Pode" icon="circle-check">
    No header, 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-x">
    No corpo, na query string, no código do browser, no app, no repositório, em log ou em URL.
  </Card>
</Columns>

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

<Steps>
  <Step title="Crie a chave nova com o mesmo escopo">
    As duas convivem. Nada quebra.
  </Step>

  <Step title="Publique o valor novo e faça o deploy">
    Deixe a antiga ativa até confirmar que a nova está em uso.
  </Step>

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

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.

<Card title="Autenticação na API" icon="terminal-2" href="/start/authentication" horizontal>
  O contrato do lado do código, com os erros 401, 403 e 422.
</Card>

## Próximo passo

<Card title="5. Domínios" icon="world" href="/platform/domains" horizontal>
  Autorize onde a verificação pode abrir.
</Card>