Keys (your own keys)

Manage the API keys for your store. All key operations require a platform key (a public key cannot mint other keys — by design).

Heads up: A key minted via the API is active immediately. There's no email confirmation, no admin approval. If you mint a key with broad scopes and leak it, the leaker can act with that key's full scope until you DELETE it. Keep secrets out of repos and shared screens.

GET /v1/keys

List the keys belonging to your store (excludes revoked keys; revoked keys are kept in audit history but hidden from this listing).

Auth: platform key.

Response 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 is updated on every authenticated call (best-effort write — may lag a few seconds).
• last_used_ip is the source IP as seen by the edge. With Cloudflare in front, this is the original client IP, not a CF POP IP.
• Secrets are NEVER returned by GET.

POST /v1/keys — mint

Create a new key. The secret is returned exactly once — save it immediately.

Auth: platform key. Requires Idempotency-Key.

Body

Field	Type	Required	Notes
type	platform | public	✅
name	string ≤ 100		Free-form label

Scope and tier are inherited from the calling key. To get a key with different scopes/tier, you'll need a key created via the admin path (handled by your support team).

Request

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" }'

Response 201

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

For a platform key, bearer_token is what you put in Authorization: Bearer .... For a public key, bearer_token is null and you use signing_secret to compute HMAC signatures (see Authentication).

DELETE /v1/keys/{key_id} — revoke

Auth: platform key. Requires Idempotency-Key.

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

Response:

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

What happens:

• api_v1_keys.status = 'revoked' is set immediately on origin.
• An audit row is appended to api_v1_key_events.
• The Cloudflare edge KV cache will expire within ~60 s; until then the key may continue to work for cached operations. If immediate hard-revoke is critical, contact support to flush the KV entry.

Best practices

• One key per environment — a staging key and a production key. Don't share.
• One key per integration — a key for Zapier, a key for your CRM sync, a key for your analytics pipeline. Easier to revoke a single integration without breaking others.
• Rotate periodically — every 90 days for production keys is a sensible cadence.
• Audit last_used_at — keys that haven't been used in 30+ days are candidates for revocation.
• Never email a secret — paste it once into your secrets store and never again.