# 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[​](#before-you-start "Direct link to 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](https://dzbuild.dev/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[​](#start-from-the-example-app "Direct link to Start from the example app") The fastest start is [/apps/new](https://dzbuild.dev/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](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTg0IiBoZWlnaHQ9IjM5IiB2aWV3Qm94PSIwIDAgMTg0IDM5IiBmaWxsPSJub25lIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogIDxwYXRoCiAgICBkPSJNMSA0QzEgMi4zNDMxNSAyLjM0MzE1IDEgNCAxSDE4MEMxODEuNjU3IDEgMTgzIDIuMzQzMTUgMTgzIDRWMzVDMTgzIDM2LjY1NjkgMTgxLjY1NyAzOCAxODAgMzhINEMyLjM0MzE0IDM4IDEgMzYuNjU2OSAxIDM1VjRaIgogICAgZmlsbD0iYmxhY2siIC8+CiAgPHBhdGgKICAgIGQ9Ik0xIDRDMSAyLjM0MzE1IDIuMzQzMTUgMSA0IDFIMTgwQzE4MS42NTcgMSAxODMgMi4zNDMxNSAxODMgNFYzNUMxODMgMzYuNjU2OSAxODEuNjU3IDM4IDE4MCAzOEg0QzIuMzQzMTQgMzggMSAzNi42NTY5IDEgMzVWNFoiCiAgICBzdHJva2U9IiNGNjgyMUYiIHN0cm9rZS13aWR0aD0iMiIgLz4KICA8cGF0aAogICAgZD0iTTI4Ljg4NjggMjQuNzc0NUwyOS4wMDk1IDI0LjM1QzI5LjE1NTggMjMuODQ0OSAyOS4xMDE0IDIzLjM3OCAyOC44NTU5IDIzLjAzNDlDMjguNjMwMiAyMi43MTg5IDI4LjI1MzkgMjIuNTMyOCAyNy43OTcgMjIuNTExMkwxOS4xNDE2IDIyLjQwMDlDMTkuMDgzMyAyMi4zOTc4IDE5LjAzNTEgMjIuMzcxNSAxOS4wMDU0IDIyLjMyODNDMTguOTc1MyAyMi4yODM5IDE4Ljk2ODMgMjIuMjI2OCAxOC45ODY5IDIyLjE3MkMxOS4wMTU0IDIyLjA4NjcgMTkuMDk5OSAyMi4wMjIzIDE5LjE4NzkgMjIuMDE4NEwyNy45MjM2IDIxLjkwNzdDMjguOTU5NyAyMS44NjAyIDMwLjA4MTYgMjEuMDE5NCAzMC40NzQ1IDE5Ljk5NEwzMC45NzI3IDE4LjY5MjRDMzAuOTg2NCAxOC42NTcgMzAuOTkyNiAxOC42MTk0IDMwLjk5MjMgMTguNTgxN0MzMC45OTIyIDE4LjU2MTIgMzAuOTkwNyAxOC41NDA2IDMwLjk4NjIgMTguNTIwM0MzMC40MjAxIDE1Ljk3NjEgMjguMTQ5NyAxNC4wNzM2IDI1LjQzNDggMTQuMDczNkMyMi45MzMzIDE0LjA3MzYgMjAuODA5MiAxNS42ODgyIDIwLjA0NzQgMTcuOTMyMkMxOS41NTU3IDE3LjU2MzMgMTguOTI2NyAxNy4zNjcyIDE4LjI1MDYgMTcuNDM0OEMxNy4wNTA0IDE3LjU1NCAxNi4wODYgMTguNTIwMyAxNS45NjY3IDE5LjcyMDRDMTUuOTM1NCAyMC4wMzE5IDE1Ljk2MDkgMjAuMzMyNSAxNi4wMzI3IDIwLjYxNUMxNC4wNzIyIDIwLjY3MjEgMTIuNSAyMi4yNzgyIDEyLjUgMjQuMjUyNEMxMi41IDI0LjQzMTEgMTIuNTEzNSAyNC42MDY3IDEyLjUzODYgMjQuNzc4NEMxMi41NTA5IDI0Ljg2MTggMTIuNjIxMiAyNC45MjQzIDEyLjcwNTMgMjQuOTI0M0wyOC42ODQ2IDI0LjkyNjJDMjguNjg2MiAyNC45MjYyIDI4LjY4NzYgMjQuOTI1NSAyOC42ODkyIDI0LjkyNTRDMjguNzgwNiAyNC45MjM0IDI4Ljg2MSAyNC44NjI5IDI4Ljg4NjggMjQuNzc0NVoiCiAgICBmaWxsPSJ1cmwoI3BhaW50MF9saW5lYXJfMjYxXzU4NTkpIiAvPgogIDxwYXRoCiAgICBkPSJNMzEuNzY5NSAxOC43ODc5QzMxLjY4OTIgMTguNzg3OSAzMS42MDkzIDE4Ljc5MDIgMzEuNTI5OCAxOC43OTQxQzMxLjUxNjcgMTguNzk0OCAzMS41MDQyIDE4Ljc5OCAzMS40OTIzIDE4LjgwMjJDMzEuNDUwOCAxOC44MTY3IDMxLjQxNzcgMTguODUwMyAzMS40MDUxIDE4Ljg5NDFMMzEuMDY0OCAyMC4wNjk1QzMwLjkxODUgMjAuNTc0NiAzMC45NzI5IDIxLjA0MTIgMzEuMjE4NCAyMS4zODQyQzMxLjQ0NDEgMjEuNzAwNyAzMS44MjA0IDIxLjg4NjMgMzIuMjc3MyAyMS45MDc5TDM0LjEyMjQgMjIuMDE4N0MzNC4xNzY4IDIyLjAyMTMgMzQuMjI0NyAyMi4wNDc2IDM0LjI1NCAyMi4wOUMzNC4yODQ4IDIyLjEzNDggMzQuMjkxOCAyMi4xOTIzIDM0LjI3MzMgMjIuMjQ3MUMzNC4yNDQzIDIyLjMzMjQgMzQuMTYwMiAyMi4zOTY4IDM0LjA3MjYgMjIuNDAwN0wzMi4xNTUzIDIyLjUxMTRDMzEuMTE0NSAyMi41NTkzIDI5Ljk5MjcgMjMuMzk5OCAyOS41OTk4IDI0LjQyNTFMMjkuNDYxMiAyNC43ODcxQzI5LjQzNiAyNC44NTI2IDI5LjQ4MyAyNC45MjIzIDI5LjU1MjIgMjQuOTI1OEMyOS41NTQgMjQuOTI1OCAyOS41NTU2IDI0LjkyNjQgMjkuNTU3MyAyNC45MjY0SDM2LjE1NDJDMzYuMjMzIDI0LjkyNjQgMzYuMzAzMiAyNC44NzUxIDM2LjMyNDQgMjQuNzk5NEMzNi40MzkgMjQuMzkxOSAzNi41IDIzLjk2MjQgMzYuNSAyMy41MTgzQzM2LjUgMjAuOTA1NyAzNC4zODIxIDE4Ljc4NzkgMzEuNzY5NSAxOC43ODc5WiIKICAgIGZpbGw9InVybCgjcGFpbnQxX2xpbmVhcl8yNjFfNTg1OSkiIC8+CiAgPHBhdGgKICAgIGQ9Ik00Ni4wODAxIDI0LjVWMTQuNjM1N0g0OS42ODI2QzUyLjYyMjEgMTQuNjM1NyA1NC4zNzIxIDE2LjQxMzEgNTQuMzcyMSAxOS41MzAzVjE5LjU0MzlDNTQuMzcyMSAyMi42NjggNTIuNjM1NyAyNC41IDQ5LjY4MjYgMjQuNUg0Ni4wODAxWk00Ny44NDM4IDIzLjAwOThINDkuNDk4QzUxLjQ4MDUgMjMuMDA5OCA1Mi41NzQyIDIxLjc5OTggNTIuNTc0MiAxOS41NTA4VjE5LjUzNzFDNTIuNTc0MiAxNy4zMzU5IDUxLjQ2IDE2LjEyNiA0OS40OTggMTYuMTI2SDQ3Ljg0MzhWMjMuMDA5OFpNNTguNzg4MSAyNC42NDM2QzU2LjYxNDMgMjQuNjQzNiA1NS4zMDE4IDIzLjIwMTIgNTUuMzAxOCAyMC44OTc1VjIwLjg5MDZDNTUuMzAxOCAxOC42MDc0IDU2LjYzNDggMTcuMTAzNSA1OC43MDYxIDE3LjEwMzVDNjAuNzc3MyAxNy4xMDM1IDYyLjA2MjUgMTguNTU5NiA2Mi4wNjI1IDIwLjc0NzFWMjEuMjkzOUg1Ni45OTAyQzU3LjAxNzYgMjIuNTY1NCA1Ny43MTQ4IDIzLjMxNzQgNTguODIyMyAyMy4zMTc0QzU5LjY2OTkgMjMuMzE3NCA2MC4yMjM2IDIyLjg2NjIgNjAuMzg3NyAyMi4zODA5TDYwLjQwMTQgMjIuMzMzSDYxLjk5NDFMNjEuOTczNiAyMi40MDgyQzYxLjc0OCAyMy41MjI1IDYwLjY4MTYgMjQuNjQzNiA1OC43ODgxIDI0LjY0MzZaTTU4LjcyNjYgMTguNDM2NUM1Ny44MjQyIDE4LjQzNjUgNTcuMTQ3NSAxOS4wNDQ5IDU3LjAxMDcgMjAuMTU5Mkg2MC40MDgyQzYwLjI4NTIgMTkuMDEwNyA1OS42Mjg5IDE4LjQzNjUgNTguNzI2NiAxOC40MzY1Wk02My4xNjMxIDI2Ljg5MjZWMTcuMjUzOUg2NC44NjUyVjE4LjUwNDlINjQuODk5NEM2NS4zMTY0IDE3LjYzNjcgNjYuMTA5NCAxNy4xMDM1IDY3LjE0ODQgMTcuMTAzNUM2OC45ODczIDE3LjEwMzUgNzAuMTQ5NCAxOC41MzkxIDcwLjE0OTQgMjAuODc3VjIwLjg4MzhDNzAuMTQ5NCAyMy4yMDggNjguOTg3MyAyNC42NDM2IDY3LjE2ODkgMjQuNjQzNkM2Ni4xMzY3IDI0LjY0MzYgNjUuMzA5NiAyNC4xMjQgNjQuODk5NCAyMy4yNzY0SDY0Ljg2NTJWMjYuODkyNkg2My4xNjMxWk02Ni42NDI2IDIzLjIwOEM2Ny43Mjk1IDIzLjIwOCA2OC40MTMxIDIyLjMxMjUgNjguNDEzMSAyMC44ODM4VjIwLjg3N0M2OC40MTMxIDE5LjQyNzcgNjcuNzI5NSAxOC41MzkxIDY2LjY0MjYgMTguNTM5MUM2NS41ODk4IDE4LjUzOTEgNjQuODUxNiAxOS40NTUxIDY0Ljg1MTYgMjAuODc3VjIwLjg4MzhDNjQuODUxNiAyMi4yOTg4IDY1LjU4OTggMjMuMjA4IDY2LjY0MjYgMjMuMjA4Wk03MS4yOTEgMjQuNVYxNC42MzU3SDcyLjk5MzJWMjQuNUg3MS4yOTFaTTc3LjY0ODQgMjQuNjQzNkM3NS41MTU2IDI0LjY0MzYgNzQuMTQxNiAyMy4yMjE3IDc0LjE0MTYgMjAuODc3VjIwLjg2MzNDNzQuMTQxNiAxOC41MzkxIDc1LjUzNjEgMTcuMTAzNSA3Ny42NDE2IDE3LjEwMzVDNzkuNzUzOSAxNy4xMDM1IDgxLjE1NTMgMTguNTI1NCA4MS4xNTUzIDIwLjg2MzNWMjAuODc3QzgxLjE1NTMgMjMuMjI4NSA3OS43NzQ0IDI0LjY0MzYgNzcuNjQ4NCAyNC42NDM2Wk03Ny42NTUzIDIzLjI2OTVDNzguNzI4NSAyMy4yNjk1IDc5LjQxODkgMjIuMzk0NSA3OS40MTg5IDIwLjg3N1YyMC44NjMzQzc5LjQxODkgMTkuMzUyNSA3OC43MjE3IDE4LjQ4NDQgNzcuNjQxNiAxOC40ODQ0Qzc2LjU4MiAxOC40ODQ0IDc1Ljg3NzkgMTkuMzU5NCA3NS44Nzc5IDIwLjg2MzNWMjAuODc3Qzc1Ljg3NzkgMjIuNDAxNCA3Ni41Njg0IDIzLjI2OTUgNzcuNjU1MyAyMy4yNjk1Wk04Mi45NiAyNi45MDYyQzgyLjYzMTggMjYuOTA2MiA4Mi4yOSAyNi44NjUyIDgyLjA4NSAyNi44MzExVjI1LjUzMjJDODIuMjE0OCAyNS41NTk2IDgyLjQxMzEgMjUuNTkzOCA4Mi42NTIzIDI1LjU5MzhDODMuMzAxOCAyNS41OTM4IDgzLjY2NDEgMjUuNDA5MiA4My44ODI4IDI0LjgwMDhMODMuOTg1NCAyNC41MDY4TDgxLjM4MDkgMTcuMjUzOUg4My4yNDAyTDg0LjkzNTUgMjMuMDUwOEg4NC45ODM0TDg2LjY4NTUgMTcuMjUzOUg4OC40NzY2TDg1Ljg3MjEgMjQuNzQ2MUM4NS4zMTg0IDI2LjMzODkgODQuNDcwNyAyNi45MDYyIDgyLjk2IDI2LjkwNjJaTTk0Ljc1ODggMjQuNjQzNkM5My4yNDEyIDI0LjY0MzYgOTIuNTIzNCAyNC4wMjgzIDkyLjUyMzQgMjIuNTM4MVYxOC41NjY0SDkxLjQ5OFYxNy4yNTM5SDkyLjUyMzRWMTUuNDE1SDk0LjI1MjlWMTcuMjUzOUg5NS41OTk2VjE4LjU2NjRIOTQuMjUyOVYyMi4zOTQ1Qzk0LjI1MjkgMjMuMTA1NSA5NC41Njc0IDIzLjMzMTEgOTUuMTg5NSAyMy4zMzExQzk1LjM1MzUgMjMuMzMxMSA5NS40ODM0IDIzLjMxMDUgOTUuNTk5NiAyMy4zMDM3VjI0LjU4MkM5NS40MDE0IDI0LjYwOTQgOTUuMTAwNiAyNC42NDM2IDk0Ljc1ODggMjQuNjQzNlpNOTkuODM3OSAyNC42NDM2Qzk3LjcwNTEgMjQuNjQzNiA5Ni4zMzExIDIzLjIyMTcgOTYuMzMxMSAyMC44NzdWMjAuODYzM0M5Ni4zMzExIDE4LjUzOTEgOTcuNzI1NiAxNy4xMDM1IDk5LjgzMTEgMTcuMTAzNUMxMDEuOTQzIDE3LjEwMzUgMTAzLjM0NSAxOC41MjU0IDEwMy4zNDUgMjAuODYzM1YyMC44NzdDMTAzLjM0NSAyMy4yMjg1IDEwMS45NjQgMjQuNjQzNiA5OS44Mzc5IDI0LjY0MzZaTTk5Ljg0NDcgMjMuMjY5NUMxMDAuOTE4IDIzLjI2OTUgMTAxLjYwOCAyMi4zOTQ1IDEwMS42MDggMjAuODc3VjIwLjg2MzNDMTAxLjYwOCAxOS4zNTI1IDEwMC45MTEgMTguNDg0NCA5OS44MzExIDE4LjQ4NDRDOTguNzcxNSAxOC40ODQ0IDk4LjA2NzQgMTkuMzU5NCA5OC4wNjc0IDIwLjg2MzNWMjAuODc3Qzk4LjA2NzQgMjIuNDAxNCA5OC43NTc4IDIzLjI2OTUgOTkuODQ0NyAyMy4yNjk1Wk0xMTEuNzA1IDI0LjY3MDlDMTA4Ljg2OCAyNC42NzA5IDEwNy4wNzcgMjIuNzE1OCAxMDcuMDc3IDE5LjU2NDVWMTkuNTU3NkMxMDcuMDc3IDE2LjQwNjIgMTA4Ljg3NSAxNC40NjQ4IDExMS43MDUgMTQuNDY0OEMxMTMuOTc1IDE0LjQ2NDggMTE1LjY0MyAxNS44Nzk5IDExNS45MDIgMTcuODg5NkwxMTUuOTA5IDE3Ljk1OEgxMTQuMThMMTE0LjE0NiAxNy44MjgxQzExMy44NTggMTYuNzAwMiAxMTIuOTkgMTUuOTk2MSAxMTEuNzA1IDE1Ljk5NjFDMTA5Ljk4MiAxNS45OTYxIDEwOC44ODIgMTcuMzcwMSAxMDguODgyIDE5LjU1NzZWMTkuNTY0NUMxMDguODgyIDIxLjc1ODggMTA5Ljk4OSAyMy4xMzk2IDExMS43MDUgMjMuMTM5NkMxMTIuOTYzIDIzLjEzOTYgMTEzLjg0NSAyMi40NjI5IDExNC4xNjYgMjEuMjQ2MUwxMTQuMTg3IDIxLjE3NzdIMTE1LjkxNkwxMTUuOTAyIDIxLjI0NjFDMTE1LjY0OSAyMy4yNjk1IDExMy45NzUgMjQuNjcwOSAxMTEuNzA1IDI0LjY3MDlaTTExNy4xMzMgMjQuNVYxNC42MzU3SDExOC44MzVWMjQuNUgxMTcuMTMzWk0xMjMuNDkgMjQuNjQzNkMxMjEuMzU3IDI0LjY0MzYgMTE5Ljk4MyAyMy4yMjE3IDExOS45ODMgMjAuODc3VjIwLjg2MzNDMTE5Ljk4MyAxOC41MzkxIDEyMS4zNzggMTcuMTAzNSAxMjMuNDgzIDE3LjEwMzVDMTI1LjU5NiAxNy4xMDM1IDEyNi45OTcgMTguNTI1NCAxMjYuOTk3IDIwLjg2MzNWMjAuODc3QzEyNi45OTcgMjMuMjI4NSAxMjUuNjE2IDI0LjY0MzYgMTIzLjQ5IDI0LjY0MzZaTTEyMy40OTcgMjMuMjY5NUMxMjQuNTcgMjMuMjY5NSAxMjUuMjYxIDIyLjM5NDUgMTI1LjI2MSAyMC44NzdWMjAuODYzM0MxMjUuMjYxIDE5LjM1MjUgMTI0LjU2MyAxOC40ODQ0IDEyMy40ODMgMTguNDg0NEMxMjIuNDI0IDE4LjQ4NDQgMTIxLjcyIDE5LjM1OTQgMTIxLjcyIDIwLjg2MzNWMjAuODc3QzEyMS43MiAyMi40MDE0IDEyMi40MSAyMy4yNjk1IDEyMy40OTcgMjMuMjY5NVpNMTMwLjU1OSAyNC42NDM2QzEyOC45NjYgMjQuNjQzNiAxMjguMDU3IDIzLjYxODIgMTI4LjA1NyAyMS45MzY1VjE3LjI1MzlIMTI5Ljc1OVYyMS42MDE2QzEyOS43NTkgMjIuNjI3IDEzMC4yMzcgMjMuMjA4IDEzMS4yMDggMjMuMjA4QzEzMi4xODYgMjMuMjA4IDEzMi44MDggMjIuNTAzOSAxMzIuODA4IDIxLjQ1MTJWMTcuMjUzOUgxMzQuNTFWMjQuNUgxMzIuODA4VjIzLjM2NTJIMTMyLjc3M0MxMzIuMzk3IDI0LjEzNzcgMTMxLjY1MiAyNC42NDM2IDEzMC41NTkgMjQuNjQzNlpNMTM4LjYwNCAyNC42NDM2QzEzNi43NzIgMjQuNjQzNiAxMzUuNjEgMjMuMjA4IDEzNS42MSAyMC44NzdWMjAuODcwMUMxMzUuNjEgMTguNTMyMiAxMzYuNzc5IDE3LjEwMzUgMTM4LjU5OCAxNy4xMDM1QzEzOS42MjMgMTcuMTAzNSAxNDAuNDUgMTcuNjI5OSAxNDAuODYgMTguNDk4SDE0MC45MDFWMTQuNjM1N0gxNDIuNjA0VjI0LjVIMTQwLjkwMVYyMy4yNjk1SDE0MC44NkMxNDAuNDUgMjQuMTI0IDEzOS42NSAyNC42NDM2IDEzOC42MDQgMjQuNjQzNlpNMTM5LjExNyAyMy4yMDhDMTQwLjE3IDIzLjIwOCAxNDAuOTAxIDIyLjI5ODggMTQwLjkwMSAyMC44NzdWMjAuODcwMUMxNDAuOTAxIDE5LjQ1NTEgMTQwLjE2MyAxOC41MzkxIDEzOS4xMTcgMTguNTM5MUMxMzguMDMgMTguNTM5MSAxMzcuMzQ3IDE5LjQyNzcgMTM3LjM0NyAyMC44NzAxVjIwLjg3N0MxMzcuMzQ3IDIyLjMxOTMgMTM4LjAyMyAyMy4yMDggMTM5LjExNyAyMy4yMDhaTTE0NC41MDQgMjQuNVYxOC41NjY0SDE0My41MTNWMTcuMjUzOUgxNDQuNTA0VjE2LjU2MzVDMTQ0LjUwNCAxNS4xNDg0IDE0NS4xNzQgMTQuNDkyMiAxNDYuNzQ2IDE0LjQ5MjJDMTQ3LjA4MSAxNC40OTIyIDE0Ny40NDMgMTQuNTE5NSAxNDcuNjU1IDE0LjU2MDVWMTUuNzVDMTQ3LjUxOSAxNS43Mjk1IDE0Ny4zMjcgMTUuNzE1OCAxNDcuMTQzIDE1LjcxNThDMTQ2LjQ3OSAxNS43MTU4IDE0Ni4xNzIgMTYuMDIzNCAxNDYuMTcyIDE2LjYxMTNWMTcuMjUzOUgxNDcuNjI4VjE4LjU2NjRIMTQ2LjIwNlYyNC41SDE0NC41MDRaTTE0OC43OTcgMjQuNVYxNC42MzU3SDE1MC40OTlWMjQuNUgxNDguNzk3Wk0xNTQuMDg4IDI0LjYyM0MxNTIuNjM5IDI0LjYyMyAxNTEuNjYxIDIzLjcyNzUgMTUxLjY2MSAyMi40MzU1VjIyLjQyMTlDMTUxLjY2MSAyMS4xMzY3IDE1Mi42NTkgMjAuMzY0MyAxNTQuNDE2IDIwLjI1NDlMMTU2LjMxIDIwLjEzODdWMTkuNjM5NkMxNTYuMzEgMTguOTA4MiAxNTUuODMxIDE4LjQ2MzkgMTU0Ljk3IDE4LjQ2MzlDMTU0LjE2MyAxOC40NjM5IDE1My42NzEgMTguODM5OCAxNTMuNTYyIDE5LjM3M0wxNTMuNTQ4IDE5LjQzNDZIMTUxLjk2OUwxNTEuOTc2IDE5LjM1MjVDMTUyLjA3OCAxOC4wNjc0IDE1My4xOTIgMTcuMTAzNSAxNTUuMDMxIDE3LjEwMzVDMTU2Ljg0MyAxNy4xMDM1IDE1OC4wMTIgMTguMDYwNSAxNTguMDEyIDE5LjUxNjZWMjQuNUgxNTYuMzFWMjMuMzg1N0gxNTYuMjY5QzE1NS44NTIgMjQuMTQ0NSAxNTUuMDQ1IDI0LjYyMyAxNTQuMDg4IDI0LjYyM1pNMTUzLjM1NiAyMi4zNjcyQzE1My4zNTYgMjIuOTYxOSAxNTMuODQ5IDIzLjMyNDIgMTU0LjU5NCAyMy4zMjQyQzE1NS41NzEgMjMuMzI0MiAxNTYuMzEgMjIuNjc0OCAxNTYuMzEgMjEuODEzNVYyMS4yNjY2TDE1NC42NTUgMjEuMzY5MUMxNTMuODE0IDIxLjQyMzggMTUzLjM1NiAyMS43ODYxIDE1My4zNTYgMjIuMzYwNFYyMi4zNjcyWk0xNTkuMzg2IDI0LjVWMTcuMjUzOUgxNjEuMDRWMTguNDYzOUgxNjEuMDc0QzE2MS4yOTMgMTcuNjE2MiAxNjEuOTI5IDE3LjEwMzUgMTYyLjc4MyAxNy4xMDM1QzE2Mi45OTUgMTcuMTAzNSAxNjMuMTkzIDE3LjEzNzcgMTYzLjMyMyAxNy4xNzE5VjE4LjcxQzE2My4xOCAxOC42NTUzIDE2Mi45MiAxOC42MTQzIDE2Mi42MzMgMTguNjE0M0MxNjEuNjY5IDE4LjYxNDMgMTYxLjA4OCAxOS4yMzYzIDE2MS4wODggMjAuMjU0OVYyNC41SDE1OS4zODZaTTE2Ny4xMSAyNC42NDM2QzE2NC45MzcgMjQuNjQzNiAxNjMuNjI0IDIzLjIwMTIgMTYzLjYyNCAyMC44OTc1VjIwLjg5MDZDMTYzLjYyNCAxOC42MDc0IDE2NC45NTcgMTcuMTAzNSAxNjcuMDI4IDE3LjEwMzVDMTY5LjEgMTcuMTAzNSAxNzAuMzg1IDE4LjU1OTYgMTcwLjM4NSAyMC43NDcxVjIxLjI5MzlIMTY1LjMxMkMxNjUuMzQgMjIuNTY1NCAxNjYuMDM3IDIzLjMxNzQgMTY3LjE0NSAyMy4zMTc0QzE2Ny45OTIgMjMuMzE3NCAxNjguNTQ2IDIyLjg2NjIgMTY4LjcxIDIyLjM4MDlMMTY4LjcyNCAyMi4zMzNIMTcwLjMxNkwxNzAuMjk2IDIyLjQwODJDMTcwLjA3IDIzLjUyMjUgMTY5LjAwNCAyNC42NDM2IDE2Ny4xMSAyNC42NDM2Wk0xNjcuMDQ5IDE4LjQzNjVDMTY2LjE0NiAxOC40MzY1IDE2NS40NyAxOS4wNDQ5IDE2NS4zMzMgMjAuMTU5MkgxNjguNzNDMTY4LjYwNyAxOS4wMTA3IDE2Ny45NTEgMTguNDM2NSAxNjcuMDQ5IDE4LjQzNjVaIgogICAgZmlsbD0idXJsKCNwYWludDJfbGluZWFyXzI2MV81ODU5KSIgLz4KICA8ZGVmcz4KICAgIDxsaW5lYXJHcmFkaWVudCBpZD0icGFpbnQwX2xpbmVhcl8yNjFfNTg1OSIgeDE9IjE0LjI5MiIgeTE9IjEyLjkxMDgiIHgyPSIxMy4yMTc1IiB5Mj0iMjMuNDQ4OCIKICAgICAgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPgogICAgICA8c3RvcCBzdG9wLWNvbG9yPSIjRkJBRDQxIiAvPgogICAgICA8c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGRjY2MzMiIC8+CiAgICA8L2xpbmVhckdyYWRpZW50PgogICAgPGxpbmVhckdyYWRpZW50IGlkPSJwYWludDFfbGluZWFyXzI2MV81ODU5IiB4MT0iMzAuMTM3MSIgeTE9IjE4LjEzMDIiIHgyPSIyOS4yNDU4IiB5Mj0iMjQuMDE3OCIKICAgICAgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPgogICAgICA8c3RvcCBzdG9wLWNvbG9yPSIjRkJBRDQxIiAvPgogICAgICA8c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGRjY2MzMiIC8+CiAgICA8L2xpbmVhckdyYWRpZW50PgogICAgPGxpbmVhckdyYWRpZW50IGlkPSJwYWludDJfbGluZWFyXzI2MV81ODU5IiB4MT0iNDQuNTMwMyIgeTE9IjI1LjMzMzMiIHgyPSIxMzkuOTA3IiB5Mj0iNzguMDcxMyIKICAgICAgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPgogICAgICA8c3RvcCBzdG9wLWNvbG9yPSIjRkJBRDQxIiAvPgogICAgICA8c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGRjY2MzMiIC8+CiAgICA8L2xpbmVhckdyYWRpZW50PgogIDwvZGVmcz4KPC9zdmc+)](https://deploy.workers.cloudflare.com/?url=https://github.com/DZBuild-com/dzbuild-app-starter/tree/main/cloudflare-basic) If you host on your own server instead, the Node.js example in the same [repository](https://github.com/DZBuild-com/dzbuild-app-starter) 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[​](#1-register-the-app "Direct link to 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: | Field | What to enter | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | The app name merchants see on the consent screen. | | Developer name | Your name or your company's name, shown on the consent screen. | | Descriptions | One description each in English, Arabic and French. | | Homepage | Your 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 email | The address merchants write to for help. | | Launch URL | The `https` page that opens when a merchant clicks **Open** on your app. | | Redirect URIs | One to five exact URIs. DZBuild sends the authorization code only to these. | | Scopes | The permissions your app may request. See [Scopes](https://dzbuild.dev/scopes.md). | | Minimum plan | The lowest store plan that may use your app. Leave it on Free to allow every store. | | Webhook URL and events | Optional. See [Webhooks](https://dzbuild.dev/webhooks.md). | Save the app. The console then shows three credentials: | Credential | Format | Where it lives | | -------------- | -------------------------------------- | -------------------------------------------------------------------------------------- | | `client_id` | `dzapp_` followed by 20 hex characters | Public. It goes in the authorize URL. | | Client secret | `dzas_` followed by 48 hex characters | Shown once. Store it on your server. Generate a new one in the console if you lose it. | | Signing secret | 64 hex characters | Viewable 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[​](#2-choose-scopes "Direct link to 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](https://dzbuild.dev/scopes.md) page. ## 3. Set your redirect URIs[​](#3-set-your-redirect-uris "Direct link to 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[​](#4-install-the-app-on-your-own-store "Direct link to 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](https://dzbuild.dev/oauth.md) page lists every error this call can return. ## 5. Make your first call[​](#5-make-your-first-call "Direct link to 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[​](#6-read-the-app-object "Direct link to 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. | Field | Meaning | | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | | `app_id` | Your app's numeric id on DZBuild. | | `client_id` | Your app's public client id. Compare it with your own to reject tokens issued to another app. | | `install_id` | The 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](https://dzbuild.dev/concepts.md). ## Next steps[​](#next-steps "Direct link to Next steps") * Read [Core concepts](https://dzbuild.dev/concepts.md) before you build on install tokens. * Add [webhook verification](https://dzbuild.dev/webhooks.md) if you registered a webhook URL. * Read the [review guidelines](https://dzbuild.dev/review-guidelines.md), then submit the app for review from the console.