UI States
Make the embedded shell predictable across loading, sizing, expiration, and errors
Build your shell around these states. For the exact session fields, see the session contract and the API reference.
| State | Shell behavior |
|---|---|
| Session loading | Show product-owned loading UI; do not mount an unauthenticated iframe |
| Iframe loading | Keep stable dimensions and show a loading layer |
| Ready | Remove loading on the iframe load event; there is no ready message |
| Sizing | The embed does not report its height; give the iframe fixed or responsive dimensions with sensible bounds |
| Bootstrap expiring | Mount within 60 seconds, before the response expiry |
| Session expiring | Fetch a new URL and remount before the 15-minute session ends |
| Session expired | The embed shows an expired-session screen; remount with a fresh session |
| Access denied | Stop retries and show an account/team access action |
| Network failure | Offer bounded retry without changing team or credential |
A missing, malformed, replayed, expired, or access-denied session renders an explicit error screen inside the iframe — there is no silent fallback. Your shell can rely on that: if the iframe loaded, the embed is either showing the view or telling the user what went wrong.
If the selected team changes, create a new session for that team. Never reuse a token from another team merely because the iframe URL is still open.
Log correlation IDs and structured error codes in your backend diagnostics, but do not expose bootstrap URLs, codes, partner secrets, or bearer tokens in browser telemetry.