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.

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": "pro_plus",
        "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 vue par la périphérie. Avec Cloudflare en frontal, c'est l'IP client originale, pas un IP de PoP CF.
• Les secrets ne sont JAMAIS retournés par GET.

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	✅
name	string ≤ 100		Libellé libre

Scopes et tier sont hérités de la clé appelante. Pour obtenir une clé avec scopes/tier différents, il faut une clé créée via le chemin admin (géré par le support).

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 201

{
  "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 .... 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 :

• api_v1_keys.status = 'revoked' est défini immédiatement à l'origine.
• Une ligne d'audit est ajoutée à api_v1_key_events.
• Le cache KV en périphérie expire en ~60 s ; jusque-là la clé peut continuer à fonctionner pour des opérations en cache. Si la révocation immédiate est critique, contactez le support pour purger l'entrée KV.

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.