Authentification API : clé API et signature HMAC

Comment fonctionne la signature

La signature atteste que la requête a été formulée par quelqu’un qui connaît le secret, sans le transporter sur le réseau. Le serveur recalcule la même empreinte et la compare à X-SIGNATURE.

HMAC_SHA256(method|path|timestamp|body, apiSecret)

Chaque partie est prise exactement comme suit :

• method — méthode HTTP telle qu’envoyée, en majuscules (GET, POST, etc.).
• path — chemin seul, sans schéma ni domaine ni query string (ex. /api/v1/public/util/ping).
• timestamp — la même valeur que X-TIMESTAMP, en ISO 8601 (décalage ou Z selon votre implémentation ; elle doit rester cohérente avec l’en-tête).
• body — pour un POST/PATCH/PUT avec JSON, la chaîne brute du corps ; pour un GET (ou sans corps), une chaîne vide. Les séparateurs | entre les segments font partie de la convention.

Le secret (apiSecret) est celui associé à votre clé API. La sortie attendue pour X-SIGNATURE est en général l’empreinte HMAC-SHA256 exprimée en hexadécimal (aligné sur la documentation de votre espace client).

Points qui bloquent souvent au premier essai : inclure le domaine dans le path signé, réécrire ou reformater le JSON après calcul de signature, ou utiliser un timestamp différent de celui de l’en-tête.

Exemple avec body JSON : POST SMS

POST /api/v1/public/sms/send — le corps JSON doit être strictement identique entre : (1) la chaîne utilisée pour signer, (2) le corps réellement envoyé sur le réseau. Un espace en plus, un champ re-ordonné, ou une normalisation Unicode différente peut invalider la signature.

{"recipient":"+99905550001","content":"Hello sandbox"}

POST|/api/v1/public/sms/send|2025-11-02T17:00:00.000Z|{"recipient":"+99905550001","content":"Hello sandbox"}

En pratique : sérialisez votre objet JSON une seule fois, conservez la chaîne résultante, calculez la signature sur cette chaîne, puis envoyez exactement cette chaîne dans le corps HTTP. Ne recalculez pas un JSON « équivalent » après coup.

curl -sS -X POST "https://api.novixo.fr/api/v1/public/sms/send" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-TIMESTAMP: YOUR_TIMESTAMP" \
  -H "X-SIGNATURE: YOUR_SIGNATURE" \
  -d '{"recipient":"+99905550001","content":"Hello sandbox"}'

Scénario sanctionné par l’API : calculer la signature sur une jolie version indentée du JSON, puis envoyer une version compacte (ou l’inverse). Les deux chaînes doivent être les mêmes octets.

Bonnes pratiques d’implémentation

• Calculez la signature uniquement côté serveur (ou environnement équivalent : worker, microservice backend).
• Ne jamais embarquer le secret API dans une application mobile ou un bundle front.
• Centralisez la construction de la canonique et du HMAC dans un module unique (helper interne, petite lib partagée par vos services).
• En cas d’échec d’auth, journalisez la méthode, le path, un hash ou tronquat du body et le code retour — pas le secret.
• Commencez par un endpoint simple (/util/ping) avant d’enchaîner sur l’envoi SMS.