> ## 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.
# API Keys
> Crie e administre chaves de acesso programático à API pública da Acrity.
API Keys permitem que sistemas externos acessem a API pública da Acrity em nome de um workspace.
Use `Console > API Keys` para criar, editar metadados, ativar, desativar, rotacionar e remover chaves.
## Quando usar
Use API Keys quando:
* uma automação precisa consultar dados da Acrity;
* um sistema interno precisa acionar operações suportadas pela API pública;
* integrações precisam de autenticação estável por workspace;
* webhooks não são suficientes porque o sistema externo precisa buscar dados sob demanda.
Use webhooks quando o sistema externo só precisa receber eventos.
## Quem pode acessar
Gerenciar API Keys requer um admin de workspace. Criar uma API Key também requer um admin de workspace.
## Formato de autenticação
Sistemas externos devem enviar a chave conforme a documentação da API pública. A tela de criação mostra a chave completa apenas uma vez.
Guarde a chave em um cofre seguro no momento da criação. Depois que a tela for fechada, a chave completa não poderá ser exibida novamente.
## Campos principais
| Campo | Para que serve |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| Nome | Identifica a chave e o sistema que a utiliza. |
| Expiração | Define até quando a chave pode ser usada. Definida apenas quando a chave é criada; não pode ser editada depois. |
| IP allowlist | Restringe uso a endereços ou faixas permitidas quando aplicável. |
| Escopos | Limitam quais áreas da API a chave pode acessar. |
| Ativa | Indica se a chave pode ser usada. |
| Últimos caracteres | Ajuda a identificar a chave sem expor o segredo. |
## Criar uma API Key
Acesse `Console > API Keys`.
Escolha `Nova API Key`.
Use um nome que identifique sistema, ambiente e dono da integração.
Escolha um período de validade. A expiração é definida apenas na criação e não pode ser alterada depois.
Restrinja a chave aos IPs esperados quando possível.
Conceda apenas os escopos necessários.
Copie a chave exibida uma única vez e armazene em cofre seguro.
## Expiração
Opções de expiração podem incluir:
* sem expiração;
* 1 hora;
* 1 dia;
* 7 dias;
* 30 dias;
* 90 dias;
* 180 dias;
* 360 dias.
Prefira expiração definida para integrações temporárias, testes ou ambientes não produtivos.
A expiração é definida apenas quando a chave é criada e não pode ser editada depois. Para usar uma expiração diferente, crie uma nova chave.
## IP allowlist
IP allowlist limita o uso da chave a origens conhecidas.
Use quando:
* a integração roda em infraestrutura com IP fixo;
* a organização exige controle de origem;
* a chave tem escopos de escrita;
* a integração é crítica.
Revise a allowlist após mudanças de infraestrutura, NAT, proxy ou provedor em nuvem.
## Escopos
| Escopo | Permite |
| ------------- | --------------------------------------------------------------------------- |
| Reviews | Ler ou operar recursos relacionados a reviews, conforme nível concedido. |
| Workspaces | Ler ou alterar dados do workspace, conforme nível concedido. |
| Credentials | Ler ou alterar metadados de credenciais, conforme nível concedido. |
| Webhooks | Ler ou alterar webhooks, conforme nível concedido. |
| Repositories | Ler ou alterar repositórios, conforme nível concedido. |
| SecurityScans | Ler ou operar recursos de varredura de segurança, conforme nível concedido. |
Escopos de escrita normalmente incluem a capacidade de leitura correspondente. Conceda escrita apenas quando a integração realmente precisar alterar dados.
## Rotacionar uma chave
Rotação gera um novo segredo para a mesma chave lógica.
Fluxo recomendado:
1. Acesse `Console > API Keys`.
2. Na lista de chaves, localize a chave e escolha `Rotate` nas ações da linha.
3. Confirme a rotação na caixa de diálogo.
4. Copie o novo valor exibido.
5. Atualize o sistema externo.
6. Valide a integração.
7. Remova segredos antigos do cofre ou ambiente de execução.
Após rotação, o segredo anterior deixa de funcionar. Planeje a troca para evitar interrupção.
## Desativar ou excluir
Desative uma chave quando quiser interromper temporariamente o acesso sem perder histórico administrativo.
Exclua quando:
* a integração foi removida;
* o sistema não existe mais;
* a chave foi criada por engano;
* a política da organização exige remoção definitiva.
## Boas práticas
* Crie uma chave por sistema e ambiente.
* Use nomes claros, como `billing-sync-prod`.
* Aplique o menor escopo possível.
* Configure expiração quando viável.
* Use IP allowlist para integrações críticas.
* Guarde em cofre seguro, nunca em código-fonte.
* Rotacione periodicamente.
* Desative chaves sem uso.
## Problemas comuns
| Sintoma | O que verificar |
| -------------------------------------- | ------------------------------------------------------------------- |
| Chave não autentica | Confirme valor copiado, expiração, status ativo e ambiente correto. |
| Acesso negado | Verifique escopos e função do workspace. |
| Funciona localmente, falha em produção | Confira IP allowlist e origem real da requisição. |
| Perdi a chave completa | Rotacione a chave e atualize a integração. |
| Integração parou após rotação | Atualize o segredo no sistema externo e redeploy quando necessário. |
## Segurança
O segredo completo é mostrado apenas uma vez e não deve ser armazenado em texto puro fora de um cofre seguro. A proteção técnica de chaves e tokens é descrita em `Segurança > Credenciais e tokens`.