Two key types.
Platform key (server-to-server, full CRUD)
Use a Bearer token from your backend:
Authorization: Bearer <key_id>.<key_secret>
The format is key_id.key_secret — both halves are required. key_id is the 24-character identifier that already begins with dzpk_live_ (for example dzpk_live_c741d949613f8f.<48-hex secret>), so don't add the prefix again. The key secret is 48 hex characters and is shown once at creation, never again.
Public key (external sites & apps; HMAC-signed)
For counting end-user signups and custom events from a site or app you run outside DZBuild. Your backend calls POST /v1/signups / POST /v1/events and signs each request — never expose the signing secret to a browser.
Headers:
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)))
Here too, key_id already begins with dzpub_live_ — pass it exactly as returned. The signing secret is 64 hex characters.
The nonce is single-use per key for one hour and prevents replay. The timestamp must be within ±5 minutes.
⚠️ Warning — A new public key is inert until it is activated
A type: public key you create through POST /v1/keys returns 401 until it has been activated for API traffic. Contact support right after creating one to have it activated. Platform (Bearer) keys are not affected — they work immediately.
Scopes
Every key has a list of scopes. Default platform scopes: 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.
Default public scopes: signups:write, events:write.
Scopes are enforced today on the write and metered endpoints: products:write, orders:write, landing_pages:write, webhooks:write, plus webhooks:read and usage:read. The read endpoints (store, products, orders, customers, landing-pages) currently accept any active, pilot-enrolled key regardless of its scope list. store:write, signups:write and events:write are granted by default but no endpoint consumes them yet. Don't rely on omitting a scope to restrict what a key can read.
Key management (/v1/keys) is gated by key type, not by scope: a public key calling it gets 403 — "Key management requires a platform key".
Pilot enrollment
While the API is in pilot, a valid, correctly-signed key still returns 403 forbidden unless that key is pilot-enrolled. Contact support with your store id to get enrolled.