Skip to main content

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.

  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.
RuleValue
The scope parameterA subset of the scopes of your manifest. Consent shows exactly that parameter.
The redirect_uriOne of the redirect_urls of your manifest, compared exactly.
A codeSingle use, valid 60 seconds. Presenting a used code again revokes the refresh tokens it produced.
What an administrator can grantOnly 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_token is the installation token. Send it as Authorization: Bearer to the 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. 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.

ClaimMeaning
issThe API origin of the platform
destThe origin of the platform's web app, the one that frames you
audYour client_id
subThe user, as an identity id. No name, no email, no role
orgThe organization the user is working in
instThe installation id
platformThe platform name
localefr or en
exp, nbf, iat, jtiLifetime: 60 seconds
slot, ctxIn an extension slot 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.