Clés (vos propres clés)

Gérez les clés API de votre boutique. Toutes les opérations sur les clés nécessitent une clé plateforme (une clé publique ne peut pas créer d'autres clés — par conception).

Attention : une clé créée via l'API est active immédiatement. Pas de confirmation par email, pas d'approbation admin. Si vous créez une clé avec des scopes larges et la fuiez, le destinataire peut agir avec ses pleins droits jusqu'à ce que vous fassiez DELETE. Gardez les secrets hors des repos et des écrans partagés.

Obtenir votre première clé

L'API est réservée au plan Enterprise : les clés ne peuvent être émises que pour des boutiques disposant d'un plan Enterprise actif, et la création échoue pour tout autre plan. Générez votre première clé depuis le tableau de bord marchand : Paramètres → API (/dashboard/api) — accessible au propriétaire de la boutique ; le secret n'est affiché qu'une seule fois, à la création. Vous pouvez aussi créer et faire tourner vos clés avec les endpoints ci-dessous. Une boutique peut détenir au plus 3 clés actives (tous canaux de création confondus) ; révoquez-en une pour libérer une place.

L'API est aussi actuellement restreinte à un pilote. Les clés que vous créez héritent de l'enrôlement pilote de votre clé, elles fonctionnent donc — mais toute clé créée hors pilote renvoie 403 forbidden (« API is in pilot mode; key not enrolled ») à chaque appel.

GET /v1/keys

Liste les clés de votre boutique (exclut les clés révoquées ; elles sont conservées dans l'historique d'audit mais cachées de cette liste).

Auth : clé plateforme.

Réponse 200

{
  "data": {
    "items": [
      {
        "key_id":          "dzpk_live_c741d949613f8f",
        "type":            "platform",
        "name":            "production-server-1",
        "scopes":          ["store:read", "products:read", "orders:read", "orders:write"],
        "rate_limit_tier": "enterprise",
        "pilot":           true,
        "status":          "active",
        "last_used_at":    "2026-04-30 19:35:49",
        "last_used_ip":    "203.0.113.42",
        "created_at":      "2026-04-30 19:27:55",
        "expires_at":      null
      }
    ]
  }
}

Notes :

• last_used_at est mis à jour à chaque appel authentifié (écriture best-effort — peut traîner de quelques secondes).
• last_used_ip est l'IP source de l'appelant telle que vue par l'API — l'IP client originale, pas celle d'un proxy intermédiaire.
• Les secrets ne sont JAMAIS retournés par GET.
• expires_at vaut toujours null — rien ne le définit et les clés n'expirent pas d'elles-mêmes. Révoquez-les explicitement.
• Les clés en status: "suspended" apparaissent toujours dans cette liste ; seules les clés révoquées sont masquées.
• key_id fait toujours exactement 24 caractères, préfixe dzpk_live_ / dzpub_live_ compris.

POST /v1/keys — créer

Crée une nouvelle clé. Le secret est retourné une seule fois — sauvegardez-le immédiatement.

Auth : clé plateforme. Nécessite Idempotency-Key.

Corps

Champ	Type	Requis	Notes
type	platform | public		Défaut platform — l'omettre crée une clé plateforme à accès complet, envoyez-le donc toujours explicitement. Une valeur hors ensemble renvoie 400
name	string ≤ 100		Libellé libre. Défaut default, tronqué durement à 100 caractères sans erreur

Le tier et l'enrôlement pilote sont hérités de la clé appelante. Les scopes, NON. Toute clé créée via POST /v1/keys reçoit l'ensemble de scopes par défaut complet de son type — les clés plateforme obtiennent store:read/store:write, products:read/products:write, orders:read/orders:write, customers:read, landing_pages:read/landing_pages:write, webhooks:read/webhooks:write et usage:read ; les clés publiques obtiennent signups:write et events:write. Une clé à scopes réduits peut donc en créer une à scopes complets : considérez toute clé plateforme comme équivalente à un accès total à la boutique, et contactez le support si vous avez besoin d'une clé émise avec un jeu de scopes réduit.

Requête

curl -X POST 'https://api.dzbuild.app/v1/keys' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "type": "platform", "name": "ci-deploy-key" }'

Réponse 200

La création d'une clé renvoie HTTP 200, pas 201 — vérifiez data.key_id plutôt que le code de statut.

{
  "data": {
    "key_id":         "dzpk_live_a3f9...",
    "bearer_token":   "dzpk_live_a3f9..........73ad…",
    "signing_secret": "185c4b5216c9d3f713a4ac7842d4664b75fa287b4aa4105cc27f933d7385a740",
    "note":           "Save these now — secrets are not retrievable."
  }
}

Pour une clé plateforme, bearer_token est ce que vous mettez dans Authorization: Bearer ... — son format est {key_id}.{secret hex de 48 caractères}. Pour une clé publique, bearer_token vaut null et vous utilisez signing_secret pour calculer les signatures HMAC (voir Authentification).

DELETE /v1/keys/{key_id} — révoquer

Auth : clé plateforme. Nécessite Idempotency-Key.

curl -X DELETE 'https://api.dzbuild.app/v1/keys/dzpk_live_a3f9...' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Idempotency-Key: revoke-a3f9"

Réponse :

{ "data": { "revoked": true, "key_id": "dzpk_live_a3f9..." } }

Ce qui se passe :

• Le statut de la clé passe immédiatement à revoked et elle disparaît de GET /v1/keys.
• La révocation est enregistrée dans l'historique d'audit de vos clés.
• La révocation peut mettre jusqu'à ~60 s à se propager partout ; jusque-là, la clé peut encore réussir sur certains appels. S'il vous faut une coupure immédiate, contactez le support.

Bonnes pratiques

• Une clé par environnement — une clé staging et une clé production. Ne pas partager.
• Une clé par intégration — une pour Zapier, une pour la sync CRM, une pour l'analytics. Plus facile de révoquer une intégration sans casser les autres.
• Faites tourner périodiquement — tous les 90 jours pour les clés de production est une cadence raisonnable.
• Auditez last_used_at — les clés non utilisées depuis 30+ jours sont candidates à la révocation.
• N'envoyez jamais un secret par email — collez-le une fois dans votre gestionnaire de secrets et plus jamais.