Session lifecycle
Two token layers — the channel session (~12h) and the auto-refreshing identity — plus recommended partner behavior.
When a referral link opens successfully, the Shop establishes two independent token layers. Both live in httpOnly, secure, sameSite=none, partitioned (CHIPS) cookies — JavaScript cannot read them, so partners neither need to nor can manage tokens themselves.
| Layer | Contents | Lifetime | Refresh |
|---|---|---|---|
| Channel session | Binds the document to the right sale channel (the source of all pricing & payment methods) | Per expires_in at mint, default 12 hours | No auto-renewal — reopen the referral link when it expires |
| Identity | Access token + refresh token of the signed-in user | Per the JWT exp | Refreshed transparently via the refresh token, never exposed |
Identity tokens refresh automatically in the background while the refresh token is valid — a signed-in user is not logged out mid-session. The channel session does not auto-renew.
Recommended partner behavior
Always use a fresh link
Open the Shop with a freshly generated referral link every time the user enters the Shop surface in your app. Don't cache the link or rely on a session persisting across app launches — the signature lives ~5 minutes and the channel session only ~12 hours.
For signed links (WebView), mint sign immediately before opening — see Authentication.
Cross-site iframe note
Because the iframe runs cross-site, cookies must be CHIPS (sameSite=none; secure; partitioned). Consequences:
- Sessions do not carry across providers, nor between the iframe and a top-level tab — by white-label design.
- A reload inside the iframe keeps the channel session; but if the browser blocks storage (e.g. Safari private), a reload can lose context — the parent should reload the
srcthat contains theslug.
Roadmap
A shop.auth_expired event (postMessage for iframe, JS bridge for WebView) will let the partner host reopen the referral link with no user-visible interruption. Not yet committed.