# Install, tokens and session tokens

> How an app is installed with OAuth, how it gets and refreshes its tokens, and how it recognizes the user in an embedded page.

Source: https://developers-staging.foodpilot.tech/build/authentication

In this page you will learn the three credentials an app deals with: the installation token it calls the App API with, the secret that signs webhooks, and the session token that tells it who is using an embedded page.

## The install flow

The install is an OAuth 2.0 authorization-code flow, with consent on scopes and on organizations.

1. The administrator starts the install in the platform. The platform sends the browser to your manifest's `install_url`, with `?platform=<platform name>`.
2. Your app checks that it knows the platform, then redirects the browser to the platform's consent page, `/admin/oauth/authorize`, with `client_id`, `redirect_uri`, `scope`, a `state` you will check, and a PKCE challenge (`code_challenge`, `code_challenge_method=S256`).
3. The administrator reviews the scopes you asked for and chooses the organizations. The platform sends the browser back to your `redirect_uri` with `code`, `state` and `platform`.
4. Your server checks `state`, then calls `POST /oauth/token` on the platform's API host with `grant_type=authorization_code`, your `client_id` and `client_secret`, the `code`, the same `redirect_uri` and the PKCE `code_verifier`.

| Rule | Value |
|---|---|
| The `scope` parameter | A subset of the scopes of your manifest. Consent shows exactly that parameter. |
| The `redirect_uri` | One of the `redirect_urls` of your manifest, compared exactly. |
| A code | Single use, valid 60 seconds. Presenting a used code again revokes the refresh tokens it produced. |
| What an administrator can grant | Only what they hold themselves, on the organizations they belong to. |

An app has at most one live installation per platform. Consenting again to an installed app is a re-consent: it changes the scopes and organizations of the same installation, and your existing tokens see the change at once.

## The token response

```json
{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<opaque>",
  "scope": "read_products read_organizations",
  "webhook_secret": "<only on the first activation>"
}
```

- **`access_token`** is the installation token. Send it as `Authorization: Bearer` to the [App API](/build/app-api), and to nothing else: any other route answers `403`.
- **`refresh_token`** lasts 90 days and is rotated at every use.
- **`webhook_secret`** is sent once, when the installation is first activated. It is the key that signs your [webhooks](/build/webhooks). Store it with the installation.

Errors follow RFC 6749: `invalid_request`, `invalid_client`, `invalid_grant`, `unsupported_grant_type`, `server_error`.

## Refresh

```bash
curl -X POST https://{tenant}-api.example.com/oauth/token \
  -d grant_type=refresh_token -d client_id=<client_id> \
  -d client_secret=<client_secret> -d refresh_token=<refresh_token>
```

The answer carries a new access token and a new refresh token. Use each refresh token once: a rotated or revoked token presented again revokes its whole family, and the installation must be authorized again.

## Uninstall

An administrator can uninstall at any time. Every token of the installation then answers `401` at once, and refreshing answers `invalid_grant`. You receive the [`app/uninstalled`](/build/webhooks/topics) webhook, and forget the installation. A later install is a new installation, with a new secret.

An app can also be suspended by the marketplace. A suspended installation answers `401` and receives no webhook, until it resumes.

## Session tokens

An embedded page runs in an iframe inside the platform. It proves who is using it with a **session token**: a JWT, valid 60 seconds, signed by the platform with RS256. Your page asks the host for one with [App Bridge](/build/app-bridge) and sends it to your own server. Session tokens are never accepted by the App API: they are for your backend only.

| Claim | Meaning |
|---|---|
| `iss` | The API origin of the platform |
| `dest` | The origin of the platform's web app, the one that frames you |
| `aud` | Your `client_id` |
| `sub` | The user, as an identity id. No name, no email, no role |
| `org` | The organization the user is working in |
| `inst` | The installation id |
| `platform` | The platform name |
| `locale` | `fr` or `en` |
| `exp`, `nbf`, `iat`, `jti` | Lifetime: 60 seconds |
| `slot`, `ctx` | In an [extension slot](/build/extension-slots) only: the slot and its context, such as `{ "productId": 345 }` |

To verify a session token on your server:

1. Take the keys from `<apiOrigin>/.well-known/jwks.json`, where `apiOrigin` is the origin you recorded at install. Never take them from the token.
2. Accept RS256 only, and refuse `none` and HS256.
3. Check that `iss` is your recorded API origin, `aud` is your client id and `dest` is your recorded web app origin, and that the token has not expired.
4. Check that `platform` and `inst` are the installation you recorded, and that `org` is one of its organizations: the granted ones and their descendants, as `coveredOrganizationIds` of `GET /api/app/v1/installation` lists them.

The `@foodpilot/app-bridge/server` library does all of this in `verifySessionToken`. The keys are public and cached for five minutes: refetch on an unknown `kid`.

:::warning
A session token tells you who is there, not what they may see. To read data, call the App API with the installation token. And never trust the `platform` and `host` query parameters of your embedded page: they are hints. Only verified claims count.
:::
