Session Architecture & Security
Option B HMAC Signed Identity & Sandboxing
Detailed guide on how Playground API authenticates anonymous visitors, manages persistent session overlays, and enforces IP auto-recovery.
Your Live Session Signed Token FormatHMAC-SHA256 Signed
Format: <UUID>.<HMAC_SIGNATURE>
Active Session Token
1. Cookie & Header Transport Mechanism
The backend sets the pg_identity HTTP cookie automatically. For cross-origin E2E test suites (Playwright, Cypress) or mobile applications where cookies are restricted, pass the header explicitly:
X-Playground-Identity: <your_signed_token>
2. IP Auto-Recovery Fallback
If a client tampers with the HMAC signature or clears cookies, Playground API hashes the client IP address (using salted SHA-256) and automatically recovers the visitor's previous identity session without throwing breaking errors.
3. Virtual Overlay Ordering Rules
- Creates: Newly created sandbox items receive string IDs like
local-<uuid>and are prepended to the top of list queries. - Updates: Modified items retain their exact index position within virtual lists.
- Deletes: Deleted record IDs are filtered out of ID list slices prior to pagination.
- 10-Day Purge: Sessions idle for 10 consecutive days are automatically purged via background cron jobs.