Autenticação (API Key)

Toda a API de integração é autenticada por API Key, enviada no header X-Api-Key.

Nota

As API Keys e os endpoints de webhook são criados/gerenciados no painel (autenticado por JWT) — essas telas ficam fora do escopo deste documento, que cobre apenas a integração por API Key.

Enviada no header X-Api-Key com o valor cru da chave (sem prefixo Bearer).

Formato da chave: {prefix}.{type}.{secret} Exemplo: ab12cd34.public.<48-chars-secret>

• prefix — 8 caracteres aleatórios (base64url). Usado para lookup.
• type — public ou secret (lowercase).
• secret — 48 caracteres aleatórios.

Como o servidor valida (guard ApiKeyGuard):

1. Extrai os primeiros 8 caracteres como key_prefix e busca as chaves não revogadas com esse prefixo.
2. bcrypt.compare da chave completa contra o key_hash armazenado (o segredo cru nunca é persistido).
3. Verifica expiração (expires_at), tipo exigido pela rota, status da empresa e scopes.
4. Em caso de sucesso, anexa a empresa e a chave ao request.

Requisição autenticada

curl -X POST https://goldpay-goldpay-api.f0czp0.easypanel.host/api/payments/merchant/transaction/pix \
  -H "X-Api-Key: ab12cd34.public.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Erros de autenticação:

Status	Situação
401	Header ausente (Missing API key), chave inválida (Invalid API key), chave expirada (API key expired), tipo errado (API key type must be {TYPE})
403	Empresa BLOCKED ou INACTIVE; scope ausente (API key missing required scope)
400	Falha de validação Zod do body/params