Skip to main content
An app is trusted with a merchant’s workspace, so the way that trust is established matters. The good news: the SDK handles all of it, and the model is small enough to hold in your head.

​
The trust model

The platform signs tokens with an Ed25519 private key. Your app verifies them with the platform’s public key only. That asymmetry is the whole point: a hosted app can check that a token is genuine, but it can never forge one — unlike a shared secret, which anyone holding it could mint tokens with. Every token also carries aud — your app’s audience — so a token minted for one app can never be replayed against another. There are two kinds of token:
  • Session — authenticates an embed or storefront request as a workspace. Reusable until it expires (15 minutes).
  • Provision — one-time, server-to-server. It delivers a workspace’s freshly minted API key when the app is installed.
And there’s one golden rule the SDK enforces for you:
The workspace always comes from a verified token — never from the request body or a query parameter.
So a caller can only ever act as the tenant the platform minted the token for. There’s no way to ask your app about someone else’s workspace.

​
The lifecycle

The Install lifecycle guide walks through the provision and uninstall handlers in code.

​
Provisioning is retry-safe

The provision token is one-time — a jti on it blocks replay. But “one-time” has a subtle trap: if your onProvision work fails after the token is spent (a locked database, say), a naive design would strand the workspace forever, because the platform’s retry carries the same, now-spent token. The SDK avoids this. It consumes the jti only after your onProvision succeeds, and releases it on failure. So a transient error just means the platform’s retry works. The starter wires this up for you with a releaseJti hook.

​
Where the SDK draws the line

The security-critical protocol lives in @sentralbee/app-sdk:
  • verifying platform tokens (createTokenVerifier, createSessionAuth, mountInstall),
  • encryption-at-rest for the secrets you store (createCypher),
  • webhook signature verification (verifyWebhookSignature),
  • the authenticated public-API client (sentralbeeClient).
Your app logic and UI live in your own code. The rule of thumb: if it’s crypto or token parsing, call the SDK — don’t reimplement it.

​
Where to next