Install, tokens and session tokens
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.
- The administrator starts the install in the platform. The platform sends the browser to your manifest's
install_url, with?platform=<platform name>. - Your app checks that it knows the platform, then redirects the browser to the platform's consent page,
/admin/oauth/authorize, withclient_id,redirect_uri,scope, astateyou will check, and a PKCE challenge (code_challenge,code_challenge_method=S256). - The administrator reviews the scopes you asked for and chooses the organizations. The platform sends the browser back to your
redirect_uriwithcode,stateandplatform. - Your server checks
state, then callsPOST /oauth/tokenon the platform's API host withgrant_type=authorization_code, yourclient_idandclient_secret, thecode, the sameredirect_uriand the PKCEcode_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
{
"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_tokenis the installation token. Send it asAuthorization: Bearerto the App API, and to nothing else: any other route answers403.refresh_tokenlasts 90 days and is rotated at every use.webhook_secretis sent once, when the installation is first activated. It is the key that signs your webhooks. Store it with the installation.
Errors follow RFC 6749: invalid_request, invalid_client, invalid_grant, unsupported_grant_type, server_error.
Refresh
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 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 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 only: the slot and its context, such as { "productId": 345 } |
To verify a session token on your server:
- Take the keys from
<apiOrigin>/.well-known/jwks.json, whereapiOriginis the origin you recorded at install. Never take them from the token. - Accept RS256 only, and refuse
noneand HS256. - Check that
issis your recorded API origin,audis your client id anddestis your recorded web app origin, and that the token has not expired. - Check that
platformandinstare the installation you recorded, and thatorgis one of its organizations: the granted ones and their descendants, ascoveredOrganizationIdsofGET /api/app/v1/installationlists 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.
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.