Authentification par hash (HMAC)

Certains endpoints de l'API Enkore sont protégés par une authentification de type HMAC-SHA512. Ce mécanisme permet d'identifier un client sans session ni cookie, uniquement à partir de paramètres passés en query string.

---

Paramètres requis

Chaque requête authentifiée doit inclure les trois paramètres suivants en query string :

Paramètre	Description
domain	Domaine du store (ex : monstore.com)
externalId	Identifiant du client dans la plateforme e-commerce
hash	HMAC-SHA512 calculé à partir de externalId

Exemple :

GET /point/user-history/42?domain=monstore.com&externalId=42&hash=<hmac>

---

Calcul du hash

Le hash est calculé avec l'algorithme HMAC-SHA512 selon la formule suivante :

clé = <reference_du_store> + ":" + <api_key>
hash = HMAC-SHA512(clé, externalId)

Élément	Description
reference_du_store	Référence interne du store (fournie par Enkore)
api_key	Clé API active du store (à récupérer dans le back-office d'Enkore)
externalId	Identifiant du client dans la boutique, utilisé comme message à signer

Exemple en JavaScript :

import { createHmac } from 'node:crypto';

const reference = 'monstore'; // référence du store fournie par Enkore
const apiKey = 'abc123...';   // clé API du store
const externalId = '42';      // ID du client dans la plateforme e-commerce

const key = `${reference}:${apiKey}`;
const hash = createHmac('sha512', key).update(externalId).digest('hex');

Exemple en PHP (PrestaShop / WooCommerce) :

$reference  = 'monstore';
$apiKey     = 'abc123...';
$externalId = '42';

$key  = $reference . ':' . $apiKey;
$hash = hash_hmac('sha512', $externalId, $key);

---

Endpoints concernés

Tous les endpoints des widgets qui opèrent au nom d'un client utilisent cette authentification :

• GET /point/user-history/{externalId}?domain=...&hash=...
• POST /reward/claim/{externalId}?domain=...&hash=...
• POST /point/referral?domain=...&hash=...&externalId=...

Les endpoints publics (widget, liste des récompenses) n'ont besoin que du paramètre domain et n'utilisent pas le hash.

---

Sécurité

• La reference et la clé d'api ne sont jamais exposées au navigateur : le hash doit être calculé côté serveur (dans le module PrestaShop, WooCommerce, ou l'intégration custom) et peu éventuellement être injecté dans la page HTML lors du rendu.
• Un store peut avoir plusieurs clés API actives simultanément (rotation de clé sans interruption de service).