Skip to content

Install and uninstall

The life of an installation: the merchant consent screen, scope changes and re-consent, versions, suspension, and exactly what happens when a store uninstalls.

On this page

An installation is the link between your app and one store. It holds the scopes the store approved. Every token you hold belongs to an installation.

Install

  1. Your app sends the store owner to the dashboard consent page, /oauth/authorize (Authentication and scopes).
  2. On approval Hekana creates the installation with the scopes requested, or reactivates the store's earlier installation of your app with the new scopes.
  3. Your server exchanges the code for tokens.

The app must be approved for any of this to work. The consent screen lists the app name and every scope. The install starts from a link you build into your own site or product.

Installed third-party apps show up for the store in its list of installed apps, with what each has charged.

New versions and new scopes

Release a version with POST /oauth/apps/:id/versions:

POST /oauth/apps/:id/versions (request body)JSON
{ "version": "1.2.0", "changelog": "Adds order messages." }

version is major.minor.patch and must be higher than the last one. Each version snapshots the scopes the app asks for at that moment. GET /oauth/apps/:id/versions lists them, newest first. A release that asks for more scopes than the previous one reports which were added (addedScopes) and how many installed stores have not approved them (installationsNeedingConsent).

Stores that installed earlier keep the scopes they approved. Tokens never carry more than the store's current grant, so a new scope is unusable for a store until its owner goes through the consent screen again. Remember that adding a scope to an approved app sends it back to review (Testing and going live).

Suspension

A reviewer can suspend an app with a reason. All of its tokens stop working immediately across every store, refresh stops, the developer is told, and every store with the app installed is told too.

Uninstall

A store owner or admin uninstalls with POST /oauth/apps/:id/uninstall. In order:

  1. The installation is marked revoked and all its tokens stop working. Your API calls now answer 401 invalid_token.
  2. Your webhook endpoints receive one app/uninstalled notice each (see Webhooks), and every subscription is switched off. Events still waiting are dropped.
  3. Everything in your /data store for that installation is deleted.
  4. Your checkout extensions are removed from the store's checkout.

What is not deleted by Hekana: anything you copied to your own systems. There is no separate erasure request; treat app/uninstalled as the signal to delete or anonymise that store's data on your side.

If the store installs again later, it is a fresh grant through the consent screen. Your earlier data store is not restored.

Next steps