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 :

Exemple :

GET /point/user-history/42?domain=https://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)

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.

Ce que le hash prouve, et ce qu'il ne prouve pas​

Un hash valide établit une seule chose : l'appelant détient une clé d'API active de la boutique servant ce domaine, et a signé cet externalId avec.

Il n'établit pas que l'externalId désigne un client connu d'Enkore. Enkore ne crée une fiche client qu'en voyant une commande (ou lors de l'import historique) : un compte ouvert sur la boutique mais qui n'a jamais commandé est parfaitement légitime, et parfaitement inconnu.

Un 401 signifie donc « signature invalide », jamais « client inconnu ». Chaque endpoint dit lui-même ce qu'il fait d'une référence inconnue :

Un client qui traite ces trois cas comme une session expirée invite l'utilisateur à se reconnecter, ce qui ne change rien : il faut lire le type du refus.

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).
• C'est la signature qui désigne la boutique, le domain ne fait que borner la recherche : la boutique retenue est celle dont une clé vérifie le hash.