Launch session model

Launch is server-to-server first, browser second.

Launch flow

1. operator backend calls POST /api/operator/launch
2. OpenPoly resolves the allowed host and verifies the selected product is enabled (opinion when omitted)
3. OpenPoly upserts the operator user by external_user_id
4. OpenPoly creates the host-bound launch token hash and expiry
5. OpenPoly returns launch_url
6. operator redirects user to launch_url
7. Mini App redeems token and establishes session
8. browser URL drops one-time token after redemption

Token properties

• default TTL: 60 seconds
• minimum TTL: 30 seconds
• single-use
• stored hash-only
• repeated launch calls can mint new token for same operator user
• redemption atomically claims the token and creates one session; concurrent requests cannot create multiple sessions from one token
• an expired or already-used token returns 401 INVALID_LAUNCH_TOKEN, including when it expires or is consumed after the initial lookup
• if session creation fails, the token claim rolls back; unexpected database failures remain server errors
• after a rejected redemption, request a fresh launch URL from the operator backend rather than replaying the same token

Host binding

Launch host must match operator-allowed host resolution.

Inputs:

• requested host from launch API body, if provided
• operator host mapping
• environment fallback host

Result:

• launch URL points to allowed host only
• wrong-host token usage must fail
• a requested host must be an active domain registered for this operator; without one, the default active domain is preferred before the environment fallback

Session semantics

After token redemption:

• browser gets Mini App session cookie
• browser gets CSRF cookie
• operator backend is no longer in request path for ordinary in-app navigation
• product enablement is rechecked during redemption; a previously minted URL does not bypass a product disable

Session is for Mini App client. Operator API key stays server-side only.

Operator user model

• external_user_id unique per operator
• user is upserted on launch
• simultaneous launches for the same operator and external_user_id reuse one linked user; identity creation is serialized before the first lookup
• display name and locale can be snapshotted
• metadata can be attached from operator backend
• caller metadata cannot turn a normal user into a simulator user; simulator routing is provisioned through staging tools

Operator responsibilities

• create launch from trusted backend only
• never mint launch from browser
• use stable external_user_id
• keep redirect flow short enough that token does not expire