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

# Segurança de API keys

> Como criar, limitar, rotacionar e proteger chaves da API pública da Acrity.

API keys permitem que automações chamem a API pública da Acrity sem usar uma sessão humana do Console. Elas são gerenciadas em `Console > API Keys`, o que requer um admin do Workspace.

## Autenticação

Envie a API key no header `X-Acrity-Key`:

```bash theme={null}
curl \
  -H "X-Acrity-Key: acr_live_..." \
  "https://acrity.io/api/v1/context"
```

<Warning>
  Não envie API keys em query string, logs, screenshots ou tickets de suporte. Use headers e cofre de segredos.
</Warning>

## Armazenamento

A chave completa é exibida apenas uma vez, logo após criação ou rotação. A Acrity não armazena o plaintext da API key. Para validar chamadas futuras, a Acrity armazena um hash HMAC-SHA-256 com pepper.

## Escopos

Ao criar uma chave, selecione apenas os escopos necessários.

| Escopo                | Uso típico                                               |
| --------------------- | -------------------------------------------------------- |
| `Reviews.Read`        | listar reviews, decisões e achados                       |
| `Reviews.Write`       | solicitar reviews pela API                               |
| `Repositories.Read`   | listar e consultar repositórios conectados               |
| `Repositories.Write`  | conectar, atualizar ou desconectar repositórios pela API |
| `Credentials.Read`    | consultar metadados de credenciais                       |
| `Credentials.Write`   | criar ou alterar credenciais pela API                    |
| `Webhooks.Read`       | listar webhooks configurados                             |
| `Webhooks.Write`      | criar, alterar ou desativar webhooks                     |
| `Workspaces.Read`     | consultar contexto e dados do workspace                  |
| `Workspaces.Write`    | alterar configurações permitidas do workspace            |
| `SecurityScans.Read`  | listar e consultar scans de segurança                    |
| `SecurityScans.Write` | iniciar scans sob demanda                                |

Escopos de escrita implicam maior risco operacional. Prefira uma chave separada para cada automação.

## Expiração e IP allowlist

Ao criar uma API key, configure:

* uma expiração compatível com o uso da automação — a expiração é escolhida na criação e não pode ser alterada depois; para usar um período de validade diferente, crie uma nova chave;
* uma IP allowlist quando a integração roda em infraestrutura conhecida;
* um nome descritivo com dono, sistema e ambiente;
* os escopos mínimos necessários.

## Rotação

Rotacionar uma API key gera um novo valor e invalida o segredo anterior. Atualize o cofre de segredos e a automação consumidora imediatamente após a rotação.

<Steps>
  <Step title="Rotacionar no Console">
    Acesse `Console > API Keys`, encontre a chave na lista e escolha `Rotate` nas ações da linha.
  </Step>

  <Step title="Guardar o novo valor">
    Copie a chave exibida uma única vez para o cofre de segredos.
  </Step>

  <Step title="Atualizar a automação">
    Atualize o segredo usado pela integração e reinicie o serviço consumidor quando necessário.
  </Step>

  <Step title="Validar">
    Faça uma chamada simples em `/api/v1/context` para confirmar autenticação, escopos e workspace.
  </Step>
</Steps>

## Respostas comuns

| Status | Significado provável                         | Ação                                                |
| ------ | -------------------------------------------- | --------------------------------------------------- |
| `401`  | chave ausente, inválida, expirada ou inativa | verifique o header e o estado da key no Console     |
| `403`  | chave válida, mas sem escopo necessário      | adicione o escopo ou crie uma chave separada        |
| `429`  | limite de uso atingido                       | reduza concorrência, aplique backoff e revise o uso |