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.

Getting your first key

There is no self-service API-key page in the dashboard yet — request your first key from support. After that you can mint and rotate your own with the endpoints below.

The API is also currently pilot-gated. Keys you mint inherit your key's pilot enrolment, so they work — but any key created outside the pilot returns 403 forbidden ("API is in pilot mode; key not enrolled") on every call.

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 of the caller as seen by the API — the original client IP, not an intermediate proxy address.
• Secrets are NEVER returned by GET.
• expires_at is always null — nothing sets it and keys do not auto-expire. Revoke them explicitly.
• Keys with status: "suspended" still appear in this listing; only revoked keys are hidden.
• key_id is always exactly 24 characters including the dzpk_live_ / dzpub_live_ prefix.

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		Default platform — omitting it mints a full-access platform key, so always send it explicitly. An out-of-set value returns 400
name	string ≤ 100		Free-form label. Defaults to default, and is hard-truncated at 100 characters with no error

Tier and pilot enrolment are inherited from the calling key. Scopes are NOT. Every key minted through POST /v1/keys receives the full default scope set for its type — platform keys get store:read/store:write, products:read/products:write, orders:read/orders:write, customers:read, landing_pages:read/landing_pages:write, webhooks:read/webhooks:write and usage:read; public keys get signups:write and events:write. A narrowly-scoped key can therefore mint a fully-scoped one: treat any platform key as equivalent to full store access, and contact support if you need a key issued with a reduced scope set.

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 200

Key creation returns HTTP 200, not 201 — check data.key_id rather than the status code.

{
  "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 ... — its format is {key_id}.{48-character hex secret}. 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:

• The key's status flips to revoked immediately and it disappears from GET /v1/keys.
• The revocation is recorded in your key audit history.
• Revocation can take up to ~60 s to propagate everywhere; until then the key may still succeed on some calls. If you need an immediate hard cut-off, contact support.

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.