Design rule
The platform is source of truth, the web app is the control surface, and the extension is a managed client.
The extension should never receive raw user access tokens as steady-state credentials.
Operational sequence for connecting signed-in web sessions, extension installation bind, bootstrap v2, and usage telemetry.
extensionauthbootstrap
Back to docsBefore you start
Connected runtime with API, worker, PostgreSQL, and Redis available.
Authenticated web session through /auth/login.
Extension runtime able to persist installationId locally.
Execution steps
Step 1
Open bridge route with installation handshake plus targetOrigin and bridgeNonce.
Step 2
Proxy bind through the site session and issue installation token.
Step 3
Store installation token and call /extension/bootstrap/v2.
Step 4
Send usage events to /extension/usage-events/v2.
Step 5
Trigger reconnect flow when installation session expires or is revoked.
Context and safeguards
Failure fallback
If postMessage handoff fails, the bridge can issue a one-time redeem code with TTL constraints and nonce/request checks.
This fallback keeps installation binding recoverable without weakening the main origin-restricted delivery path.