Gerar API Key

API Key é a credencial que autoriza sistemas externos (n8n, scripts próprios, ERP) a chamar a API REST do Syncro. Sem ela, nenhum endpoint da /api/v1/* responde. Esse artigo cobre criar, gerenciar e revogar keys.

Pré-requisitos

• Permissão admin no Syncro.
• Plano Starter, Growth ou Scale (Free não tem API).

Acessar API Keys

1. Menu lateral → Configurações → API / Webhooks (ou rota /configuracoes/api-keys).
2. Página mostra:

• Suas API Keys com lista de keys cadastradas.
• Botão Nova API Key.

Criar nova key

1. Clique em Nova API Key.
2. Modal abre.
3. Preencha:

• Nome (obrigatório, max 100 chars): identificador interno. Ex: "n8n Production", "Script Python ERP", "Webhook Wordpress".

4. Clique em Criar key.
5. Sistema:

• Gera token raw: crm_ + 56 chars hex (60 chars total).
• Calcula hash SHA-256 do token.
• Salva apenas o hash no banco (key_hash).
• Salva prefixo (12 primeiros chars + ...) pra display.
• Permissions default: ['*'] (acesso total).

6. Modal mostra token raw COMPLETO:

crm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

⚠️ Atenção: token aparece APENAS UMA VEZ. Copie e guarde imediatamente. Se perder, você precisa gerar nova key.

Como usar a key

Em qualquer chamada à API, inclua header:

X-API-Key: crm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

Exemplo cURL:

curl -X GET "https://app.syncro.chat/api/v1/leads" \
 -H "X-API-Key: crm_a1b2c3..."

Sem o header (ou com key inválida): retorna 401 Unauthorized.

O que aparece na lista

Cada key cadastrada mostra:

💡 Dica: você nunca vê token completo depois da criação. Sistema só guarda hash. Se você esquecer, revogue e crie nova.

Permissões (scopes)

Por padrão, key tem acesso total (['*']). Pra restringir scope, edite permissions_json (UI atual não expõe — use SQL ou API direto):

💡 Dica: pra n8n público, considere scope mínimo (apenas leads:read se só consulta). Reduz risco se token vazar.

Rate limit

Cada key tem rate limit de 60 requisições por minuto:

• Counter no Redis com chave api-key:{id}.
• Quando hit ultrapassa, retorna 429 Too Many Requests com Retry-After header.

💡 Dica: pra throughput maior, distribua entre múltiplas keys (ex: 1 key por workflow n8n).

Atualização de last_used_at

Cada chamada atualiza last_used_at = now na key. Útil pra:

• Identificar keys abandonadas (last_used > 30 dias).
• Auditoria de uso.
• Detecção de vazamento (chamadas inesperadas).

Revogar key

Pra desativar imediatamente:

1. Em /configuracoes/api-keys, encontre a key.
2. Botão Revogar (ícone lixeira).
3. Confirme.
4. Sistema marca is_active = false.
5. Próximas requests com essa key → 401 Unauthorized.

⚠️ Atenção: revogação é imediata e irreversível. Sistemas usando essa key param de funcionar.

Quando revogar

Sinais de que deve revogar uma key:

• ✅ Você trocou de ferramenta (n8n por Zapier).
• ✅ Suspeita de vazamento (token apareceu em screenshot, log público).
• ✅ Funcionário saiu da empresa (key estava no laptop dele).
• ✅ Auditoria periódica (revoga keys com last_used > 90 dias).

Boas práticas

1. Uma key por integração

❌ Não use a mesma key pra n8n + script + Zapier. ✅ Crie uma pra cada — facilita revogação seletiva.

2. Nome descritivo

✅ "n8n Production - Workflows de Lead" ❌ "Key 1", "Test"

3. Armazene em vault

Não cole token em código fonte ou commits. Use:

• Vault do n8n (Credentials).
• Variáveis de ambiente em scripts.
• Secret manager (1Password, Bitwarden, AWS Secrets Manager).

4. Rotacione anualmente

Crie key nova, atualize sistemas, revogue antiga. Reduz exposure se token vazou em algum momento.

5. Audit periódico

Trimestralmente:

• Revise last_used_at de cada key.
• Revogue as não usadas há 90+ dias.
• Documente quais sistemas usam quais keys (planilha interna).

Limites

• Sem limite oficial de keys por tenant.
• Mas rate limit é por key (60 req/min) — múltiplas keys = mais throughput.
• Sem expiração automática (expires_at campo existe mas não é exposto na UI hoje).

Erros comuns

"401 Unauthorized — API Key inválida"

• Token errado ou copiado parcial.
• Key foi revogada.
• Tenant suspenso ou em trial expirado.

"401 — API Key não fornecida"

Header X-API-Key ausente ou nome errado. Garanta hifenação correta.

"429 — Rate limit excedido"

60 req/min ultrapassado. Aguarde 1 minuto. Implemente rate limiting próprio no seu lado (sleep entre requests).

"403 — Sem permissão pra esta operação"

Key tem scope restrito que não cobre o endpoint. Edite permissions_json ou use key com ['*'].

"Modal fechou e perdi a key"

Não tem como recuperar. Revogue e crie nova.

Próximos passos

• Pra ver lista de endpoints, veja Endpoints disponíveis.
• Pra criar lead via API, veja Criar lead via API.

Artigos relacionados

• Endpoints disponíveis
• Criar lead via API
• Webhooks de saída
• n8n Community Node