Embedded apps

An embedded app (app_type: embedded) renders its UI inside the PlatformDTC dashboard at /apps/installed/<your-handle>. The dashboard loads your embedded_app_url in an iframe and talks to it through App Bridge, a small script served from the PlatformDTC CDN, over an origin-locked postMessage channel. If you have built a Shopify embedded app, the model is the same: short-lived session tokens authenticate your frontend to your backend, and token exchange gives your backend the install’s offline access token without any redirect after install.

How your app is loaded

<embedded_app_url>?host=<base64url("platformdtc.com/store/<store_id>")>&shop=<store host>&id_token=<session token>

Param	Meaning
`host`	Identifies the admin. App Bridge decodes it to the only origin it will talk to.
`shop`	The store’s public host, e.g. `acme.com`.
`id_token`	A session token. Verify it before trusting `shop`.

The iframe is sandboxed without top-level navigation: to send the merchant elsewhere in the dashboard, use app.navigation.redirectToAdmin(). Your embedded_app_url must be https.

Set up App Bridge

App Bridge is an ES module on the PlatformDTC CDN. Nothing to install: load it by URL, the way Shopify apps load App Bridge from cdn.shopify.com.

URL	Use
`https://cdn.platformdtc.com/app-bridge/v1/app-bridge.js`	Use this. Always the latest 1.x; compatible fixes reach your app without a redeploy.
`https://cdn.platformdtc.com/app-bridge/v1/app-bridge.d.ts`	TypeScript types for your editor.
`https://cdn.platformdtc.com/app-bridge/<version>/app-bridge.js`	One exact release (e.g. `1.0.0`), never changed.

Map the module name in an import map on your embedded page, then import it from your own scripts:

<script type="importmap">
  { "imports": { "@platformdtc/app-bridge": "https://cdn.platformdtc.com/app-bridge/v1/app-bridge.js" } }
</script>
<script type="module" src="/app.js"></script>

Or import the URL directly: import { createApp } from 'https://cdn.platformdtc.com/app-bridge/v1/app-bridge.js';. If your page sends a Content-Security-Policy, allow https://cdn.platformdtc.com in script-src (and the import map’s hash, if it is inline). The dtc app init starter does both.

import { createApp, authenticatedFetch } from '@platformdtc/app-bridge';

const app = createApp({ clientId: 'sq_app_…' });
const fetch = authenticatedFetch(app); // adds Authorization: Bearer <session token>

const res = await fetch('/api/reviews');

API	What it does
`app.idToken()`	A fresh 60-second session token (cached until 10s before expiry).
`app.toast.show(message, { duration, isError, action, onAction, onDismiss })`	A toast in the admin.
`app.modal.show({ title, message, primaryAction, secondaryActions, onHide })`	An admin modal. Text only.
`app.saveBar.show(id, { onSave, onDiscard, loading })` / `hide(id)`	The save bar. While it shows, leaving the page asks the merchant to confirm.
`app.saveBar.leaveConfirmation()`	Ask the merchant to confirm discarding changes; resolves `true` to leave.
`app.resourcePicker({ type, multiple, selectionIds })`	The dashboard’s picker for `product`, `collection` or `customer`. Resolves the selection, or `undefined` if cancelled.
`app.navigation.push(path)` / `replace(path)`	Sync your route into the admin URL (automatic for `history.pushState`).
`app.navigation.onNavigate(handler)`	Handle admin navigation (sidebar links, back/forward).
`app.navigation.redirectToAdmin('/orders')`	Leave the app for a dashboard page.
`app.loading(true)` / `app.title('…')`	Admin loading bar and page title.

Paths are relative to your embedded_app_url’s origin. /embedded/settings shows in the admin as /apps/installed/<handle>/embedded/settings. Reloading that URL reopens your iframe on https://<your origin>/embedded/settings. Declare nav_links on an app version. They appear in the merchant’s sidebar under your app while it is open. Like scopes, they are part of the version and go through review.

{
  "nav_links": [
    { "label": "Reviews", "destination": "/embedded" },
    { "label": "Settings", "destination": "/embedded/settings" }
  ]
}

A destination must start with /. You can declare up to 20 links, each label up to 64 characters.

Session tokens

App Bridge gets a session token from the dashboard for each idToken() call. It is an HS256 JWT signed with your client secret and expires 60 seconds after it is issued.

Claim	Value
`iss`	`https://platformdtc.com`
`dest`	`https://<store host>`
`aud`	Your `client_id`
`sub`	The merchant user’s account id
`sid`	The install id
`exp`, `nbf`, `iat`	60-second lifetime
`jti`	Unique token id

Verify every request on your backend. Check the signature, aud, iss, exp and nbf, and allow about 10 seconds of clock skew. Reject a failure with 401. To have App Bridge retry once with a fresh token, also send the header X-PlatformDTC-Retry-Invalid-Session-Request: 1.

import { jwtVerify } from 'jose';

const { payload } = await jwtVerify(token, new TextEncoder().encode(CLIENT_SECRET), {
  algorithms: ['HS256'],
  issuer: 'https://platformdtc.com',
  audience: CLIENT_ID,
  clockTolerance: 10,
});

claims := jwt.MapClaims{}
_, err := jwt.ParseWithClaims(token, claims,
    func(*jwt.Token) (any, error) { return []byte(clientSecret), nil },
    jwt.WithValidMethods([]string{"HS256"}),
    jwt.WithIssuer("https://platformdtc.com"),
    jwt.WithAudience(clientID),
    jwt.WithLeeway(10*time.Second))

claims = jwt.decode(token, CLIENT_SECRET, algorithms=["HS256"],
                    audience=CLIENT_ID, issuer="https://platformdtc.com", leeway=10)

Token exchange

Your backend swaps a session token for the install’s offline sq_agt_* token (RFC 8693). No redirect is needed after install.

curl -X POST https://api.platformdtc.com/api/v1/appstore/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET \
  -d subject_token=$SESSION_TOKEN \
  -d subject_token_type=urn:ietf:params:oauth:token-type:id_token \
  -d requested_token_type=urn:platformdtc:params:oauth:token-type:offline-access-token

{
  "access_token": "sq_agt_…",
  "token_type": "bearer",
  "issued_token_type": "urn:platformdtc:params:oauth:token-type:offline-access-token",
  "scope": "catalog:read orders:read",
  "install_id": "…"
}

The dated route POST /api/v1/appstore/2026-08/oauth/token accepts the same grant.

Every exchange issues a new token and retires the previous one. Offline tokens are stored only as hashes, so the platform cannot return a token it issued earlier. The retired token keeps working for 15 minutes so in-flight requests finish, then stops. Exchange once, store the token against install_id, and exchange again only when you have no token or it returns 401.

Rules the token endpoint enforces:

Each session token can be exchanged once (its jti).
The session’s install must belong to your app and be installed. A pending_reauth install needs the merchant to reauthorize first.
Only embedded apps can use this grant. Online (per-user) tokens are not supported.
After you rotate your client secret, authenticate with either secret during the 72-hour grace window. Session tokens are signed with the new secret straight away.

Error	Meaning
`invalid_subject_token`	The session token is expired, forged, already used, or for another app. Get a fresh `idToken()` and retry.
`invalid_client` (401)	Unknown `client_id` or wrong `client_secret`.
`invalid_grant`	The install is not installed, or not yours.
`unauthorized_client`	The app is not active, or not an embedded app.
`invalid_request`	A required parameter is missing or has the wrong type URN.
`temporarily_unavailable` (503)	Retry with backoff.

Uninstalling revokes every token issued for the install, retired ones included.

Security model

App Bridge posts only to the admin origin decoded from host. It accepts messages only from that origin and from its parent window.
The dashboard accepts messages only from your embedded_app_url origin and your iframe, and replies only to that origin.
The offline token never passes through postMessage or the browser.
Text you send (toasts, modal content, labels, titles) is shown as plain text and truncated.

Build an App

How your app is loaded

Set up App Bridge

Admin navigation

Session tokens

Token exchange

Security model

​How your app is loaded

​Set up App Bridge

​Admin navigation

​Session tokens

​Token exchange

​Security model

How your app is loaded

Set up App Bridge

Admin navigation

Session tokens

Token exchange

Security model