Autenticação

API Key (rotas /v1/*)

Todas as rotas tenant‑scoped exigem o header x-api-key:

x-api-key: <API_KEY>

Características:

• A chave é emitida pelo Nexus para um tenant. Internamente, o Nexus resolve o tenant pelo hash SHA‑256 da chave (a chave em texto claro nunca é armazenada).
• Respostas 401 retornam corpo em texto puro (não usam o envelope JSON):
  • Header ausente → Missing API key.
  • Chave inválida ou inativa → Invalid API key.
• Cada chave possui um limite de requisições por minuto. Toda resposta inclui:
  • x-rate-limit-total — limite por minuto.
  • x-rate-limit-remaining — requisições restantes na janela atual.
  • x-rate-limit-reset — segundos restantes até a janela ser reiniciada (TTL).
  • Quando excedido, a API responde 429 com retry-after (segundos) e envelope de erro padrão.
• O header x-request-id é devolvido em todas as respostas. Inclua‑o em chamados de suporte para rastrearmos a requisição.

Exemplo de chamada autenticada:

curl -sS https://<API_BASE>/v1/data-sources \
  -H "x-api-key: $NEXUS_API_KEY"

Webhooks de ingestão (rotas /hooks/{slug})

As rotas de ingestão por webhook são públicas (não usam x-api-key). A autenticação é feita pelo header:

X-Webhook-Secret: <SECRET_GERADO_NA_CRIAÇÃO_DO_DATASOURCE>
Content-Type: application/json

O Nexus armazena apenas o hash do segredo. Toda comparação é feita em tempo constante. Apenas application/json é aceito; outros content types retornam 415.

Webhooks de saída (eventos enviados pelo Nexus)

Quando o Nexus envia eventos para a sua aplicação, ele assina o corpo com HMAC‑SHA‑256 usando o segredo registrado na criação do webhook (ver seção Webhooks de saída). Sua aplicação verifica a assinatura — não usa x-api-key.