# App Bridge

> How an embedded app talks to the platform page that frames it: session tokens, toast, confirm, navigation, title and loading.

Source: https://developers-staging.foodpilot.tech/build/app-bridge

In this page you will learn how an embedded app is opened, how it learns who is using it, and what it can ask of the platform page around it. The `@foodpilot/app-bridge` package implements everything below.

## An embedded app

An app whose [manifest](/build/manifest) has `embedded: true` and an `app_url` appears in the platform's menu, under **Apps**. A user of a granted organization opens it, and the platform shows your page in an iframe under its own header. Your `navigation` entries are the tabs of that page.

The platform loads your `app_url` (or a navigation path under it) with four query parameters:

| Parameter | Value |
|---|---|
| `embedded` | `1` |
| `platform` | The platform name |
| `locale` | `fr` or `en` |
| `host` | The origin of the platform's web app, in base64url (UTF-8, no padding) |

They are hints only: trust what a verified [session token](/build/authentication) says, never these.

The frame is sandboxed: scripts, forms, popups and same-origin are allowed; top navigation and downloads are not. No token is ever put in the URL.

## Secure your pages

- Send `Content-Security-Policy: frame-ancestors <the platform web app origins>` so nobody else can embed your app.
- Do not rely on third-party cookies, which a browser may block inside an iframe: authenticate each request to your server with a session token.
- Serve the app from an origin only you control, not a shared hosting domain.

## The client

```bash
npm install @foodpilot/app-bridge jose
```

```ts

const app = createApp({ allowedHosts: ['https://acme.example.com'] }); // exact origins

await app.ready(); // hides the platform's loading skeleton

const token = await app.getSessionToken(); // 60 seconds
await fetch('/api/me', { headers: { Authorization: `Bearer ${token}` } });

app.toast({ message: 'Saved', kind: 'success' });
const ok = await app.confirm({ message: 'Delete the report?', confirmLabel: 'Delete' });
app.navigate.app('/app/reports/2');
app.navigate.foodpilot('/products');
app.title('Reports');
app.loading(true);
```

`createApp` refuses to start unless the page is framed and the `host` parameter names one of the origins you listed. Requests go to that origin only, and replies are accepted only from the parent window.

## What the host does

| Request | Effect |
|---|---|
| `ready` | Ends the loading state. If it does not come within 15 seconds, the user sees "The app did not respond" with a retry |
| `session-token` | Returns a session token for the user, organization and installation. Cached by the host until 10 seconds before it expires |
| `toast` | A message of at most 200 characters, `info`, `success` or `error`, shown with the app's name |
| `confirm` | A dialog, titled with the app's name, with a message of at most 500 characters and a label of at most 30. Answers whether the user confirmed |
| `navigate` | `app`: a path under your `app_url`. `foodpilot`: only a few areas of the platform, such as `/products` |
| `title` | Sets the page title, at most 100 characters |
| `loading` | Shows or hides a progress bar under the header |
| `resize` | In an [extension slot](/build/extension-slots): sets the frame height |
| `context` | In an extension slot: tells the app its slot and context |

A request the host would refuse never leaves your page: it rejects at once. Messages are `{ "fpab": 1, "id", "type", "payload" }`, at most 8 KB, and the host answers at most 50 messages per second per app. Another request type gets the error `unsupported`.

## On your server

Verify the session token with `verifySessionToken` from `@foodpilot/app-bridge/server`, against what you recorded at install: the API origin, the web app origin, your client id, the platform, the installation and its organizations. See [session tokens](/build/authentication).

```ts

const claims = await verifySessionToken(bearer, {
  apiOrigin: 'https://api.acme.example.com',
  appOrigin: 'https://app.acme.example.com',
  clientId: process.env.CLIENT_ID,
  platform: 'acme',
  installationId: '0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b',
  organizationIds: [7, 9, 12], // coveredOrganizationIds of GET /api/app/v1/installation
});
```

A token lives 60 seconds and may be replayed within it. When one authorizes a change, remember its `jti` and refuse a second use.
