From dd7764bf53cb1825535254448139d8c40c343236 Mon Sep 17 00:00:00 2001
From: Tushar Pandey <tushar.pandey@okta.com>
Date: Mon, 17 Nov 2025 20:12:50 +0530
Subject: [PATCH] docs: add docs for silent auth

---
 EXAMPLES.md           | 41 +++++++++++++++++++++++++++++++++++++++++
 V4_MIGRATION_GUIDE.md |  3 +++
 2 files changed, 44 insertions(+)

diff --git a/EXAMPLES.md b/EXAMPLES.md
index cd7cff7f..a3c354f0 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -40,6 +40,7 @@
     - [Usage Example](#usage-example)
     - [Token Management Best Practices](#token-management-best-practices)
   - [Mitigating Token Expiration Race Conditions in Latency-Sensitive Operations](#mitigating-token-expiration-race-conditions-in-latency-sensitive-operations)
+- [Silent authentication](#silent-authentication)
 - [DPoP (Demonstrating Proof-of-Possession)](#dpop-demonstrating-proof-of-possession)
   - [What is DPoP?](#what-is-dpop)
   - [Basic DPoP Setup](#basic-dpop-setup)
@@ -1065,6 +1066,46 @@ This ensures that the token you send is guaranteed to be valid for at least the
 > [!IMPORTANT]
 > This strategy is **not** a solution for long-running operations that take longer than the token's total validity period (e.g., 10 minutes). In those cases, the token will still expire mid-operation. The correct approach for long-running tasks is to call `getAccessToken()` immediately before the operation that requires it, ensuring you have a fresh token. The buffer is only for mitigating latency-related failures in short-lived requests.
 
+## Silent authentication
+
+Silent authentication checks for an existing Auth0 session without user interaction. Use `prompt: 'none'` as an authorization parameter.
+
+**Custom route:**
+
+```typescript
+// app/api/auth/silent/route.ts
+import { auth0 } from '@/lib/auth0';
+import { NextRequest } from 'next/server';
+
+export const GET = async (req: NextRequest) => {
+  return auth0.startInteractiveLogin({
+    authorizationParameters: { prompt: 'none' },
+    returnTo: req.nextUrl.searchParams.get('returnTo') || '/'
+  });
+};
+```
+
+**Built-in route with query param:**
+
+```html
+<a href="/auth/login?prompt=none">Silent Auth</a>
+```
+
+**Error handling:**
+
+Auth0 returns `login_required` when no active session exists. Handle gracefully:
+
+```typescript
+try {
+  return await auth0.startInteractiveLogin({
+    authorizationParameters: { prompt: 'none' }
+  });
+} catch (error) {
+  // Redirect to interactive login
+  return NextResponse.redirect('/auth/login');
+}
+```
+
 ## DPoP (Demonstrating Proof-of-Possession)
 
 DPoP is an OAuth 2.0 extension that enhances security by binding access tokens to a client's private key. This prevents token theft and replay attacks by requiring cryptographic proof that the client possessing the token also possesses the private key used to request it.
diff --git a/V4_MIGRATION_GUIDE.md b/V4_MIGRATION_GUIDE.md
index 0050f755..eae07fdf 100644
--- a/V4_MIGRATION_GUIDE.md
+++ b/V4_MIGRATION_GUIDE.md
@@ -233,6 +233,9 @@ export const auth0 = new Auth0Client({
 
 Read more about [passing authorization parameters](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#passing-authorization-parameters).
 
+> [!NOTE]
+> In previous versions, `authParams` was used. In v4, use `authorizationParameters`. For example, for silent authentication: `authorizationParameters: { prompt: 'none' }`.
+
 ## ID token claims
 
 In v3, any claims added to the ID token were automatically propagated to the `user` object in the session. This resulted in the large cookies that exceeded browser limits.