Skip to main content

Get started

This page takes you from an empty developer console to a first authenticated API call. You register an app, install it on a store you own, exchange the code for an install token and call GET /v1/whoami.

Before you start​

  • A DZBuild account that owns at least one store. A test install only works on a store your account owns, not on a store where you are a team member.
  • A redirect URI on https that your app controls. The console refuses http. The quickest option is a Worker on workers.dev from /apps/new, registered once; an https tunnel to your machine also works, but its address changes on each run and the console holds at most 5 redirect URIs.
  • curl and openssl on your machine.

Start from the example app​

The fastest start is /apps/new: pick one of three Cloudflare presets, deploy it to a free workers.dev address and get the exact values for the console.

  • cloudflare-basic: the install flow, one token per store and the launch link. The base for your own app.
  • cloudflare-catalog: a products page for the merchant and a CSV export of the catalog.
  • cloudflare-orders: new-order alerts to Telegram by polling GET /v1/orders once a minute; order webhooks once you own a domain.

Scaffold the basic preset in one command, or deploy it from the browser with the button below. Cloudflare clones it into your GitHub account and deploys it; the preset README lists the steps that follow.

npm create cloudflare@latest my-app -- --template DZBuild-com/dzbuild-app-starter/cloudflare-basic --no-agents --no-git --no-deploy --no-open

Deploy to Cloudflare

If you host on your own server instead, the Node.js example in the same repository has the same flow with no dependencies and offline tests. Fill in the environment variables in .env.example from your console.

1. Register the app​

Open the developer console at https://dzbuild.com/dashboard/developer and choose New app (/dashboard/developer/apps/new). Fill in the form:

FieldWhat to enter
NameThe app name merchants see on the consent screen.
Developer nameYour name or your company's name, shown on the consent screen.
DescriptionsOne description each in English, Arabic and French.
HomepageYour app's website, https only. The Install button on the merchant's Extensions page opens this address, or the launch URL when it is empty, so it must lead to your install flow.
Support emailThe address merchants write to for help.
Launch URLThe https page that opens when a merchant clicks Open on your app.
Redirect URIsOne to five exact URIs. DZBuild sends the authorization code only to these.
ScopesThe permissions your app may request. See Scopes.
Minimum planThe lowest store plan that may use your app. Leave it on Free to allow every store.
Webhook URL and eventsOptional. See Webhooks.

Save the app. The console then shows three credentials:

CredentialFormatWhere it lives
client_iddzapp_ followed by 20 hex charactersPublic. It goes in the authorize URL.
Client secretdzas_ followed by 48 hex charactersShown once. Store it on your server. Generate a new one in the console if you lose it.
Signing secret64 hex charactersViewable in the console. It signs webhooks and launch tokens.

The new app is a draft. A draft runs only on stores your own account owns, which is what you need for testing.

2. Choose scopes​

Register only the scopes your app uses. On the consent screen, the merchant sees one line per resource you request. At install time you can ask for fewer scopes than you registered with the scope parameter, but never more. The full list is on the Scopes page.

3. Set your redirect URIs​

DZBuild compares the redirect_uri you send with your registered URIs as exact strings. A trailing slash, a different letter case or an extra query parameter makes it a different URI. A URI with a fragment (#) is refused when you save the app.

If the redirect_uri does not match, DZBuild shows an error page and does not redirect at all.

4. Install the app on your own store​

Create a PKCE verifier and its S256 challenge. The verifier stays on your server.

CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(printf %s "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)

Send your browser to the authorize URL. Encode each value; spaces between scopes become %20.

GET https://dzbuild.com/oauth/apps/authorize?response_type=code&client_id=dzapp_0123456789abcdef0123&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=store%3Aread%20orders%3Aread&state=STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

Log in to DZBuild if asked. The consent screen lists your stores and marks the ones that cannot install the app. Pick a store and approve. DZBuild redirects to your URI:

HTTP/1.1 302 Found
Location: https://app.example.com/callback?code=CODE&state=STATE

Check that state is the value you sent. The code is valid for 10 minutes and works once.

Exchange the code for an install token. Send the form from your server, never from a browser.

curl -s https://dzbuild.com/oauth/apps/token \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  --data-urlencode redirect_uri=https://app.example.com/callback \
  -d code_verifier="$CODE_VERIFIER" \
  -d client_id="$DZ_CLIENT_ID" \
  -d client_secret="$DZ_CLIENT_SECRET"

A successful answer looks like this:

{
  "access_token": "dzpk_live_0a1b2c3d4e5f67.9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928",
  "token_type": "Bearer",
  "scope": "store:read orders:read",
  "store_id": 141,
  "install_id": 7,
  "stores": [
    {
      "store_id": 141,
      "store_name": "My test store",
      "install_id": 7,
      "access_token": "dzpk_live_0a1b2c3d4e5f67.9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928"
    }
  ]
}

Save each access_token with its store_id and install_id. There is no expires_in and no refresh token: the token works until the merchant uninstalls your app. The OAuth page lists every error this call can return.

5. Make your first call​

Call GET /v1/whoami with the install token. It needs no scope, so it works for every install.

curl -s https://api.dzbuild.app/v1/whoami \
  -H "Authorization: Bearer $DZ_TOKEN"
{
  "data": {
    "key_id": "dzpk_live_0a1b2c3d4e5f67",
    "store_id": 141,
    "type": "platform",
    "rate_limit_tier": "enterprise",
    "pilot": true,
    "scopes": ["store:read", "orders:read"],
    "app": {
      "app_id": 3,
      "client_id": "dzapp_0123456789abcdef0123",
      "install_id": 7
    }
  },
  "meta": {
    "request_id": "5f2c9a0b1d3e4f60",
    "api_version": "v1"
  }
}

6. Read the app object​

The app object appears only when the token belongs to an app install. It tells your server which app and which install made the call.

FieldMeaning
app_idYour app's numeric id on DZBuild.
client_idYour app's public client id. Compare it with your own to reject tokens issued to another app.
install_idThe install this token belongs to. It stays the same if the merchant uninstalls and installs your app again on the same store.

rate_limit_tier is enterprise for every install token, whatever plan the store is on. Your real budget is the per-install limit described in Core concepts.

Next steps​

This page for AI toolsView as MarkdownOpen in ChatGPTOpen in Claude