From f0aeeebd64c1bf3a310b57083cef7b09823b267c Mon Sep 17 00:00:00 2001
From: Yogesh Chaudhary <yogesh.chaudhary@okta.com>
Date: Sat, 3 Oct 2026 13:27:53 +0530
Subject: [PATCH 1/4] docs(anonymous-sessions): handle session expiry error in
 getTokenSilently example

---
 EXAMPLES.md | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/EXAMPLES.md b/EXAMPLES.md
index 86f6e2dc..53ff9250 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -2216,28 +2216,39 @@ Set `createAnonymousSessionOnFailedSilentAuth` on `Auth0Provider` to automatical
 
 ### Getting an anonymous access token
 
+The SDK returns a cached token when still fresh and renews it when the access token expires. If the session itself is expired or invalid, `getTokenSilently()` throws an `AnonymousSessionError` — catch it and call `createSession()` to start a new session.
+
 ```jsx
 import { useAuth0 } from '@auth0/auth0-react';
+import { AnonymousSessionError } from '@auth0/auth0-spa-js';
 
 function ApiButton() {
   const { anonymous } = useAuth0();
 
   const callApi = async () => {
-    const { accessToken } = await anonymous.getTokenSilently({
-      audience: 'https://api.example.com'
-    });
+    try {
+      const { accessToken } = await anonymous.getTokenSilently({
+        audience: 'https://api.example.com'
+      });
 
-    await fetch('https://api.example.com/data', {
-      headers: { Authorization: `Bearer ${accessToken}` }
-    });
+      await fetch('https://api.example.com/data', {
+        headers: { Authorization: `Bearer ${accessToken}` }
+      });
+    } catch (e) {
+      if (
+        e instanceof AnonymousSessionError &&
+        (e.code === 'session_expired' || e.code === 'invalid_session_token')
+      ) {
+        // Session is permanently gone. Start a new one.
+        await anonymous.createSession();
+      }
+    }
   };
 
   return <button onClick={callApi}>Call API</button>;
 }
 ```
 
-The SDK returns a cached token when still fresh and renews it transparently when expired.
-
 ### Explicit anonymous session creation with metadata
 
 Call `anonymous.createSession()` directly to attach metadata at creation time.

From c0b69ca137fb1387700bc5ee7d241eef8c33a8ae Mon Sep 17 00:00:00 2001
From: Yogesh Chaudhary <yogesh.chaudhary@okta.com>
Date: Sat, 3 Oct 2026 13:30:29 +0530
Subject: [PATCH 2/4] docs: rethrow unhandled errors in anonymous session
 example

---
 EXAMPLES.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/EXAMPLES.md b/EXAMPLES.md
index 53ff9250..a4de0189 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -2241,6 +2241,8 @@ function ApiButton() {
       ) {
         // Session is permanently gone. Start a new one.
         await anonymous.createSession();
+      } else {
+        throw e;
       }
     }
   };

From 048cab98f94c0bfbd68c88cb7bd5c7cddb56deae Mon Sep 17 00:00:00 2001
From: Yogesh Chaudhary <yogesh.chaudhary@okta.com>
Date: Sat, 3 Oct 2026 14:06:25 +0530
Subject: [PATCH 3/4] docs: retry api call after anonymous session recovery in
 example

---
 EXAMPLES.md | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/EXAMPLES.md b/EXAMPLES.md
index a4de0189..7ab2c674 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -2226,25 +2226,29 @@ function ApiButton() {
   const { anonymous } = useAuth0();
 
   const callApi = async () => {
+    let accessToken;
     try {
-      const { accessToken } = await anonymous.getTokenSilently({
+      ({ accessToken } = await anonymous.getTokenSilently({
         audience: 'https://api.example.com'
-      });
-
-      await fetch('https://api.example.com/data', {
-        headers: { Authorization: `Bearer ${accessToken}` }
-      });
+      }));
     } catch (e) {
       if (
         e instanceof AnonymousSessionError &&
         (e.code === 'session_expired' || e.code === 'invalid_session_token')
       ) {
-        // Session is permanently gone. Start a new one.
+        // Session is permanently gone. Start a new one and retry.
         await anonymous.createSession();
+        ({ accessToken } = await anonymous.getTokenSilently({
+          audience: 'https://api.example.com'
+        }));
       } else {
         throw e;
       }
     }
+
+    await fetch('https://api.example.com/data', {
+      headers: { Authorization: `Bearer ${accessToken}` }
+    });
   };
 
   return <button onClick={callApi}>Call API</button>;

From aa2853c878f7dd7d9645a88a048407c6a96144be Mon Sep 17 00:00:00 2001
From: Yogesh Chaudhary <yogesh.chaudhary@okta.com>
Date: Tue, 6 Oct 2026 11:41:50 +0530
Subject: [PATCH 4/4] docs: import AnonymousSessionError from auth0-react
 instead of auth0-spa-js

---
 EXAMPLES.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/EXAMPLES.md b/EXAMPLES.md
index 7ab2c674..4215658c 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -2219,8 +2219,7 @@ Set `createAnonymousSessionOnFailedSilentAuth` on `Auth0Provider` to automatical
 The SDK returns a cached token when still fresh and renews it when the access token expires. If the session itself is expired or invalid, `getTokenSilently()` throws an `AnonymousSessionError` — catch it and call `createSession()` to start a new session.
 
 ```jsx
-import { useAuth0 } from '@auth0/auth0-react';
-import { AnonymousSessionError } from '@auth0/auth0-spa-js';
+import { useAuth0, AnonymousSessionError } from '@auth0/auth0-react';
 
 function ApiButton() {
   const { anonymous } = useAuth0();