Autenticação (referência)

Security scheme OpenAPI, formato detalhado da chave, comportamento de validação.

Security scheme

A API usa o esquema OpenAPI HTTP Bearer.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

Toda operação exige security: [{ bearerAuth: [] }] no OpenAPI.

Formato da chave

crm_<env>_<prefixo>_<segredo>

Parte	Valor	Notas
Prefixo	`crm_`	Fixo
Ambiente	`live` ou `test` (futuro)	`test` ainda não disponível
Prefixo público	12 caracteres hexadecimais	Identificador visual da chave (não secreto)
Segredo	32+ caracteres `[A-Za-z0-9_-]`	Gerado por CSPRNG no servidor

Exemplo: crm_live_a1b2c3d4e5f6_AbCdEfGhIjKlMnOpQrStUvWxYz012345

A chave é exibida uma única vez no console no momento da criação. Não temos como recuperá-la depois. Armazene em cofre.

Header esperado

Authorization: Bearer ofm_live_<random>

Casos rejeitados

Header	Resultado
Sem `Authorization`	401 `code: missing_api_key`
`Authorization: <random>` (sem Bearer)	401 `code: missing_api_key`
`Authorization: Bearer <chave-falsa>`	401 `code: invalid_api_key`
`Authorization: Bearer <chave-revogada>`	401 `code: revoked_api_key`
`Authorization: Bearer <chave-expirada>`	401 `code: expired_api_key`
Chave válida + escopo insuficiente	403 `code: missing_scope`

Escopos requeridos por endpoint

Endpoint	Escopos necessários
`GET /contacts/message-search`	`contacts:read` + `messages:read`

Hash e armazenamento

A chave em texto-claro nunca é persistida em texto-claro no servidor
Armazenamos um hash SHA-256 + prefixo (ofm_live_a1b2c3d4) para identificação visual
Comparação em tempo constante (crypto.timingSafeEqual) para evitar timing attacks

Auditoria

Toda chamada com chave válida gera entrada de auditoria com:

api_key_id (não a chave em si)
endpoint, method, status
organization_id
requested_scopes, granted_scopes
timestamp, ip, user_agent

Acesse via Configurações → API → [chave] → Histórico.

Sessão de browser (uso interno)

O mesmo endpoint aceita também autenticação via cookie de sessão para o time interno usando o CRM logado. Esse modo é detectado automaticamente quando o header Authorization: Bearer ... está ausente.

Para integrações externas, sempre use Bearer API key — o caminho de cookie depende de same-origin e não funciona cross-domain.

On this page