# Authentication Two key types. ## Platform key (server-to-server, full CRUD) Use a Bearer token from your backend: ``` Authorization: Bearer . ``` 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_xxxxxxxxxxxxxx.<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 X-DZ-Timestamp: 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. 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`, `promos:read`, `promos:write`, `pixels:read`, `pixels:write`, `shipping:read`, `shipping:write`, `webhooks:read`, `webhooks:write`, `usage:read`, `analytics:read`, `whatsapp:read`, `whatsapp:send`. A key created in the dashboard gets exactly this list. `delivery:send` and `ai:generate` are not in it, so a key created in the dashboard or through `POST /v1/keys` gets `403` on `POST /v1/orders/{id}/send-to-delivery` and `POST /v1/landing-pages/generate`. Default public scopes: `signups:write`, `events:write`. Scopes are checked on reads as well as writes: a key without `orders:read` gets `403` with `Missing scope: orders:read` on `GET /v1/orders`. `store:write` covers the store settings, design, theme and home page writes. `signups:write` and `events:write` cover `POST /v1/signups` and `POST /v1/events`. 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". A platform key minted through `POST /v1/keys` gets only the scopes the calling key already holds (`403` when they share none). A `type: public` key always gets `signups:write` and `events:write`. ## Creating a key The owner of a store on an active Enterprise plan creates personal keys in the dashboard at **Settings → API** (`/dashboard/api`). A new key is enrolled in the pilot automatically and works at once: there is nothing to ask support for. The page shows two values, once, when the key is created: * **Bearer token**: the whole credential, already in the `key_id.key_secret` form. Send it as it is, `Authorization: Bearer `, without adding anything to it. * **Signing secret**: never goes in the `Authorization` header, and Bearer calls don't use it. Keep it private like the token. A store holds at most 3 active personal keys. Keys held by installed apps, Copilot or a connector don't take one of those slots. ## Assistant connections A connection made for Copilot or a connected AI assistant (Claude or ChatGPT) can cover several of the merchant's stores, with one key per store. Two endpoints let a key held by such a connection read which stores it covers and change which one is active. Any other key, including one created in the dashboard, gets `404 not_found` with `This key does not belong to an assistant connection.` ### `GET /v1/connection` Needs `store:read`. ``` curl https://api.dzbuild.app/v1/connection \ -H "Authorization: Bearer $DZ_KEY" ``` ``` { "data": { "connection_id": 100, "client_name": "Claude", "active_store_id": 10, "stores": [ { "id": 10, "name": "My store", "slug": "my-store" }, { "id": 20, "name": "My second store", "slug": "my-second-store" } ] }, "meta": { "request_id": "...", "api_version": "v1" } } ``` `client_name` is the name of the assistant app. A connection approved before connections could cover several stores lists its one store. ### `POST /v1/connection/active-store` Needs `store:write` and an `Idempotency-Key`. `store_id` in the body names the store to make active. ``` curl -X POST https://api.dzbuild.app/v1/connection/active-store \ -H "Authorization: Bearer $DZ_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: active-store-20" \ -d '{"store_id": 20}' ``` The answer is the connection after the move, in the same shape as `GET /v1/connection`. The active store is a pointer, not a permission: every request still acts on the one store its key belongs to. A store outside the connection answers `403 store_not_in_connection`, and a body without `store_id` answers `400 bad_request`.