Skip to main content
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

​
Criar uma API Key

1

Abrir API Keys

Acesse Console > API Keys.
2

Criar nova

Escolha Nova API Key.
3

Nomear

Use um nome que identifique sistema, ambiente e dono da integração.
4

Definir expiração

Escolha um período de validade. A expiração é definida apenas na criação e não pode ser alterada depois.
5

Configurar IP allowlist

Restrinja a chave aos IPs esperados quando possível.
6

Escolher escopos

Conceda apenas os escopos necessários.
7

Salvar e guardar

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

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

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