Criando uma API Key

API Keys são chaves de acesso permanentes (até serem revogadas) que sistemas externos usam pra consumir a Public API do CRM. Cada chave tem:

• Scopes: quais recursos e operações pode acessar (ex: contacts:read, deals:write)
• Rate limit: chamadas por minuto (default 100, máximo 1000)
• Expiração opcional: data limite (útil pra integrações temporárias)
• Logs: histórico das últimas 100 chamadas pra auditoria

Quem pode criar

Apenas usuários com role Admin ou Super Admin gerenciam API Keys. Vendedores comuns não podem. Essa restrição é importante: uma chave concede acesso a dados PII e a decisão de criar/revogar é administrativa.

Como gerar

1. Logado como admin, vá em Configurações (engrenagem no canto inferior esquerdo) → Integrações
2. Clique no tile API Keys (ícone de chave, roxo)
3. Botão Nova API Key no canto superior direito
4. Preencha:
   • Nome (obrigatório, ex: “Zapier — sync contatos”)
   • Descrição (opcional, mas recomendado pra documentar o uso)
   • Scopes (marque os mínimos necessários — princípio do menor privilégio)
   • Expiração (nunca, 30 dias, 90 dias, 1 ano)
   • Rate limit (default 100 req/min — ajuste em “Avançado” se precisar)
5. Clique Criar

Segredo exibido uma única vez

Ao criar, o segredo crm_live_xxxxx... aparece na tela. Essa é a única vez que você vai vê-lo. Copie e guarde num cofre de senhas (1Password, Bitwarden, AWS Secrets Manager, etc.). Depois disso só ficamos com o hash no banco — não há como recuperar.

Se você perder, gere uma nova chave e revogue a antiga.

Princípio do menor privilégio

Quando estiver escolhendo scopes:

• Integração só lê dados? Marque apenas *:read (ex: contacts:read)
• Integração também escreve? Adicione *:write apenas dos recursos necessários
• Evite * (wildcard) — concede acesso total. Use só pra scripts de admin internos.

Exemplo: pra um Zap “novo lead no formulário → criar contato no CRM”, basta contacts:write.

Onde armazenar a chave

• Variáveis de ambiente (.env, process.env.CRM_API_KEY)
• Secret managers (AWS Secrets Manager, GCP Secret Manager, Vault)
• Cofres de senhas (1Password, Bitwarden — só pra equipe humana acessar)

Nunca:

• Committe no git
• Coloque em URLs (query string)
• Compartilhe por e-mail/Slack sem criptografia

Revogar uma chave

Se uma chave vazou ou não é mais necessária:

1. Vá em Configurações → Integrações → API Keys
2. Clique no ícone de lixeira ao lado da chave
3. Confirme na modal

A revogação é imediata — em até 60 segundos sistemas usando a chave começam a receber 401 invalid_api_key. O histórico de uso fica preservado pra auditoria.

A revogação é soft-delete: o registro continua no banco com revokedAt preenchido, mas a chave não autentica mais.

Auditoria — quem usou a chave

Cada API Key tem um log de chamadas que mostra:

• Método HTTP + path
• Status code da resposta
• Latência
• IP de origem
• User-agent
• Fragmento de erro (quando 4xx/5xx)

Pra ver: clique no ícone de “scroll” (📜) ao lado da chave na lista. O drawer atualiza em tempo real (refresh a cada 10 segundos) — útil pra debug enquanto você testa uma integração.

O log mostra as últimas 100 chamadas. Pra auditoria histórica completa, consulte o banco diretamente (tabela api_key_audit_logs).