Authentification

L'API externe d'Owem Pay utilise un modele de securite a trois couches : API Key + Secret, signature HMAC-SHA512 par requete et liste blanche d'IP obligatoire.

Vue d'Ensemble des Couches

Requete HTTP
  |
  +- 1. Liste blanche d'IP --- IP non autorise ? -> 403 Forbidden
  |
  +- 2. API Key + Secret --- Identifiants invalides ? -> 401 Unauthorized
  |
  +- 3. HMAC-SHA512 --- Signature invalide ? -> 401 Unauthorized
       |
       +- Requete acceptee -> Logique metier

Couche 1 -- API Key + Secret

Toutes les requetes doivent inclure l'en-tete Authorization :

Authorization: ApiKey {client_id}:{client_secret}

Composant	Description	Prefixe
client_id	Identifiant public de l'API Key	cli_
client_secret	Cle secrete (nous ne stockons que le hash)	sk_

Le secret n'est jamais stocke en clair. Lorsqu'une requete arrive, le secret envoye est compare au hash stocke. S'il ne correspond pas, la requete est rejetee avant d'atteindre la logique metier.

Format alternatif -- Basic Auth avec base64 :

Authorization: Basic {base64(client_id:client_secret)}

Couche 2 -- HMAC-SHA512

Les requetes transactionnelles (POST, PUT, PATCH) exigent une signature HMAC-SHA512 du body dans l'en-tete hmac. La validation utilise une comparaison en temps constant (constant-time comparison) pour empecher les attaques par timing.

Consultez HMAC-SHA512 pour des exemples d'implementation dans 6 langages.

Couche 3 -- Liste Blanche d'IP

Chaque API Key doit avoir au moins un IP dans la liste blanche. Les requetes provenant d'IPs non autorisees sont rejetees avec 403 Forbidden, meme avec des identifiants valides. Configurez la liste blanche dans le Merchant Portal lors de la creation ou de la modification de l'API Key.

Supporte les IPs individuels et la notation CIDR (ex : 172.20.16.0/20).

En-tetes Obligatoires

En-tete	Valeur	Obligatoire
Authorization	ApiKey {client_id}:{client_secret}	Oui -- toutes les requetes
Content-Type	application/json	Oui -- requetes avec body
hmac	Signature HMAC-SHA512 en hexadecimal	Oui -- uniquement POST/PUT/PATCH
Idempotency-Key	Cle unique pour la deduplication (max 256 chars)	Optionnel -- uniquement POST

Exemple Complet

CLIENT_ID="cli_a1b2c3d4e5f6"
CLIENT_SECRET="sk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01"

# Consultation du solde (GET -- sans HMAC)
curl -X GET https://api.owem.com.br/api/external/balance \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

# PIX Cash-Out (POST -- avec 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"

Protections Supplementaires

Protection	Description
Rate Limiting	60 000 req/min par IP (authentifie). 5 req/min (non authentifie)
Cloud Armor (WAF)	Pare-feu applicatif protegeant le cluster
HTTPS + TLS 1.2+	Chiffrement obligatoire sur toutes les connexions
HSTS	Navigateurs forces a utiliser HTTPS

Pourquoi HMAC-SHA512 et non mTLS ?

Le mTLS (mutual TLS) authentifie la connexion, pas le contenu. Si la connexion est authentifiee, toutes les requetes passent sans validation individuelle.

Le HMAC valide chaque requete separement. Meme au sein d'une connexion valide, toute modification du payload fait rejeter la requete.

Aspect	mTLS	HMAC-SHA512
Valide	Canal TLS	Payload de la requete
Gestion	Certificats X.509 (emission, rotation, revocation, CRL/OCSP)	Genere la paire, met a jour, invalide
Risque operationnel	Certificats expires -- cause frequente d'incidents	La cle est une simple chaine de caracteres
Integrite du contenu	Non	Oui

Le TLS garantit deja le chiffrement du transport. Le HMAC ajoute l'integrite et l'authenticite du payload -- ce que le mTLS seul ne couvre pas.

Reponses d'Erreur

401 -- Identifiants Absents

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

403 -- IP non Autorise

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

429 -- Rate Limit Depasse

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

Securite

• N'exposez jamais le client_secret dans du code frontend ou des depots publics
• Utilisez des variables d'environnement sur votre serveur
• L'API Key est permanente -- elle n'expire pas, mais peut etre revoquee dans le Merchant Portal
• Configurez les IPs autorises dans la liste blanche