# 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.

Source: https://hekana.dev/apps/lifecycle

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](https://hekana.dev/apps/authentication)).
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`:

```json title="POST /oauth/apps/:id/versions (request body)"
{ "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](https://hekana.dev/apps/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](https://hekana.dev/apps/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.