Skip to content
Dukkan DevelopersDocs
العربيةSign in

App lifecycle

Distribution channels, install and uninstall, suspension and its effects, and client-secret rotation.

Updated 2 Sept 20263 min read
On this page

This page is for anyone operating an app in production. By the end you know how an app reaches a store, what happens on uninstall or suspension, and how to rotate the client secret without downtime.

Distribution channels#

Channel Who installs How
Development (development) your sandbox and linked stores from the app page create a development distribution grant for the store
Private (private) one specific organization or store a private distribution grant issues an install_token you pass in the consent URL
Public (public) every merchant from the marketplace a published listing after review

Creating a grant requires the owner or admin role and recent authentication (a sign-in within the last 15 minutes). A grant can be revoked at any time from the app page.

Install#

An install begins when the merchant completes the consent screen and your app exchanges the code for tokens. The install is bound to a specific version of your app (the scopes and topics as they were at consent). One install = one app + one store + one granting member; its scopes are always intersected with that member's live permissions.

Uninstall#

When a merchant uninstalls:

  1. Every token is revoked immediately and every later call returns 401.
  2. app.uninstalled is emitted with payload { "app_id": "…", "install_id": "…" } and delivered even after revocation if your subscription includes the topic.
  3. Subscriptions are closed and later store events are dropped.

Your obligation: delete that store's data — and its customers' data if you held clients:read — as described in Data processing. With the SDK, the receiver marks the install's tokens as needing reconnection before your app.uninstalled handler (or the Nuxt module's onUninstall) runs, so the deletion and the token invalidation cannot get out of step.

Suspension#

You can suspend your app as an emergency measure from its page (owner or admin), and Dukkan can suspend it for a breach of the terms. The effect is atomic:

  • Active tokens in every install are revoked and stop refreshing.
  • Webhook subscriptions are disabled with reason app_suspended; nothing is delivered, not even the farewell notice.
  • Distribution grants are withdrawn, the marketplace listing is delisted, and the distribution mode falls back to private.
  • Existing installs remain recorded but inactive.

Unsuspending restores subscriptions to their prior state, but revoked tokens do not return: your app must bring the merchant back through the refresh grant or a fresh authorization. Events that occurred during the suspension wait and are not lost.

Rotate the client secret#

From the app page (owner or admin, with recent authentication) choose Rotate secret. A new secret is minted and shown once, and the old one stays valid during an overlap window you choose: 24 hours by default, up to 30 days, or zero for an immediate cut.

The safe procedure:

  1. Mint the new secret with a window long enough to redeploy every instance of your app.
  2. Roll the new secret out to all your environments; the server accepts both secrets until the previous_secret_expires_at the response returns.
  3. After the window the old secret is refused with invalid_client. No merchant re-authorization is needed; issued tokens are unaffected.

The webhook signing secret is independent: rotate it through PUT /webhooks with rotate_secret: true as described in Webhooks. There is no overlap window there; update your endpoint before the call.

Versions#

Every change to scopes, topics or redirect URIs is saved as a new version. Existing installs stay on their version until the merchant consents again, and their scopes never widen silently. The marketplace listing always points at the version that was reviewed.