Pular para o conteúdo principal
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

CampoPara que serve
NomeIdentifica a chave e o sistema que a utiliza.
ExpiraçãoDefine até quando a chave pode ser usada. Definida apenas quando a chave é criada; não pode ser editada depois.
IP allowlistRestringe uso a endereços ou faixas permitidas quando aplicável.
EscoposLimitam quais áreas da API a chave pode acessar.
AtivaIndica se a chave pode ser usada.
Últimos caracteresAjuda a identificar a chave sem expor o segredo.

​
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

EscopoPermite
ReviewsLer ou operar recursos relacionados a reviews, conforme nível concedido.
WorkspacesLer ou alterar dados do workspace, conforme nível concedido.
CredentialsLer ou alterar metadados de credenciais, conforme nível concedido.
WebhooksLer ou alterar webhooks, conforme nível concedido.
RepositoriesLer ou alterar repositórios, conforme nível concedido.
SecurityScansLer 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

SintomaO que verificar
Chave não autenticaConfirme valor copiado, expiração, status ativo e ambiente correto.
Acesso negadoVerifique escopos e função do workspace.
Funciona localmente, falha em produçãoConfira IP allowlist e origem real da requisição.
Perdi a chave completaRotacione a chave e atualize a integração.
Integração parou após rotaçãoAtualize 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.