Host-asserted Onboard identity

A setup checklist needs to know who is completing steps, and which workspace shared steps belong to. Building a second login just for onboarding is usually wrong when your SaaS already has sessions.

Bootstrapware Onboard does not authenticate end users. Your host app asserts identity on every render:

user={{ id: "opaque-stable-id", name: "Ada" }}
workspaceKey={workspace.id}

Pass the same stable ids you use in your product. Do not invent ids. Do not use user_1 in production.

Fields

Field	Role
user.id	Required. Opaque and stable for the same person across sessions.
user.name	Optional display metadata.
workspaceKey	Scopes shared (workspace) steps. Bind it when minting authorToken.
authorToken	Host-signed assertion from `POST /api/v1/author-tokens` (secret key). Required for live Hosted and when the flow enables `requireAuthorToken`.

Mint from the BFF

const session = await getSession();
const authorToken = await mintOnboardToken({
  authorId: session.user.id,
  flowId: "flw_...",
  workspaceKey: session.workspace.id,
});

<Onboard
  user={{ id: session.user.id, name: session.user.name }}
  workspaceKey={session.workspace.id}
  authorToken={authorToken}
  flowId="flw_..."
  publishableKey={process.env.NEXT_PUBLIC_BSW_ONBOARD_PUBLISHABLE_KEY}
/>

Never mint tokens in the browser. Renew when expiresAt is within about 5 minutes.

Why opacity matters

Prefer internal ids over emails as id. Personal progress is keyed by that string. If the id changes when someone renames their display name, they look like a new person and lose personal completions.

Threat model

Publishable keys may appear in the browser. If a publishable key leaks, a client can forge user.id against Hosted APIs. Mitigate with allowed origins, keep secret keys server-side, enable requireAuthorToken for production Hosted, and treat BYO Route Handlers as the place to re-bind authorship to the real session.

Reference: identity docs.

Related: Identity docs · Security · API keys · Progress