Autenticacao

A API externa da Owem Pay utiliza um modelo de seguranca em tres camadas: API Key + Secret, assinatura HMAC-SHA512 por requisicao e whitelist de IP obrigatoria.

Visao Geral das Camadas

Requisicao HTTP
  │
  ├─ 1. IP Whitelist ─── IP nao autorizado? → 403 Forbidden
  │
  ├─ 2. API Key + Secret ─── Credenciais invalidas? → 401 Unauthorized
  │
  └─ 3. HMAC-SHA512 ─── Assinatura invalida? → 401 Unauthorized
       │
       └─ Requisicao aceita → Logica de negocio

Camada 1 -- API Key + Secret

Todas as requisicoes devem incluir o header Authorization:

Authorization: ApiKey {client_id}:{client_secret}

Componente	Descricao	Prefixo
client_id	Identificador publico da API Key	cli_
client_secret	Chave secreta (armazenamos apenas o hash)	sk_

O secret nunca e armazenado em texto puro. Quando uma requisicao chega, o secret enviado e comparado com o hash armazenado. Se nao corresponder, a requisicao e rejeitada antes de chegar a logica de negocio.

Formato alternativo -- Basic Auth com base64:

Authorization: Basic {base64(client_id:client_secret)}

Camada 2 -- HMAC-SHA512

Requisicoes transacionais (POST, PUT, PATCH) exigem assinatura HMAC-SHA512 do body no header hmac. A validacao usa comparacao em tempo constante (constant-time comparison) para impedir ataques de timing.

Veja HMAC-SHA512 para exemplos de implementacao em 6 linguagens.

Camada 3 -- IP Whitelist

Toda API Key deve ter pelo menos um IP na whitelist. Requisicoes de IPs nao autorizados sao rejeitadas com 403 Forbidden, mesmo com credenciais validas. Configure a whitelist no Merchant Portal ao criar ou editar a API Key.

Suporta IPs individuais e notacao CIDR (ex: 172.20.16.0/20).

Headers Obrigatorios

Header	Valor	Obrigatorio
Authorization	ApiKey {client_id}:{client_secret}	Sim -- todas as requisicoes
Content-Type	application/json	Sim -- requisicoes com body
hmac	Assinatura HMAC-SHA512 em hexadecimal	Sim -- apenas POST/PUT/PATCH
Idempotency-Key	Chave unica para deduplicacao (max 256 chars)	Opcional -- apenas POST

Exemplo Completo

CLIENT_ID="cli_a1b2c3d4e5f6"
CLIENT_SECRET="sk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01"

# Consulta de saldo (GET -- sem HMAC)
curl -X GET https://api.owem.com.br/api/external/balance \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

# PIX Cash-Out (POST -- com HMAC + Idempotency-Key)
BODY='{"amount":3000,"pix_key":"12345678901","pix_key_type":"cpf","description":"Pagamento"}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/external/pix/cash-out \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -H "Idempotency-Key: cashout-order-9876" \
  -d "$BODY"

Protecoes Adicionais

Protecao	Descricao
Rate Limiting	60.000 req/min por IP (autenticado). 5 req/min (sem autenticacao)
Cloud Armor (WAF)	Firewall de aplicacao protegendo o cluster
HTTPS + TLS 1.2+	Criptografia obrigatoria em todas as conexoes
HSTS	Navegadores forcados a usar HTTPS

Por que HMAC-SHA512 e nao mTLS?

O mTLS (mutual TLS) autentica a conexao, nao o conteudo. Se a conexao esta autenticada, todas as requisicoes passam sem validacao individual.

O HMAC valida cada requisicao separadamente. Mesmo dentro de uma conexao valida, qualquer alteracao no payload faz a requisicao ser rejeitada.

Aspecto	mTLS	HMAC-SHA512
Valida	Canal TLS	Payload da requisicao
Gestao	Certificados X.509 (emissao, rotacao, revogacao, CRL/OCSP)	Gera par, atualiza, invalida
Risco operacional	Certificados expirados -- causa frequente de incidentes	Chave e string simples
Integridade do conteudo	Nao	Sim

O TLS ja garante criptografia do transporte. O HMAC adiciona integridade e autenticidade do payload -- algo que o mTLS por si so nao cobre.

Respostas de Erro

401 -- Credenciais Ausentes

{
  "error": {
    "status": 401,
    "message": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

403 -- IP nao Autorizado

{
  "error": {
    "status": 403,
    "message": "Request IP not in API key whitelist"
  }
}

429 -- Rate Limit Excedido

{
  "error": {
    "status": 429,
    "message": "Too Many Requests"
  }
}

Permissoes (Permissions)

Cada API Key possui uma lista de permissoes que determinam quais endpoints podem ser acessados. Se a API Key nao possuir a permissao necessaria, a requisicao e rejeitada com 403 Forbidden.

Permissoes Disponiveis

Permissao	Descricao
pix:write	Gerar QR Code (Cash-In)
pix:read	Listar chaves PIX
transfer:write	Enviar PIX (Cash-Out), aprovar Cash-Out
transfer:read	Consultar transacoes (por ID, E2E, Tag, External ID), comprovante, listar transacoes
payment:write	Solicitar devolucao (refund)
payment:read	Listar e consultar MED
account:write	Criar e remover webhooks
account:read	Consultar saldo, listar webhooks, validar CPF
statement:read	Consultar extrato

Permissoes por Endpoint

Endpoint	Metodo	Permissao
/pix/cash-in	POST	pix:write
/pix/cash-out	POST	transfer:write
/pix/cash-out/approve	POST	transfer:write
/pix/refund	POST	payment:write
/cpf/validate	POST	account:read
/webhooks	POST	account:write
/webhooks	GET	account:read
/webhooks/:id	DELETE	account:write
/balance	GET	account:read
/transactions	GET	transfer:read
/transactions/:id	GET	transfer:read
/transactions/e2e/:e2e_id	GET	transfer:read
/transactions/tag/:tag	GET	transfer:read
/transactions/ref/:external_id	GET	transfer:read
/transactions/:id/receipt	GET	transfer:read
/pix/keys	GET	pix:read
/med	GET	payment:read
/med/:id	GET	payment:read
/statement	GET	statement:read

Resposta de Erro -- 403 (Permissao Insuficiente)

{
  "error": "forbidden",
  "message": "API key lacks permission: transfer:write"
}

As permissoes sao configuradas na criacao da API Key pelo Merchant Portal ou pela API de administracao.

Seguranca

• Nunca exponha o client_secret em codigo frontend ou repositorios publicos
• Utilize variaveis de ambiente no seu servidor
• A API Key e permanente -- nao expira, mas pode ser revogada no Merchant Portal
• Configure IPs permitidos na whitelist