Deux types de clés.
Clé de plateforme (serveur à serveur, CRUD complet)
Utilisez un Bearer token depuis votre back-end :
Authorization: Bearer <key_id>.<key_secret>
Le format est key_id.key_secret — les deux moitiés sont requises. key_id est l'identifiant de 24 caractères qui commence déjà par dzpk_live_ (par exemple dzpk_live_c741d949613f8f.<48-hex secret>) : ne rajoutez donc pas le préfixe. Le secret de la clé fait 48 caractères hexadécimaux et n'est affiché qu'une seule fois à la création, jamais ensuite.
Clé publique (sites et applications externes ; signée HMAC)
Pour comptabiliser les inscriptions d'utilisateurs finaux et les événements personnalisés depuis un site ou une application que vous exploitez en dehors de DZBuild. Votre back-end appelle POST /v1/signups / POST /v1/events et signe chaque requête — n'exposez jamais le secret de signature au navigateur.
En-têtes :
Authorization: DZ-Public <key_id> X-DZ-Timestamp: <unix_seconds> X-DZ-Nonce: <32-hex> X-DZ-Signature: hex(hmac_sha256(signing_secret, key_id + "\n" + nonce + "\n" + ts + "\n" + sha256(body)))
Ici aussi, key_id commence déjà par dzpub_live_ — transmettez-le exactement tel qu'il vous a été retourné. Le secret de signature fait 64 caractères hexadécimaux.
Le nonce est à usage unique par clé pendant une heure et empêche le rejeu. Le timestamp doit être dans les ±5 minutes.
⚠️ Attention — Une nouvelle clé publique reste inerte tant qu'elle n'est pas activée
Une clé type: public créée via POST /v1/keys renvoie 401 tant qu'elle n'a pas été activée pour le trafic API. Contactez le support juste après en avoir créé une pour la faire activer. Les clés de plateforme (Bearer) ne sont pas concernées — elles fonctionnent immédiatement.
Scopes
Chaque clé possède une liste de scopes. Scopes de plateforme par défaut : store:read, store:write, products:read, products:write, orders:read, orders:write, customers:read, landing_pages:read, landing_pages:write, webhooks:read, webhooks:write, usage:read.
Scopes publics par défaut : signups:write, events:write.
Les scopes sont aujourd'hui appliqués sur les endpoints d'écriture et les endpoints décomptés : products:write, orders:write, landing_pages:write, webhooks:write, ainsi que webhooks:read et usage:read. Les endpoints de lecture (boutique, produits, commandes, clients, landing pages) acceptent actuellement toute clé active et inscrite au pilote, quelle que soit sa liste de scopes. store:write, signups:write et events:write sont accordés par défaut mais aucun endpoint ne les consomme encore. Ne comptez pas sur l'omission d'un scope pour restreindre ce qu'une clé peut lire.
La gestion des clés (/v1/keys) est contrôlée par le type de clé, pas par les scopes : une clé publique qui l'appelle reçoit 403 — « Key management requires a platform key ».
Inscription au pilote
Tant que l'API est en pilote, une clé valide et correctement signée renvoie malgré tout 403 forbidden si elle n'est pas inscrite au pilote. Contactez le support avec votre identifiant de boutique pour l'inscrire.