feat: add Anonymous Sessions documentation

main/config/navigation/manage-users.json

@@ -227,6 +227,16 @@
                 "docs/manage-users/sessions/session-metadata/configure-session-metadata",
                 "docs/manage-users/sessions/session-metadata/add-organization-information"
               ]
+            },
+            {
+              "group": "Anonymous Sessions",
+              "pages": [
+                "docs/manage-users/sessions/anonymous-sessions",
+                "docs/manage-users/sessions/anonymous-sessions/quickstart",
+                "docs/manage-users/sessions/anonymous-sessions/transfer-to-users",
+                "docs/manage-users/sessions/anonymous-sessions/claims-mapping",
+                "docs/manage-users/sessions/anonymous-sessions/best-practices"
+              ]
             }
           ]
         },

main/docs/manage-users/sessions/anonymous-sessions.mdx

@@ -0,0 +1,88 @@
+---
+title: Anonymous Sessions
+description: Learn how to create and manage guest user sessions with Anonymous Sessions.
+sidebarTitle: Overview
+---
+
+Create and manage guest user sessions without requiring authentication using Anonymous Sessions. Users can browse, add items to carts or wishlists, complete purchases, and set preferences before creating an account — and carry that activity into their authenticated profile when they sign up or log in.
+
+## How it works
+
+```mermaid actions={false}
+sequenceDiagram
+  participant SPA/APP
+  participant Auth0
+  participant Resource Server
+  note over SPA/APP: User browses a site and you decide<br/> to start storing information about the user.
+  SPA/APP ->> Auth0: POST /anonymous/token
+  Auth0 ->> SPA/APP: Session token, Access token, sub:anon|123
+  SPA/APP ->> Auth0: Post /anonymous/token {language=EN}
+  Auth0 ->> SPA/APP: Session token, Access token, sub:anon|123
+  SPA/APP ->> Auth0: Post /anonymous/token {country=US}
+  Auth0 ->> SPA/APP: Session token, Access token, sub:anon|123
+  note over SPA/APP: User purchases anonymously
+  SPA/APP ->> Resource Server: POST /purchase, Access token
+  Resource Server ->> Resource Server: Purchase PUR_987 complete for user anon|123
+  Resource Server ->> SPA/APP: HTTP 200 Ok
+  SPA/APP ->> Auth0: Post /anonymous/token {purchase=PUR_987}
+  Auth0 ->> SPA/APP: Session token, Access token, sub:anon|123
+```
+
+When you decide to start tracking a user — even one who has not authenticated yet — your application sends a `POST /anonymous/token` request. Auth0 responds with two tokens:
+
+- A **session token** (JWT or JWE) that identifies and persists the anonymous session
+- An **access token** (OAuth 2.0-compliant) that the user can present to your resource servers
+
+Subsequent calls that include the session token continue the same session for the same `user_id`, so all activity is traceable to a single origin. Because the access token is OAuth 2.0-compliant, anonymous users can call any of your existing APIs without additional plumbing.
+
+
+### What Anonymous Sessions provide
+
+- **Track guest users** across page loads and sessions
+- **Store metadata** such as shopping cart references, preferences, consents, and profiling information
+- **Issue OAuth 2.0 access tokens** for API calls without requiring authentication
+- **Transfer anonymous activity** to authenticated accounts when users sign up or log in
+
+## Key concepts
+
+### Session token
+
+The session token is a JWT or JWE that contains:
+
+| Claim | Description |
+| :--- | :--- |
+| `user_id` | Anonymous identifier (for example, `anon\|a7f3b2c9e1`) |
+| `session_id` | Unique session identifier |
+| `created_at` | When the session was created |
+| `metadata` | Application-defined data (cart, preferences, and so on) |
+| `iss` | Token issuer (your Auth0 domain) |
+| `exp` | Expiration timestamp |
+
+### Access token
+
+The access token lets your application call resource server APIs. It contains:
+
+- A `sub` claim that holds the anonymous `user_id`
+- Standard OAuth 2.0 claims: `aud`, `iss`, `exp`, `iat`, `scope`
+
+### Anonymous user ID
+
+Each anonymous user has a unique identifier in UUID format, consistent across all tokens for that session. If you include a `user_id` in the initial session creation call, Auth0 uses it instead of generating one.
+
+### Anonymous session ID
+
+Each anonymous session has its own identifier. The same anonymous user may have more than one session — for example, when a previous session expired, or when you supply your own user IDs.
+
+## Limitations
+
+- Session transfer only occurs during login (Post-Login Action) and sign-up (Pre-Registration Action).
+- Password reset flows do not link anonymous sessions.
+- The following grant types are not supported: Device Code, Client-Initiated Backchannel Authentication (CIBA), custom token exchange, and refresh token exchange.
+- Anonymous sessions are not a secure data store. To learn more, read [Anonymous Sessions Best Practices](/docs/manage-users/sessions/anonymous-sessions/best-practices).
+
+## Learn more
+
+- [Quick Start: Anonymous Sessions](/docs/manage-users/sessions/anonymous-sessions/quickstart) — Configure Anonymous Sessions and create your first session in five steps.
+- [Transfer Anonymous Sessions to Users](/docs/manage-users/sessions/anonymous-sessions/transfer-to-users) — Migrate cart, preference, and activity data when a guest signs up or logs in.
+- [Claims Mapping](/docs/manage-users/sessions/anonymous-sessions/claims-mapping) — Include anonymous session attributes in access tokens without writing Actions code.
+- [Anonymous Sessions Best Practices](/docs/manage-users/sessions/anonymous-sessions/best-practices) — Security, performance, and implementation recommendations.