| name | embed-and-auth |
| description | The host-owned-identity auth model for an app embedded in a platform's back-office surface, and how to authenticate every request. Use when adding or changing an authenticated API route, a client-side data fetch, the token handshake, the embed entry route, iframe/CSP headers, or when debugging 401s, a blank embed, or "token" problems. Explains why the app is a token-gated client SPA (no cookies, no SSR data fetching, library-owned verification) and how to reach the platform server-side WITHOUT a user token — install/tenant-scoped from a persisted install id — for public pages, webhooks, and cron. Triggers on "add an API route", "authenticate a request", "iframe won't load", "401 in the embed", "call the platform from a public page", "call the platform without a user token", "background/cron access". |
Embed & auth — the host owns identity
An app built on this kit runs as a client-side SPA embedded in the platform's back-office
surface (typically an iframe). It has no sessions, no cookies, and no server-rendered
authenticated data. Every authenticated request rides a short-lived, signed identity token that
the platform hands to the app in the browser. This skill is the map of that model and the recipe
for extending it. Peek Pro is the canonical example — its concrete pipeline lives in
peek-embed-and-auth.
The one mental model: the identity token only exists in the browser
The host (the platform surface embedding your app) hands the acting user's identity to the app
as a short-lived signed token, delivered to the browser — there is no server-side copy.
That single fact explains every constraint:
- No cookies, no redirect-carry. Third-party cookie blocking kills them in an embedded frame.
The token can't be persisted in a cookie or carried across a redirect. → The app receives the
token in the client, holds it in memory, and sends it as a
Bearer header instead.
- No SSR / server-component data fetching of authed data. At render time on the server, no
token exists, so a server component has nothing authenticated to fetch. → Embedded views render
client-side and fetch after a token gate. This is not the "fetch-on-mount instead of
server components" anti-pattern; there is no server alternative here — the token gate, not
preference, forces client rendering.
- Verification is library-owned. Routes never hand-decode the token. They delegate to the
platform SDK, constructed from the app's secret. Never hand-decode or hand-verify.
This is about the acting user's identity — that, and only that, is browser-only. It does
not mean you can't call the platform without a user token. You can, install/tenant-scoped, from
any server context that has a persisted install id — see
Server-to-host without a user token below.
The host owns the chrome, not just identity
The same "the host owns it" logic extends past the token to the surrounding UI. The host frames
your app — it renders the app's name, navigation, breadcrumbs, and window chrome outside the
iframe. Your embedded views render only the app's own content.
- Don't render an app-name header or title bar inside the embed. The host already shows which
app the user is in, around the frame. A second title inside the iframe is redundant chrome that
pushes your real UI down and reads as non-native. Open straight into what the app does — the
first thing in the frame is the app's actual content and controls.
- This applies to the embedded surface specifically. A separate developer/admin surface you own
(rendered outside the host) is yours to chrome however you like.
The concrete layout conventions for building this are stack-specific — on the JS stack see
javascript-odyssey-ui.
The request lifecycle (end to end)
1. The host delivers the signed identity token to the browser (not to your server).
2. The embedded app boots as a client SPA and OBTAINS the token from the host
(e.g. the parent frame hands it over on request).
3. The app CACHES the token in memory and renders the view only AFTER it arrives (the "ready" gate).
4. Each data call goes to an API route with the token as a Bearer header.
5. The route VERIFIES the token (library-owned) and builds an install/tenant-scoped platform client.
6. On a 401, the client requests a FRESH token via the SAME channel and RETRIES once.
The concrete delivery mechanism (how the host posts the token, the message names, the header name,
the entry route that converts the host's POST into the client view) is platform + stack specific —
see peek-embed-and-auth for the canonical postMessage/JWT pipeline and javascript-nextjs for
the route-handler / client-SPA mechanics.
Why the embed entry route often throws the token away. The host may deliver the token to a
POST entry route, but that route typically can't render the SPA and the token can't survive a
redirect (no cookies) — so the entry route just converts the host's POST into the client view and
does not authenticate. Real auth happens per-API-request (step 5). Don't add verification to
the entry route.
Server-to-host without a user token
The pipeline above is one of two ways to reach the platform — the one that carries the acting
user's identity. But you do not need a user token to call the platform at all.
The platform SDK client mints its own API credentials from an install/tenant identifier + the
app secret. The user identity token is not a platform API credential — it's just how the
browser tells the server which install is acting. So any install/tenant id you have persisted
lets you build a fully functional, scoped platform client server-side, with no user token and no
browser in the loop.
That is the load-bearing fact behind every non-embedded server path:
- Public (non-embedded) pages — a customer-facing page with no embed and no user token that
still needs to read/write platform data (e.g. a public waitlist page reconciling into the
platform).
- Webhooks — a platform → your-endpoint delivery carries the install id; act on it immediately
(see
webhooks).
- Cron / background jobs / reconciliation — iterate persisted installs and sync each on a
schedule, with no request in flight at all.
Where the install id comes from: you persist it during the app's lifecycle — from an
install/webhook registration, or captured from a verified user token during an embedded session —
and store it against your own records. It is not secret and not a credential on its own; it's only
useful combined with the app secret, which never leaves the server.
Guardrail. This bypasses user-identity checks by design, so the install/tenant id must come
from a trusted server-side source (your DB, a verified webhook) — never from a query param
or request body a caller can forge, which would let anyone act on any install. The browser-token
pipeline is still correct for embedded API routes: it proves which install the live user
belongs to. Use the install-scoped path only where there is no live user. See peek-backoffice-api
for the canonical createPeekServiceForInstall recipe.
Two IDs, two jobs — don't conflate them
There are two distinct identifiers, and mixing them causes real bugs:
- An install/tenant identifier — identifies the install for API auth. It comes from the
verified token (or from your persistence, for the server-to-host paths above). This is the only
thing you build the platform client from.
- A data-scoping key — the stable key you scope your own stored data by. On most platforms
this is not something the token hands you: you derive it (get-or-create) from the install
identifier and persist it, so that a reinstall doesn't inherit stale data. Don't reach for it as
if it were a token claim.
Different values, different sources. Build the platform client from the install identifier; scope
your storage by the derived data-scoping key. See backoffice-data for how the data-scoping key is
derived and why keying storage on a raw install id is a trap.
Make auth failures diagnosable: 500 for misconfig, 401 for a bad token
The most dangerous auth bug is collapsing two different failure modes into one response. It has
bitten a real deploy: when the app's secret/config env vars were misconfigured, config parsing threw
inside token verification, a bare catch swallowed it, and every route returned a naked 401 with
zero signal — indistinguishable from a genuine bad token. The "app isn't working" hunt was slow
purely because a server misconfig masqueraded as an auth failure. Split them:
- Config / secret error (env parsing threw — a missing/invalid app secret, app id, …): the
deploy is broken, not the caller. Return 500 and log loudly. A 500 tells you instantly "fix
the environment," not "the token is bad." Do this outside the verify try/catch so a config
throw can't be laundered into a 401.
- Token verification failure (expired, wrong signature, wrong issuer): the caller's token is
bad. Return 401, and log the reason so it's greppable — distinct from the 500 above.
The same split applies anywhere you construct a client from env, including the server-to-host
paths (a config throw there is a 500/alerting condition, not a client error).
Logging discipline: log the reason string only. Never log the raw token (it's a live
credential) and never log the decoded claims (they carry user PII). The config-parse message
(naming the offending var, not its value) and the library's verify error ("jwt expired",
"invalid signature") are both reason-only and safe. See peek-embed-and-auth for the concrete
implementation.
Hard rules (violating these breaks the embed silently)
- Never suggest cookies for the token, or any redirect-based token carry. They're blocked in
third-party embedded frames.
- Never verify the token by hand. Delegate to the platform SDK. Build the client from the
verified token's claims (install-scoped), not from static values.
- Never add SSR/server-component data fetching to an embedded view. No token exists at server
render time. Keep embed views client-rendered and fetch after the gate.
- One token requester per mounted subtree. Multiple listeners race and double-request the host.
Reuse one shared channel; the 401-refresh path is the same single channel, not a second
bootstrap.
- Keep the embed's frame-ancestors/CSP headers so the platform can embed the app (and drop any
X-Frame-Options: DENY the framework might add). The concrete header is stack-specific — see
javascript-nextjs.
- Never let a config error surface as a 401. A config/secret parse throw is a misconfigured
deploy — return 500 and log it; only a failed token verification is a 401. Log the failure
reason, never the token or the decoded claims (PII).
- The install/tenant id for server-side calls must come from a trusted server source — never a
forgeable request param.
- Don't add your own app-name header/title bar to an embedded view. The host renders the app's
name and navigation outside the iframe; the embed shows only the app's own content — go straight
into the function. (A separate admin surface you own may have its own chrome.)
Related skills
peek-embed-and-auth — the canonical concrete pipeline: the peek-auth JWT, the postMessage
handshake, the POST→redirect→SPA entry route, PeekAccessService, and the exact token claims.javascript-nextjs — the stack mechanics: the route handler, the client SPA and token gate, and
the iframe/CSP config.backoffice-data — what the authenticated client can do once you have it, plus ID normalization,
the derived per-install data-scoping key, and PII rules.webhooks — the other inbound path (platform → your endpoint); different auth model (you verify
the delivery signature, not a user token).manifest-and-deploy — where the embed URL is declared and how the app secret is provisioned.
