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"
  }
}

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