API Keys da organização

API keys são credenciais que sistemas externos usam para autenticar no SmartPerformance SFA (ADR-028). Servem a dois usos:

Webhook de entrada em modo API key — a alternativa mais fácil ao HMAC: o cliente só manda um token num header, sem assinar o corpo.
Ler a API como máquina (ADR-034) — um serviço externo manda x-api-key em qualquer rota e é autenticado sem sessão humana. É como o backend Wessel puxa os registros canônicos.

Como funciona

O token tem o formato sfa_<prefixo>_<segredo> e é revelado uma única vez na criação — guardamos só o hash (SHA-256) e o prefixo visível (para você identificar a key sem expor o segredo).
A validação faz o hash do token apresentado e busca por índice único — timing-safe por construção.
Uma key pode expirar (opcional) e ser revogada (invalida na hora, mantém o histórico).

Controle de uso

Cada uso registra: incrementa o contador, grava último uso + IP, e adiciona uma linha no log de atividade (quando, rota, IP). A página API Keys mostra tudo — útil para auditar quem está usando e com que frequência.

Rate-limiting

Hoje o controle de uso rastreia (não bloqueia por limite). Rate-limit por key é follow-up (ADR-028).

Criar e usar

Em API Keys, crie uma key (nome + validade opcional) → copie o token (só aparece agora).
No endpoint de webhook de entrada, escolha Autenticação: API key e o header (default x-api-key).
O sistema externo envia o token nesse header (ou Authorization: Bearer <token>):

curl -X POST "https://SUA-API/api/webhooks/ingest/<publicId>" \
  -H "content-type: application/json" \
  -H "x-api-key: sfa_ab12cd34_...seutoken..." \
  -d '{"cnpj":"12345678000190"}'
# token inválido/expirado/revogado -> 401

Qualquer key ativa da organização autentica (a key é da org, não do endpoint) — então uma key serve vários endpoints/integrações, e o uso é visível de forma central.

Chamar a API como máquina (ADR-034)

A mesma key autentica qualquer rota da API pelo header x-api-key — sem login, sem token de sessão. Como o hash da key é único global, ela sozinha já identifica a organização: o chamador externo não manda orgId.

curl "https://SUA-API/api/integrations/entities/client/records?page=1&pageSize=200" \
  -H "x-api-key: sfa_ab12cd34_...seutoken..."

Permissões fixas e amplas a todas as keys

Uma key autenticada recebe hoje um conjunto fixo: apenas integration:read (ler o canônico). Não dá para configurar conector nem disparar sincronização por API key.

O modelo ApiKey ainda não tem escopo por key, então esse conjunto vale para todas as keys da plataforma — ampliá-lo amplia o poder de todas. Escopo por key (ApiKey.scopes) é follow-up.

Uma key inválida, expirada ou revogada resulta em 401 e não cai para o JWT: quem apresentou uma API key quis autenticar por ela, e o fallback silencioso transformaria "chave errada" em "sem token".

API vs HMAC — quando usar qual

	API key	HMAC
Fricção pro cliente	Baixíssima (um header)	Alta (assina o corpo a cada request)
Segurança	Boa sobre HTTPS; o token viaja a cada request	Mais forte: segredo não trafega + integridade do corpo
Recomendação	Default — onboarding fácil	Clientes que exigem mais garantias

Ver Assinatura HMAC para o modo HMAC.

API (Scalar)

Sob /api/api-keys (RBAC apikey:read/apikey:write): GET/POST /, GET /:id/usages, POST /:id/revoke, DELETE /:id. Esquemas na Referência da API (tag API Keys).

Como funciona​

Controle de uso​

Criar e usar​

Chamar a API como máquina (ADR-034)​

API vs HMAC — quando usar qual​

API (Scalar)​