Authorization

This page is for anyone implementing the app install flow. By the end you know every parameter of the consent URL, the shape and lifetime of each token, how to refresh and handle revocation, and what every error means.

The model#

• Your app is a confidential client: it presents client_id and client_secret at token exchange and uses PKCE (S256) at the same time. Both, not either.
• Every install binds one app to one store and issues its own tokens. No token ever covers more than one store.
• The effective scopes of any request are: the scopes granted at consent ∩ the granting member's live permissions. If the member loses a permission, your app loses it on the very next request.

The consent URL#

GET https://dukkan.one/apps/oauth/authorize

The server answers with a direct HTTP error — no redirect — whenever it cannot trust the redirect URI: 400 for an unknown client or an unregistered redirect_uri, 403 for an app that is not available for installation. Every later error is returned to redirect_uri as an error parameter (see Errors).

The consent screen#

The merchant sees every scope as a plain Arabic sentence (for example "Read orders, line items and fulfillment status"). Financial scopes carry a warning color, orders:create carries the caption "These orders appear in your admin marked with the app name. Stock is reduced like any other order.", and clients:read and clients:write sit in their own section, unchecked by default, because they expose customer data. A merchant may grant a subset, so read scope from the token response and never assume what you asked for.

Exchange the code for tokens#

POST https://dukkan.one/apps/oauth/token

Send client credentials in an Authorization: Basic header (or in the body as client_id and client_secret) and the body as application/x-www-form-urlencoded:

import { exchangeCode } from "@dukkan.one/app-sdk/oauth";

const tokens = await exchangeCode({
  credentials: { clientId: CLIENT_ID, clientSecret: CLIENT_SECRET },
  code: AUTH_CODE,
  redirectUri: "https://app.example.com/callback",
  codeVerifier: PKCE_VERIFIER,
});

curl -X POST https://dukkan.one/apps/oauth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=PKCE_VERIFIER

{
  "access_token": "dk_app_at_REDACTED_EXAMPLE_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dk_app_rt_REDACTED_EXAMPLE_TOKEN",
  "scope": "orders:read orders:write",
  "install_id": "8b2c1d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
  "store_id": "3065a1f2-0c4d-4e8b-b7a9-5d2f8c1e9a44",
  "store_slug": "sham-perfumes"
}

A code is single-use. Any attempt to reuse a consumed code revokes every token of that install (theft protection, per RFC 6749).

GET /installation returns the same identity later, together with the effective scopes, the store's currency exponent, locale and timezone, and the current webhook subscription; see the Installation reference.

The refresh grant#

curl -X POST https://dukkan.one/apps/oauth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=YOUR_REFRESH_TOKEN

{
  "access_token": "dk_app_at_REDACTED_NEW_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dk_app_rt_REDACTED_NEW_TOKEN",
  "scope": "orders:read orders:write",
  "install_id": "8b2c1d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
  "store_id": "3065a1f2-0c4d-4e8b-b7a9-5d2f8c1e9a44",
  "store_slug": "sham-perfumes"
}

• Every refresh returns a new pair; store both atomically and discard the old ones. The refresh response also carries scope, install_id, store_id and store_slug.
• Reusing a refresh token that was already rotated is treated as theft: the install's entire token chain is revoked and the request returns invalid_grant. Send the merchant back through the consent URL.
• One exception keeps multi-instance apps safe: presenting a token that was rotated less than 30 seconds earlier, while its successor is still valid, is treated as a race between two of your instances. The request returns invalid_grant and nothing is revoked; re-read your token store and use the pair the other instance saved. Serialize refreshes per install anyway.
• Do not refresh long before the access token expires; refresh on 401 or a few minutes before expiry.

Token prefixes#

Every token is stored server-side as a SHA-256 hash only and can never be read back.

Revocation#

• When a merchant uninstalls, the install's tokens are revoked immediately and you receive app.uninstalled — no scope required — even after revocation. Handle it by deleting that store's data.
• When your app is suspended (by you or by Dukkan) tokens are revoked and subscriptions disabled; see App lifecycle.
• Calling the Platform API with a revoked or expired token returns 401 with the error body and code unauthorized.

Errors#

A consent-URL error comes back to redirect_uri as the error parameter (with state); a token-endpoint error is a JSON body { "error": "…" }.

Limits: 60 requests per 10 minutes per IP address on both endpoints, and 600 requests per 10 minutes per client on the token endpoint. Exceeding them returns 429.

Security checklist#

• Generate a random state per session and verify it on return.
• Keep code_verifier in a server-side session, never in the browser.
• Store the client secret and refresh tokens encrypted on the server only; never send any token to a client.
• The secret rotation schedule with an overlap window (24 hours by default) is described in App lifecycle.
• Treat invalid_grant on refresh as a signal to re-authorize, not to retry.