Authentification
Chaque requête porte votre clé, un horodatage et une signature HMAC-SHA256 du corps.
Les trois en-têtes
| En-tête | Contenu |
|---|---|
x-api-key | Votre clé API. |
x-timestamp | L'heure d'envoi en millisecondes Unix (Date.now()). Elle doit être à moins de 5 minutes de l'heure du serveur : gardez l'horloge de vos machines synchronisée (NTP). |
x-signature | La signature HMAC-SHA256 de la requête, en hexadécimal minuscule. |
Calculer la signature
bodyHash = hex( SHA-256( corps ) )
signature = hex( HMAC-SHA256( clé = votre clé API, message = timestamp + "." + bodyHash ) )Le piège classique
Le serveur recalcule l'empreinte du JSON reçu, sérialisé compact (sans espaces ni retours à la ligne), en UTF-8, champs dans l'ordre où vous les envoyez. Sérialisez donc une seule fois, de cette façon, signez cette chaîne et envoyez-la telle quelle.
import crypto from 'node:crypto';
const body = JSON.stringify(payload); // une seule fois
const timestamp = Date.now().toString();
const bodyHash = crypto.createHash('sha256').update(body, 'utf8').digest('hex');
const signature = crypto
.createHmac('sha256', apiKey)
.update(`${timestamp}.${bodyHash}`)
.digest('hex');
// puis fetch(url, { method: 'POST', headers: { …, 'x-signature': signature }, body })Votre clé
- Elle appartient à l'organisation, pas à un utilisateur : une seule clé active à la fois, et en générer une nouvelle révoque la précédente.
- Elle expire 13 mois après sa création ; un e-mail vous prévient un mois avant.
- Vous pouvez restreindre son usage à des adresses IP ou des plages CIDR, dans l'Espace développeur. Par défaut, toutes les adresses sont acceptées.
- Elle circule dans chaque requête : traitez-la comme un mot de passe. Jamais dans un navigateur ni dans un dépôt de code ; révoquez-la au moindre doute.