From d341a8ee7445735e8f71cdc4d7aeb1d0544fcbd7 Mon Sep 17 00:00:00 2001
From: Jeff Escalante <jescalan@users.noreply.github.com>
Date: Mon, 1 Jun 2026 18:25:18 -0500
Subject: [PATCH 1/7] Add custom OAuth consent security guide

---
 .../oauth-consent-custom-flow-examples.mdx    | 444 ++++++++++++++++++
 .../components/oauth-consent-examples.mdx     | 138 ++++++
 .../oauth/custom-consent-page.mdx             | 154 ++++++
 .../oauth/how-clerk-implements-oauth.mdx      |   2 +
 .../auth-strategies/oauth/scoped-access.mdx   |   2 +
 docs/manifest.json                            |   4 +
 .../authentication/oauth-consent.mdx          |  25 +-
 docs/reference/hooks/use-oauth-consent.mdx    | 128 +++--
 8 files changed, 838 insertions(+), 59 deletions(-)
 create mode 100644 docs/_partials/components/oauth-consent-custom-flow-examples.mdx
 create mode 100644 docs/_partials/components/oauth-consent-examples.mdx
 create mode 100644 docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx

diff --git a/docs/_partials/components/oauth-consent-custom-flow-examples.mdx b/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
new file mode 100644
index 0000000000..e27534389a
--- /dev/null
+++ b/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
@@ -0,0 +1,444 @@
+<Tabs items={["Next.js", "React", "React Router", "TanStack React Start"]}>
+  <Tab>
+    ```tsx {{ filename: 'app/oauth-consent/custom-consent-form.tsx' }}
+    'use client'
+
+    import { useClerk, useOAuthConsent } from '@clerk/nextjs'
+    import { useSearchParams } from 'next/navigation'
+
+    function getRedirectHostname(redirectUri: string) {
+      try {
+        return new URL(redirectUri).hostname
+      } catch {
+        return ''
+      }
+    }
+
+    export function CustomConsentForm() {
+      const clerk = useClerk()
+      const searchParams = useSearchParams()
+
+      const clientId = searchParams.get('client_id') ?? ''
+      const redirectUri = searchParams.get('redirect_uri') ?? ''
+      const scope = searchParams.get('scope') ?? undefined
+      const redirectHostname = getRedirectHostname(redirectUri)
+
+      const { data, isLoading, error } = useOAuthConsent({
+        oauthClientId: clientId,
+        scope,
+      })
+
+      if (!clientId || !redirectUri) {
+        return <p>Missing OAuth consent parameters.</p>
+      }
+
+      if (isLoading) {
+        return <p>Loading consent request...</p>
+      }
+
+      if (error || !data) {
+        return <p>Unable to load consent request.</p>
+      }
+
+      return (
+        <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
+          <h1>{data.oauthApplicationName} wants access to your account</h1>
+
+          {data.oauthApplicationLogoUrl && (
+            <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
+          )}
+
+          {data.oauthApplicationUrl && (
+            <p>
+              Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
+            </p>
+          )}
+          <p>
+            Client ID: <code>{data.clientId}</code>
+          </p>
+
+          <p>
+            Review the requested permissions before continuing. After you allow or deny access, you will
+            be redirected to <strong>{redirectHostname}</strong>.
+          </p>
+
+          <details>
+            <summary>View full redirect URL</summary>
+            <code>{redirectUri}</code>
+          </details>
+
+          <ul>
+            {data.scopes.map((scope) => (
+              <li key={scope.scope}>{scope.description || scope.scope}</li>
+            ))}
+          </ul>
+
+          {/* Forward the original OAuth parameters, except fields set by this form. */}
+          {Array.from(searchParams.entries())
+            .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+            .map(([key, value], index) => (
+              <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+            ))}
+
+          <button type="submit" name="consented" value="false">
+            Deny
+          </button>
+          <button type="submit" name="consented" value="true">
+            Allow
+          </button>
+        </form>
+      )
+    }
+    ```
+
+    ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
+    import { Show } from '@clerk/nextjs'
+    import { Suspense } from 'react'
+    import { CustomConsentForm } from './custom-consent-form'
+
+    export const metadata = {
+      referrer: 'strict-origin-when-cross-origin',
+    }
+
+    export default function OAuthConsentPage() {
+      return (
+        <Show when="signed-in">
+          <Suspense fallback={<p>Loading consent request...</p>}>
+            <CustomConsentForm />
+          </Suspense>
+        </Show>
+      )
+    }
+    ```
+  </Tab>
+
+  <Tab>
+    ```tsx {{ filename: 'src/OAuthConsentPage.tsx' }}
+    import { Show, useClerk, useOAuthConsent } from '@clerk/react'
+
+    function getConsentSearchParams() {
+      if (typeof window === 'undefined') {
+        return new URLSearchParams()
+      }
+
+      return new URLSearchParams(window.location.search)
+    }
+
+    function getRedirectHostname(redirectUri: string) {
+      try {
+        return new URL(redirectUri).hostname
+      } catch {
+        return ''
+      }
+    }
+
+    function CustomConsentForm() {
+      const clerk = useClerk()
+      const searchParams = getConsentSearchParams()
+
+      const clientId = searchParams.get('client_id') ?? ''
+      const redirectUri = searchParams.get('redirect_uri') ?? ''
+      const scope = searchParams.get('scope') ?? undefined
+      const redirectHostname = getRedirectHostname(redirectUri)
+
+      const { data, isLoading, error } = useOAuthConsent({
+        oauthClientId: clientId,
+        scope,
+      })
+
+      if (!clientId || !redirectUri) {
+        return <p>Missing OAuth consent parameters.</p>
+      }
+
+      if (isLoading) {
+        return <p>Loading consent request...</p>
+      }
+
+      if (error || !data) {
+        return <p>Unable to load consent request.</p>
+      }
+
+      return (
+        <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
+          <h1>{data.oauthApplicationName} wants access to your account</h1>
+
+          {data.oauthApplicationLogoUrl && (
+            <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
+          )}
+
+          {data.oauthApplicationUrl && (
+            <p>
+              Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
+            </p>
+          )}
+          <p>
+            Client ID: <code>{data.clientId}</code>
+          </p>
+
+          <p>
+            Review the requested permissions before continuing. After you allow or deny access, you will
+            be redirected to <strong>{redirectHostname}</strong>.
+          </p>
+
+          <details>
+            <summary>View full redirect URL</summary>
+            <code>{redirectUri}</code>
+          </details>
+
+          <ul>
+            {data.scopes.map((scope) => (
+              <li key={scope.scope}>{scope.description || scope.scope}</li>
+            ))}
+          </ul>
+
+          {/* Forward the original OAuth parameters, except fields set by this form. */}
+          {Array.from(searchParams.entries())
+            .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+            .map(([key, value], index) => (
+              <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+            ))}
+
+          <button type="submit" name="consented" value="false">
+            Deny
+          </button>
+          <button type="submit" name="consented" value="true">
+            Allow
+          </button>
+        </form>
+      )
+    }
+
+    export function OAuthConsentPage() {
+      return (
+        <Show when="signed-in">
+          <CustomConsentForm />
+        </Show>
+      )
+    }
+    ```
+
+    ```html {{ filename: 'index.html' }}
+    <meta name="referrer" content="strict-origin-when-cross-origin" />
+    ```
+  </Tab>
+
+  <Tab>
+    ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+    import type { Route } from './+types/oauth-consent'
+    import { Show, useClerk, useOAuthConsent } from '@clerk/react-router'
+    import { useLocation } from 'react-router'
+
+    export const meta: Route.MetaFunction = () => [
+      {
+        name: 'referrer',
+        content: 'strict-origin-when-cross-origin',
+      },
+    ]
+
+    function getRedirectHostname(redirectUri: string) {
+      try {
+        return new URL(redirectUri).hostname
+      } catch {
+        return ''
+      }
+    }
+
+    function CustomConsentForm() {
+      const clerk = useClerk()
+      const { search } = useLocation()
+      const searchParams = new URLSearchParams(search)
+
+      const clientId = searchParams.get('client_id') ?? ''
+      const redirectUri = searchParams.get('redirect_uri') ?? ''
+      const scope = searchParams.get('scope') ?? undefined
+      const redirectHostname = getRedirectHostname(redirectUri)
+
+      const { data, isLoading, error } = useOAuthConsent({
+        oauthClientId: clientId,
+        scope,
+      })
+
+      if (!clientId || !redirectUri) {
+        return <p>Missing OAuth consent parameters.</p>
+      }
+
+      if (isLoading) {
+        return <p>Loading consent request...</p>
+      }
+
+      if (error || !data) {
+        return <p>Unable to load consent request.</p>
+      }
+
+      return (
+        <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
+          <h1>{data.oauthApplicationName} wants access to your account</h1>
+
+          {data.oauthApplicationLogoUrl && (
+            <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
+          )}
+
+          {data.oauthApplicationUrl && (
+            <p>
+              Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
+            </p>
+          )}
+          <p>
+            Client ID: <code>{data.clientId}</code>
+          </p>
+
+          <p>
+            Review the requested permissions before continuing. After you allow or deny access, you will
+            be redirected to <strong>{redirectHostname}</strong>.
+          </p>
+
+          <details>
+            <summary>View full redirect URL</summary>
+            <code>{redirectUri}</code>
+          </details>
+
+          <ul>
+            {data.scopes.map((scope) => (
+              <li key={scope.scope}>{scope.description || scope.scope}</li>
+            ))}
+          </ul>
+
+          {/* Forward the original OAuth parameters, except fields set by this form. */}
+          {Array.from(searchParams.entries())
+            .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+            .map(([key, value], index) => (
+              <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+            ))}
+
+          <button type="submit" name="consented" value="false">
+            Deny
+          </button>
+          <button type="submit" name="consented" value="true">
+            Allow
+          </button>
+        </form>
+      )
+    }
+
+    export default function OAuthConsentPage() {
+      return (
+        <Show when="signed-in">
+          <CustomConsentForm />
+        </Show>
+      )
+    }
+    ```
+  </Tab>
+
+  <Tab>
+    ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+    import { Show, useClerk, useOAuthConsent } from '@clerk/tanstack-react-start'
+    import { createFileRoute, useLocation } from '@tanstack/react-router'
+
+    export const Route = createFileRoute('/oauth-consent')({
+      head: () => ({
+        meta: [
+          {
+            name: 'referrer',
+            content: 'strict-origin-when-cross-origin',
+          },
+        ],
+      }),
+      component: OAuthConsentPage,
+    })
+
+    function getRedirectHostname(redirectUri: string) {
+      try {
+        return new URL(redirectUri).hostname
+      } catch {
+        return ''
+      }
+    }
+
+    function CustomConsentForm() {
+      const clerk = useClerk()
+      const location = useLocation()
+      const searchParams = new URLSearchParams(location.searchStr)
+
+      const clientId = searchParams.get('client_id') ?? ''
+      const redirectUri = searchParams.get('redirect_uri') ?? ''
+      const scope = searchParams.get('scope') ?? undefined
+      const redirectHostname = getRedirectHostname(redirectUri)
+
+      const { data, isLoading, error } = useOAuthConsent({
+        oauthClientId: clientId,
+        scope,
+      })
+
+      if (!clientId || !redirectUri) {
+        return <p>Missing OAuth consent parameters.</p>
+      }
+
+      if (isLoading) {
+        return <p>Loading consent request...</p>
+      }
+
+      if (error || !data) {
+        return <p>Unable to load consent request.</p>
+      }
+
+      return (
+        <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
+          <h1>{data.oauthApplicationName} wants access to your account</h1>
+
+          {data.oauthApplicationLogoUrl && (
+            <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
+          )}
+
+          {data.oauthApplicationUrl && (
+            <p>
+              Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
+            </p>
+          )}
+          <p>
+            Client ID: <code>{data.clientId}</code>
+          </p>
+
+          <p>
+            Review the requested permissions before continuing. After you allow or deny access, you will
+            be redirected to <strong>{redirectHostname}</strong>.
+          </p>
+
+          <details>
+            <summary>View full redirect URL</summary>
+            <code>{redirectUri}</code>
+          </details>
+
+          <ul>
+            {data.scopes.map((scope) => (
+              <li key={scope.scope}>{scope.description || scope.scope}</li>
+            ))}
+          </ul>
+
+          {/* Forward the original OAuth parameters, except fields set by this form. */}
+          {Array.from(searchParams.entries())
+            .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+            .map(([key, value], index) => (
+              <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+            ))}
+
+          <button type="submit" name="consented" value="false">
+            Deny
+          </button>
+          <button type="submit" name="consented" value="true">
+            Allow
+          </button>
+        </form>
+      )
+    }
+
+    function OAuthConsentPage() {
+      return (
+        <Show when="signed-in">
+          <CustomConsentForm />
+        </Show>
+      )
+    }
+    ```
+  </Tab>
+</Tabs>
diff --git a/docs/_partials/components/oauth-consent-examples.mdx b/docs/_partials/components/oauth-consent-examples.mdx
new file mode 100644
index 0000000000..da3098f4d3
--- /dev/null
+++ b/docs/_partials/components/oauth-consent-examples.mdx
@@ -0,0 +1,138 @@
+<Tabs items={["Next.js", "React", "React Router", "TanStack React Start", "Astro", "Vue", "Nuxt"]}>
+  <Tab>
+    ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
+    import { OAuthConsent, Show } from '@clerk/nextjs'
+
+    export const metadata = {
+      referrer: 'strict-origin-when-cross-origin',
+    }
+
+    export default function OAuthConsentPage() {
+      return (
+        <Show when="signed-in">
+          <OAuthConsent />
+        </Show>
+      )
+    }
+    ```
+  </Tab>
+
+  <Tab>
+    ```tsx {{ filename: 'src/OAuthConsentPage.tsx' }}
+    import { OAuthConsent, Show } from '@clerk/react'
+
+    export function OAuthConsentPage() {
+      return (
+        <Show when="signed-in">
+          <OAuthConsent />
+        </Show>
+      )
+    }
+    ```
+
+    ```html {{ filename: 'index.html' }}
+    <meta name="referrer" content="strict-origin-when-cross-origin" />
+    ```
+  </Tab>
+
+  <Tab>
+    ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+    import type { Route } from './+types/oauth-consent'
+    import { OAuthConsent, Show } from '@clerk/react-router'
+
+    export const meta: Route.MetaFunction = () => [
+      {
+        name: 'referrer',
+        content: 'strict-origin-when-cross-origin',
+      },
+    ]
+
+    export default function OAuthConsentPage() {
+      return (
+        <Show when="signed-in">
+          <OAuthConsent />
+        </Show>
+      )
+    }
+    ```
+  </Tab>
+
+  <Tab>
+    ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+    import { OAuthConsent, Show } from '@clerk/tanstack-react-start'
+    import { createFileRoute } from '@tanstack/react-router'
+
+    export const Route = createFileRoute('/oauth-consent')({
+      head: () => ({
+        meta: [
+          {
+            name: 'referrer',
+            content: 'strict-origin-when-cross-origin',
+          },
+        ],
+      }),
+      component: OAuthConsentPage,
+    })
+
+    function OAuthConsentPage() {
+      return (
+        <Show when="signed-in">
+          <OAuthConsent />
+        </Show>
+      )
+    }
+    ```
+  </Tab>
+
+  <Tab>
+    ```astro {{ filename: 'src/pages/oauth-consent.astro' }}
+    ---
+    import { OAuthConsent, Show } from '@clerk/astro/components'
+    ---
+
+    <head>
+      <meta name="referrer" content="strict-origin-when-cross-origin" />
+    </head>
+
+    <Show when="signed-in">
+      <OAuthConsent />
+    </Show>
+    ```
+  </Tab>
+
+  <Tab>
+    ```vue {{ filename: 'src/pages/OAuthConsentPage.vue' }}
+    <script setup lang="ts">
+    import { OAuthConsent, Show } from '@clerk/vue'
+    </script>
+
+    <template>
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    </template>
+    ```
+
+    ```html {{ filename: 'index.html' }}
+    <meta name="referrer" content="strict-origin-when-cross-origin" />
+    ```
+  </Tab>
+
+  <Tab>
+    ```vue {{ filename: 'pages/oauth-consent.vue' }}
+    <script setup lang="ts">
+    import { OAuthConsent, Show } from '@clerk/nuxt/components'
+
+    useHead({
+      meta: [{ name: 'referrer', content: 'strict-origin-when-cross-origin' }],
+    })
+    </script>
+
+    <template>
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    </template>
+    ```
+  </Tab>
+</Tabs>
diff --git a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
new file mode 100644
index 0000000000..59bd73e526
--- /dev/null
+++ b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
@@ -0,0 +1,154 @@
+---
+title: Customize the OAuth consent page
+description: Learn how to configure a custom OAuth consent page, and how to avoid common consent phishing and token grant risks.
+---
+
+Clerk strongly recommends using the default OAuth consent page hosted by the [Account Portal](/docs/guides/account-portal/overview). OAuth consent is a security boundary: it is where a signed-in user decides whether an OAuth [client](!oauth-client) can receive [OAuth access tokens](!oauth-access-token) and access the requested data. A custom page can weaken that boundary if it hides the requesting application, misstates the requested scopes, buries the deny action, auto-approves access, or trains users to trust an unfamiliar consent surface.
+
+Only customize the OAuth consent page when you have a specific product requirement that the Account Portal cannot satisfy. If you customize it, the safest approach is to host a page on your own application domain and render Clerk's prebuilt [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component. This keeps Clerk's consent logic, scope rendering, organization selection, form submission, and denial handling intact while letting you control the route, page styling, and surrounding page.
+
+> [!CAUTION]
+> Consent phishing is a real OAuth attack pattern. Attackers can trick users into granting a malicious app access to their account data without stealing their password. Microsoft describes consent phishing as an attack where users grant permissions to malicious cloud applications, and notes that MFA or password resets do not remediate illicit consent grants because the user authorized the app itself. See Microsoft's guidance on [protecting against consent phishing](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/protect-against-consent-phishing) and [detecting illicit consent grants](https://learn.microsoft.com/en-us/defender-office-365/detect-and-remediate-illicit-consent-grants).
+
+After shipping a custom consent page, monitor [Application Logs](/docs/guides/dashboard/logs/application-logs) for OAuth grant activity. The `oauth_authorization.granted` event records successful user consent, and the `oauth_token.created` event records token issuance. Review these events for unfamiliar OAuth applications, unexpected users, or unusual grant volume.
+
+## Before you start
+
+Custom consent pages apply to Clerk's OAuth provider flows, where Clerk acts as the authorization service for OAuth applications that request access to user data through Clerk.
+
+> [!NOTE]
+> If you're new to OAuth terminology, start with the [OAuth terminology guide](/docs/guides/configure/auth-strategies/oauth/overview#key-terminology).
+
+Before customizing the page:
+
+- Keep the consent screen enabled for every OAuth application. Without consent, a signed-in user who visits a valid authorization URL can grant access without seeing the request.
+- Use narrow [scopes](/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth#scopes). OAuth security guidance recommends restricting access tokens to the minimum required privileges, and Google recommends choosing the most narrowly focused scopes possible. See [RFC 9700](https://www.rfc-editor.org/rfc/rfc9700) and Google's guide to [configuring OAuth consent and choosing scopes](https://developers.google.com/workspace/guides/configure-oauth-consent).
+- Treat OAuth application branding as user-facing security information. App names, logos, client URLs, and redirect domains help users decide whether to grant access.
+- Verify the route in development and production before enabling it for real users. A broken custom consent page can block OAuth authorization flows.
+
+## What the consent page must show
+
+A safe consent page must give users enough information to make an informed decision. At minimum, show:
+
+- The OAuth application's name.
+- The OAuth application's logo, if one is available.
+- The OAuth application's public URL, if one is available.
+- The [resource service](!oauth-resource-service) receiving the access request.
+- The signed-in user who is granting access.
+- Every requested scope that requires consent, using clear descriptions.
+- The redirect destination the user will return to after allowing or denying access.
+- Equally visible **Allow** and **Deny** actions.
+
+The redirect destination presentation is security-sensitive. The prebuilt consent page shows a short domain derived from the `redirect_uri`, and lets the user expand it to view the full URL. This makes it harder for an attacker to hide the real root domain inside a very long URL with many subdomains or path segments. If you build your own UI, do not show only a truncated full URL. Show a clear domain summary, provide a way to view the full `redirect_uri`, and make sure the root domain cannot be pushed out of view by long subdomains.
+
+If you use the prebuilt component, do not hide the requested scopes, redirect warning, deny action, or application identity with `appearance` overrides. If you build a custom flow, include equivalent warning copy near the allow/deny controls. For example: "`<OAuth app name>` will be able to access `<application name>` and redirect you to `<redirect domain>`. Review the requested permissions before continuing."
+
+## Recommended implementation
+
+Use Clerk's prebuilt [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component on your custom consent route. The component reads the OAuth authorization parameters from the current URL, loads consent metadata for the signed-in user, renders the requested scopes, and submits the user's decision to Clerk.
+
+For example, create a route that renders `<OAuthConsent />`:
+
+<Include src="_partials/components/oauth-consent-examples" />
+
+The [`<Show />`](/docs/reference/components/control/show) component renders the consent screen only for signed-in users. In a normal OAuth authorization flow, Clerk redirects signed-out users to sign-in before sending them to the consent page. If users can visit your custom consent route directly, handle signed-out users the same way you handle any other protected route in your app.
+
+Keep the consent route focused on the consent decision. If your application uses a shared layout with navigation, account menus, sign-in or sign-out controls, or other links, use a minimal layout for this route instead. Unrelated navigation can take the user away from the OAuth flow and cause the authorization request to fail or lose its original parameters.
+
+If your framework does not support route metadata, set the same referrer policy with a `<meta>` tag or equivalent framework API:
+
+```tsx
+<meta name="referrer" content="strict-origin-when-cross-origin" />
+```
+
+The referrer policy is required because the consent form posts to Clerk's [Frontend API URL](!frontend-api-url). Without it, some cross-origin form submissions can send `Origin: null`, causing Clerk to reject the request.
+
+You can style `<OAuthConsent />` with the standard [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview) prop, but keep the security content intact. The Account Portal consent page is built from Clerk's prebuilt consent component, so using `appearance` is the safer option when your goal is visual customization. Use a fully custom flow only when the prebuilt component cannot support your required layout or interaction.
+
+## Configure the custom route
+
+After you create and deploy the route, configure Clerk to send users to it during OAuth flows that require consent.
+
+<Steps>
+  ### Open path settings
+
+  In the [Clerk Dashboard](https://dashboard.clerk.com), open your application, select the relevant instance, and navigate to **Configure** > **Paths**.
+
+  ### Set the OAuth consent location
+
+  In the **OAuth consent** section, choose your custom location:
+
+  - For a development instance, enter a path on the development host, such as `/oauth-consent`.
+  - For a production instance, enter an `https://` URL on your application domain, such as `https://example.com/oauth-consent`.
+
+  Clerk only accepts production OAuth consent URLs that use HTTPS and belong to the same registrable domain as your instance domain, such as `example.com` or a subdomain of `example.com`.
+
+  ### Keep OAuth application consent enabled
+
+  Navigate to [**OAuth applications**](https://dashboard.clerk.com/~/oauth-applications) and confirm that the consent screen is enabled for every OAuth application that can use the custom route.
+
+  If [dynamic client registration](/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth#dynamic-client-registration) is enabled, Clerk enforces the consent screen and does not allow it to be disabled.
+
+  ### Test an authorization request
+
+  Start an OAuth authorization flow for one of your OAuth applications. If the user is signed out, Clerk redirects to sign-in first, then redirects to your custom consent route with the original OAuth parameters. After the user allows or denies access, Clerk continues the OAuth flow and redirects back to the OAuth client's `redirect_uri`.
+</Steps>
+
+## Build a custom flow
+
+Building a [custom flow](!custom-flow) from low-level APIs is riskier than using `<OAuthConsent />`. Only do this if you need a layout or interaction that the prebuilt component cannot support.
+
+The custom flow needs to do the same work as the prebuilt component:
+
+1. Read `client_id`, `redirect_uri`, `scope`, `state`, `nonce`, `code_challenge`, `code_challenge_method`, and any other OAuth authorization parameters from the incoming URL.
+1. Load consent metadata for the signed-in user with `useOAuthConsent()` or `Clerk.oauthApplication.getConsentInfo()`.
+1. Display the returned OAuth application name, logo URL, application URL, client ID, and scopes without changing their meaning.
+1. Display the redirect destination safely. Show a short domain summary, and let the user inspect the full `redirect_uri`.
+1. Preserve and forward the original OAuth authorization parameters when submitting the decision.
+1. Submit a form with `method="POST"` to the URL returned by `Clerk.oauthApplication.buildConsentActionUrl({ clientId })`.
+1. Use a submit field named `consented`, with `value="true"` for allow and `value="false"` for deny.
+1. Include `organization_id` when the user grants access for a specific organization.
+1. Preserve the user's ability to deny access. A denial returns an OAuth `access_denied` response to the OAuth client.
+
+Do not construct the [Frontend API URL](!frontend-api-url) by hand. Use `buildConsentActionUrl()` so Clerk can include the current session and development browser parameters that are required for the request.
+
+The following examples show the minimum shape of a custom consent page. They intentionally keep the UI plain so you can see the OAuth-specific requirements.
+
+<Include src="_partials/components/oauth-consent-custom-flow-examples" />
+
+These examples display the full redirect hostname and an expandable full URL. For a production custom flow, use a public-suffix-aware approach for root-domain summaries, handle IP addresses and localhost explicitly, and test long redirect URIs to make sure the real destination remains visible.
+
+These examples also do not implement organization selection. If an OAuth application can request `user:org:read`, use `<OAuthConsent />` or add an organization selector that submits the selected `organization_id` with the allow action.
+
+The low-level `useOAuthConsent()` examples in this guide are available for Clerk's React-based SDKs. For Astro, Vue, and Nuxt, use the prebuilt `<OAuthConsent />` component unless you are prepared to build directly against [ClerkJS](/docs/reference/javascript/overview) and maintain the consent flow yourself.
+
+## Security checklist
+
+Before shipping a custom consent page, verify the following:
+
+- The page is served over HTTPS in production.
+- The page is on your application domain or subdomain, not on an unrelated domain.
+- The page cannot be framed by untrusted sites. Use appropriate `Content-Security-Policy` `frame-ancestors` or equivalent headers.
+- The page does not include third-party scripts that can read OAuth parameters or alter the consent form.
+- The page uses a minimal layout without unrelated navigation, account menus, or links that could take the user away from the OAuth flow.
+- The page displays the requesting OAuth application's identity and requested scopes before the user can allow access.
+- The page prevents code injection from OAuth application-provided values, including application names, logo URLs, application URLs, and redirect URLs.
+- The **Deny** action is visible and works.
+- The page never grants consent automatically.
+- The page forwards the original OAuth authorization parameters without allowing query parameters to override form-controlled fields such as `consented` or `organization_id`.
+- The page uses `strict-origin-when-cross-origin` referrer policy.
+- The OAuth application requests only the scopes it needs.
+- Your team can audit OAuth applications and revoke suspicious grants if needed.
+
+## Prefer appearance for visual changes
+
+If your main goal is to change colors, fonts, spacing, or logos, use the [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview) prop with `<OAuthConsent />` instead of building a custom flow. This keeps Clerk's consent behavior, redirect destination presentation, organization selection, form submission, and future security updates intact.
+
+Only build a low-level custom flow if:
+
+- The prebuilt component cannot support your required layout or interaction.
+- You can maintain the route as a security-sensitive surface.
+- You can show the requesting OAuth application's identity, requested scopes, and redirect destination clearly.
+- You can preserve an equally visible deny action.
+
+Do not build a custom flow to hide scopes, hide redirect destinations, remove the deny action, or auto-approve trusted clients. Instead, model trust through OAuth application configuration, narrow scopes, and administrative review. Custom consent pages should make the consent decision clearer, not easier to miss.
diff --git a/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth.mdx b/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth.mdx
index 26f9b9745a..8e9059b265 100644
--- a/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth.mdx
@@ -83,6 +83,8 @@ The consent screen is enabled by default for all OAuth apps. You can enable or d
 
 > [!IMPORTANT]
 > Enabling the consent screen for all OAuth apps is **strongly recommended**. Without a consent screen, any logged-in user who visits an OAuth authorization URL automatically grants access to any requested scopes. The consent screen acts as a critical security checkpoint, preventing malicious apps from silently gaining access to user accounts.
+>
+> If you need to host the consent page on your own application domain, see [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page). Clerk strongly recommends using the default [Account Portal](/docs/guides/account-portal/overview) consent page unless you have a specific product requirement that it cannot satisfy.
 
 ## Token expiration and management
 
diff --git a/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx b/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx
index 263a5e407f..8729020b48 100644
--- a/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx
@@ -69,6 +69,8 @@ This guide provides step-by-step instructions on how to build OAuth scoped acces
   > The consent screen uses the scopes passed in the authorization request to inform the user exactly what they're granting access to, and to whom.
   >
   > By default, the consent screen is shown for all newly created OAuth apps, but this can be disabled in each app's settings [in the Clerk Dashboard](https://dashboard.clerk.com/~/oauth-applications), although not recommended. Learn more about [how Clerk's OAuth consent screen works](/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth#consent-screen-management).
+  >
+  > If you need to host the consent page yourself, see [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page). Clerk strongly recommends using the default [Account Portal](/docs/guides/account-portal/overview) consent page unless you have a specific product requirement that it cannot satisfy.
 
   Once you have accepted, you'll be redirected to the OAuth callback route, the `redirect_uri` specified earlier. This process will exchange the authorization code for an [access token](!oauth-access-token), and return the access token and refresh token as a JSON response, similar to this:
 
diff --git a/docs/manifest.json b/docs/manifest.json
index 36e2836308..6330f0796b 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -362,6 +362,10 @@
                                 "title": "How Clerk implements OAuth",
                                 "href": "/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth"
                               },
+                              {
+                                "title": "Customize the OAuth consent page",
+                                "href": "/docs/guides/configure/auth-strategies/oauth/custom-consent-page"
+                              },
                               {
                                 "title": "Use OAuth for Single Sign-On (SSO)",
                                 "href": "/docs/guides/configure/auth-strategies/oauth/single-sign-on"
diff --git a/docs/reference/components/authentication/oauth-consent.mdx b/docs/reference/components/authentication/oauth-consent.mdx
index 6741b2edd4..9b1e2049f3 100644
--- a/docs/reference/components/authentication/oauth-consent.mdx
+++ b/docs/reference/components/authentication/oauth-consent.mdx
@@ -8,6 +8,8 @@ The `<OAuthConsent />` component renders an OAuth consent screen for authenticat
 
 By default, `<OAuthConsent />` reads the OAuth `client_id`, `scope`, and `redirect_uri` from the current URL. You can override the `client_id` and `scope` with props when rendering the component on a custom route.
 
+For route setup guidance and security considerations, see [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page).
+
 > [!IMPORTANT]
 > `<OAuthConsent />` only renders for authenticated users. If the user is signed out, the component will not be displayed.
 
@@ -20,6 +22,7 @@ The following example includes a basic implementation of the `<OAuthConsent />`
 <If sdk="nextjs">
   ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
   import { OAuthConsent } from '@clerk/nextjs'
+  import type { Metadata } from 'next'
 
   export const metadata: Metadata = {
     referrer: 'strict-origin-when-cross-origin',
@@ -32,20 +35,17 @@ The following example includes a basic implementation of the `<OAuthConsent />`
 </If>
 
 <If sdk="react">
-  ```tsx {{ filename: 'src/routes/oauth-consent.tsx' }}
+  ```tsx {{ filename: 'src/OAuthConsentPage.tsx' }}
   import { OAuthConsent } from '@clerk/react'
 
-  export const meta = () => [
-    {
-      name: 'referrer',
-      content: 'strict-origin-when-cross-origin',
-    },
-  ]
-
   export default function OAuthConsentPage() {
     return <OAuthConsent />
   }
   ```
+
+  ```html {{ filename: 'index.html' }}
+  <meta name="referrer" content="strict-origin-when-cross-origin" />
+  ```
 </If>
 
 <If sdk="react-router">
@@ -90,7 +90,7 @@ The following example includes a basic implementation of the `<OAuthConsent />`
 </If>
 
 <If sdk="astro">
-  ```astro {{ filename: 'pages/oauth-consent.astro' }}
+  ```astro {{ filename: 'src/pages/oauth-consent.astro' }}
   ---
   import { OAuthConsent } from '@clerk/astro/components'
   ---
@@ -107,7 +107,7 @@ The following example includes a basic implementation of the `<OAuthConsent />`
 </If>
 
 <If sdk="vue">
-  ```vue {{ filename: 'oauth-consent.vue' }}
+  ```vue {{ filename: 'src/pages/OAuthConsentPage.vue' }}
   <script setup lang="ts">
   import { OAuthConsent } from '@clerk/vue'
   import { useHead } from '@unhead/vue'
@@ -129,9 +129,10 @@ The following example includes a basic implementation of the `<OAuthConsent />`
 </If>
 
 <If sdk="nuxt">
-  ```vue {{ filename: 'oauth-consent.vue' }}
+  ```vue {{ filename: 'pages/oauth-consent.vue' }}
   <script setup lang="ts">
-  // Components are automatically imported
+  import { OAuthConsent } from '@clerk/nuxt/components'
+
   useHead({
     meta: [
       {
diff --git a/docs/reference/hooks/use-oauth-consent.mdx b/docs/reference/hooks/use-oauth-consent.mdx
index 3bac28dd84..eeae68b4a3 100644
--- a/docs/reference/hooks/use-oauth-consent.mdx
+++ b/docs/reference/hooks/use-oauth-consent.mdx
@@ -8,6 +8,8 @@ The `useOAuthConsent()` hook loads OAuth consent metadata for an authenticated u
 
 Unlike the [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component, this hook doesn't read values from the current URL. Pass the `oauthClientId` explicitly, and optionally pass `scope` if you want Clerk to scope the request to a specific space-delimited scope string.
 
+Building a low-level custom consent flow is security-sensitive. For setup guidance, redirect URL presentation requirements, and a safer prebuilt component option, see [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page).
+
 <Include src="_partials/oauth-consent/callout" />
 
 ## Parameters
@@ -22,22 +24,23 @@ Unlike the [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-
 
 ## Example
 
-The following example demonstrates how to use the `useOAuthConsent()` hook to fetch OAuth consent metadata and build a custom consent form. In this example, the `client_id` is read from the current URL and passed to the hook, and the form submits to the URL generated by the [`buildConsentActionUrl()`](/docs/reference/types/oauth-application) method.
+The following example demonstrates how to use the `useOAuthConsent()` hook to fetch OAuth consent metadata and build a custom consent form. In this example, the `client_id` is read from the current URL and passed to the hook, and the form submits to the URL generated by the [`buildConsentActionUrl()`](/docs/reference/types/oauth-application) method. The example intentionally focuses on the hook API; production consent pages must also clearly present the redirect destination and other security context described in [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page).
 
 <If sdk="react">
-  ```tsx {{ filename: 'src/routes/oauth-consent.tsx' }}
+  ```tsx {{ filename: 'src/OAuthConsentPage.tsx' }}
   import { useClerk, useOAuthConsent } from '@clerk/react'
 
-  export const meta = () => [
-    {
-      name: 'referrer',
-      content: 'strict-origin-when-cross-origin',
-    },
-  ]
+  function getConsentSearchParams() {
+    if (typeof window === 'undefined') {
+      return new URLSearchParams()
+    }
+
+    return new URLSearchParams(window.location.search)
+  }
 
   export default function OAuthConsentPage() {
     const clerk = useClerk()
-    const params = new URLSearchParams(window.location.search)
+    const params = getConsentSearchParams()
     const clientId = params.get('client_id') ?? ''
     const scope = params.get('scope') ?? undefined
 
@@ -46,10 +49,11 @@ The following example demonstrates how to use the `useOAuthConsent()` hook to fe
       scope,
     })
 
-    const actionUrl = clerk.oauthApplication.buildConsentActionUrl({ clientId })
-
+    if (!clientId) return <div>Missing OAuth client ID.</div>
     if (isLoading) return <div>Loading...</div>
-    if (error) return <div>Something went wrong.</div>
+    if (error || !data) return <div>Something went wrong.</div>
+
+    const actionUrl = clerk.oauthApplication.buildConsentActionUrl({ clientId })
 
     return (
       <form method="POST" action={actionUrl}>
@@ -67,27 +71,30 @@ The following example demonstrates how to use the `useOAuthConsent()` hook to fe
           Allow
         </button>
 
-        {Array.from(params.entries()).map(([key, value]) => (
-          <input key={key} type="hidden" name={key} value={value} />
-        ))}
+        {/* Forward the original OAuth parameters, except fields set by this form. */}
+        {Array.from(params.entries())
+          .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+          .map(([key, value], index) => (
+            <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+          ))}
       </form>
     )
   }
   ```
+
+  ```html {{ filename: 'index.html' }}
+  <meta name="referrer" content="strict-origin-when-cross-origin" />
+  ```
 </If>
 
 <If sdk="nextjs">
-  ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
+  ```tsx {{ filename: 'app/oauth-consent/custom-consent-form.tsx' }}
   'use client'
 
   import { useClerk, useOAuthConsent } from '@clerk/nextjs'
   import { useSearchParams } from 'next/navigation'
 
-  export const metadata: Metadata = {
-    referrer: 'strict-origin-when-cross-origin',
-  }
-
-  export default function Page() {
+  export function CustomConsentForm() {
     const clerk = useClerk()
     const params = useSearchParams()
     const clientId = params.get('client_id') ?? ''
@@ -98,10 +105,11 @@ The following example demonstrates how to use the `useOAuthConsent()` hook to fe
       scope,
     })
 
-    const actionUrl = clerk.oauthApplication.buildConsentActionUrl({ clientId })
-
+    if (!clientId) return <div>Missing OAuth client ID.</div>
     if (isLoading) return <div>Loading...</div>
-    if (error) return <div>Something went wrong.</div>
+    if (error || !data) return <div>Something went wrong.</div>
+
+    const actionUrl = clerk.oauthApplication.buildConsentActionUrl({ clientId })
 
     return (
       <form method="POST" action={actionUrl}>
@@ -119,13 +127,34 @@ The following example demonstrates how to use the `useOAuthConsent()` hook to fe
           Allow
         </button>
 
-        {Array.from(params.entries()).map(([key, value]) => (
-          <input key={key} type="hidden" name={key} value={value} />
-        ))}
+        {/* Forward the original OAuth parameters, except fields set by this form. */}
+        {Array.from(params.entries())
+          .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+          .map(([key, value], index) => (
+            <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+          ))}
       </form>
     )
   }
   ```
+
+  ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
+  import { CustomConsentForm } from './custom-consent-form'
+  import type { Metadata } from 'next'
+  import { Suspense } from 'react'
+
+  export const metadata: Metadata = {
+    referrer: 'strict-origin-when-cross-origin',
+  }
+
+  export default function Page() {
+    return (
+      <Suspense fallback={<div>Loading...</div>}>
+        <CustomConsentForm />
+      </Suspense>
+    )
+  }
+  ```
 </If>
 
 <If sdk="react-router">
@@ -152,10 +181,11 @@ The following example demonstrates how to use the `useOAuthConsent()` hook to fe
       scope,
     })
 
-    const actionUrl = clerk.oauthApplication.buildConsentActionUrl({ clientId })
-
+    if (!clientId) return <div>Missing OAuth client ID.</div>
     if (isLoading) return <div>Loading...</div>
-    if (error) return <div>Something went wrong.</div>
+    if (error || !data) return <div>Something went wrong.</div>
+
+    const actionUrl = clerk.oauthApplication.buildConsentActionUrl({ clientId })
 
     return (
       <form method="POST" action={actionUrl}>
@@ -173,9 +203,12 @@ The following example demonstrates how to use the `useOAuthConsent()` hook to fe
           Allow
         </button>
 
-        {Array.from(params.entries()).map(([key, value]) => (
-          <input key={key} type="hidden" name={key} value={value} />
-        ))}
+        {/* Forward the original OAuth parameters, except fields set by this form. */}
+        {Array.from(params.entries())
+          .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+          .map(([key, value], index) => (
+            <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+          ))}
       </form>
     )
   }
@@ -185,7 +218,7 @@ The following example demonstrates how to use the `useOAuthConsent()` hook to fe
 <If sdk="tanstack-react-start">
   ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
   import { useClerk, useOAuthConsent } from '@clerk/tanstack-react-start'
-  import { createFileRoute } from '@tanstack/react-router'
+  import { createFileRoute, useLocation } from '@tanstack/react-router'
 
   export const Route = createFileRoute('/oauth-consent')({
     head: () => ({
@@ -196,28 +229,26 @@ The following example demonstrates how to use the `useOAuthConsent()` hook to fe
         },
       ],
     }),
-    validateSearch: (search: Record<string, unknown>) => ({
-      client_id: typeof search.client_id === 'string' ? search.client_id : '',
-      scope: typeof search.scope === 'string' ? search.scope : undefined,
-    }),
     component: OAuthConsentPage,
   })
 
   function OAuthConsentPage() {
     const clerk = useClerk()
-    const params = Route.useSearch()
-    const clientId = params.client_id
-    const scope = params.scope
+    const location = useLocation()
+    const params = new URLSearchParams(location.searchStr)
+    const clientId = params.get('client_id') ?? ''
+    const scope = params.get('scope') ?? undefined
 
     const { data, isLoading, error } = useOAuthConsent({
       oauthClientId: clientId,
       scope,
     })
 
-    const actionUrl = clerk.oauthApplication.buildConsentActionUrl({ clientId })
-
+    if (!clientId) return <div>Missing OAuth client ID.</div>
     if (isLoading) return <div>Loading...</div>
-    if (error) return <div>Something went wrong.</div>
+    if (error || !data) return <div>Something went wrong.</div>
+
+    const actionUrl = clerk.oauthApplication.buildConsentActionUrl({ clientId })
 
     return (
       <form method="POST" action={actionUrl}>
@@ -235,9 +266,12 @@ The following example demonstrates how to use the `useOAuthConsent()` hook to fe
           Allow
         </button>
 
-        {Object.entries(params).map(([key, value]) => (
-          <input key={key} type="hidden" name={key} value={value} />
-        ))}
+        {/* Forward the original OAuth parameters, except fields set by this form. */}
+        {Array.from(params.entries())
+          .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+          .map(([key, value], index) => (
+            <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+          ))}
       </form>
     )
   }

From 10bc5f0ec3a984794c85ec65e9702aeb1381d7f5 Mon Sep 17 00:00:00 2001
From: Sarah Soutoul <sarah@clerk.dev>
Date: Tue, 9 Jun 2026 15:59:23 -0600
Subject: [PATCH 2/7] docs review

---
 .../oauth-consent-custom-flow-examples.mdx    | 11 ++--
 .../components/oauth-consent-examples.mdx     | 16 +++---
 .../oauth/custom-consent-page.mdx             |  8 +--
 .../oauth/how-clerk-implements-oauth.mdx      |  2 +-
 .../auth-strategies/oauth/scoped-access.mdx   |  2 +-
 docs/manifest.json                            |  2 +-
 .../authentication/oauth-consent.mdx          | 54 +++++++++++++------
 docs/reference/hooks/use-oauth-consent.mdx    |  4 +-
 8 files changed, 62 insertions(+), 37 deletions(-)

diff --git a/docs/_partials/components/oauth-consent-custom-flow-examples.mdx b/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
index e27534389a..872b94c317 100644
--- a/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
+++ b/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
@@ -1,6 +1,6 @@
 <Tabs items={["Next.js", "React", "React Router", "TanStack React Start"]}>
   <Tab>
-    ```tsx {{ filename: 'app/oauth-consent/custom-consent-form.tsx' }}
+    ```tsx {{ filename: 'app/oauth-consent/custom-consent-form.tsx', collapsible: true }}
     'use client'
 
     import { useClerk, useOAuthConsent } from '@clerk/nextjs'
@@ -93,10 +93,11 @@
 
     ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
     import { Show } from '@clerk/nextjs'
+    import type { Metadata } from 'next'
     import { Suspense } from 'react'
     import { CustomConsentForm } from './custom-consent-form'
 
-    export const metadata = {
+    export const metadata: Metadata = {
       referrer: 'strict-origin-when-cross-origin',
     }
 
@@ -113,7 +114,7 @@
   </Tab>
 
   <Tab>
-    ```tsx {{ filename: 'src/OAuthConsentPage.tsx' }}
+    ```tsx {{ filename: 'src/OAuthConsentPage.tsx', collapsible: true }}
     import { Show, useClerk, useOAuthConsent } from '@clerk/react'
 
     function getConsentSearchParams() {
@@ -223,7 +224,7 @@
   </Tab>
 
   <Tab>
-    ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+    ```tsx {{ filename: 'app/routes/oauth-consent.tsx', collapsible: true }}
     import type { Route } from './+types/oauth-consent'
     import { Show, useClerk, useOAuthConsent } from '@clerk/react-router'
     import { useLocation } from 'react-router'
@@ -331,7 +332,7 @@
   </Tab>
 
   <Tab>
-    ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+    ```tsx {{ filename: 'app/routes/oauth-consent.tsx', collapsible: true }}
     import { Show, useClerk, useOAuthConsent } from '@clerk/tanstack-react-start'
     import { createFileRoute, useLocation } from '@tanstack/react-router'
 
diff --git a/docs/_partials/components/oauth-consent-examples.mdx b/docs/_partials/components/oauth-consent-examples.mdx
index da3098f4d3..560d127999 100644
--- a/docs/_partials/components/oauth-consent-examples.mdx
+++ b/docs/_partials/components/oauth-consent-examples.mdx
@@ -2,8 +2,9 @@
   <Tab>
     ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
     import { OAuthConsent, Show } from '@clerk/nextjs'
+    import type { Metadata } from 'next'
 
-    export const metadata = {
+    export const metadata: Metadata = {
       referrer: 'strict-origin-when-cross-origin',
     }
 
@@ -101,9 +102,14 @@
   </Tab>
 
   <Tab>
-    ```vue {{ filename: 'src/pages/OAuthConsentPage.vue' }}
+    ```vue {{ filename: 'src/pages/oauth-consent.vue' }}
     <script setup lang="ts">
     import { OAuthConsent, Show } from '@clerk/vue'
+    import { useHead } from '@unhead/vue'
+
+    useHead({
+      meta: [{ name: 'referrer', content: 'strict-origin-when-cross-origin' }],
+    })
     </script>
 
     <template>
@@ -112,16 +118,12 @@
       </Show>
     </template>
     ```
-
-    ```html {{ filename: 'index.html' }}
-    <meta name="referrer" content="strict-origin-when-cross-origin" />
-    ```
   </Tab>
 
   <Tab>
     ```vue {{ filename: 'pages/oauth-consent.vue' }}
     <script setup lang="ts">
-    import { OAuthConsent, Show } from '@clerk/nuxt/components'
+    // Components are automatically imported
 
     useHead({
       meta: [{ name: 'referrer', content: 'strict-origin-when-cross-origin' }],
diff --git a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
index 59bd73e526..087a70be56 100644
--- a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
@@ -1,5 +1,5 @@
 ---
-title: Customize the OAuth consent page
+title: Set up a custom OAuth consent page
 description: Learn how to configure a custom OAuth consent page, and how to avoid common consent phishing and token grant risks.
 ---
 
@@ -72,11 +72,11 @@ After you create and deploy the route, configure Clerk to send users to it durin
 <Steps>
   ### Open path settings
 
-  In the [Clerk Dashboard](https://dashboard.clerk.com), open your application, select the relevant instance, and navigate to **Configure** > **Paths**.
+  In the Clerk Dashboard, navigate to the [**Paths**](https://dashboard.clerk.com/~/paths) page of your application.
 
   ### Set the OAuth consent location
 
-  In the **OAuth consent** section, choose your custom location:
+  Under **Component paths**, locate the the **OAuth consent** section and choose your custom location:
 
   - For a development instance, enter a path on the development host, such as `/oauth-consent`.
   - For a production instance, enter an `https://` URL on your application domain, such as `https://example.com/oauth-consent`.
@@ -116,7 +116,7 @@ The following examples show the minimum shape of a custom consent page. They int
 
 <Include src="_partials/components/oauth-consent-custom-flow-examples" />
 
-These examples display the full redirect hostname and an expandable full URL. For a production custom flow, use a public-suffix-aware approach for root-domain summaries, handle IP addresses and localhost explicitly, and test long redirect URIs to make sure the real destination remains visible.
+These examples display the full redirect hostname and an expandable full URL. For a production custom flow, use a public-suffix-aware approach for root-domain summaries, handle IP addresses and `localhost` explicitly, and test long redirect URIs to make sure the real destination remains visible.
 
 These examples also do not implement organization selection. If an OAuth application can request `user:org:read`, use `<OAuthConsent />` or add an organization selector that submits the selected `organization_id` with the allow action.
 
diff --git a/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth.mdx b/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth.mdx
index 8e9059b265..958360b517 100644
--- a/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth.mdx
@@ -84,7 +84,7 @@ The consent screen is enabled by default for all OAuth apps. You can enable or d
 > [!IMPORTANT]
 > Enabling the consent screen for all OAuth apps is **strongly recommended**. Without a consent screen, any logged-in user who visits an OAuth authorization URL automatically grants access to any requested scopes. The consent screen acts as a critical security checkpoint, preventing malicious apps from silently gaining access to user accounts.
 >
-> If you need to host the consent page on your own application domain, see [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page). Clerk strongly recommends using the default [Account Portal](/docs/guides/account-portal/overview) consent page unless you have a specific product requirement that it cannot satisfy.
+> If you need to host the consent page on your own application domain, see [Set up a custom OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page). Clerk strongly recommends using the default [Account Portal](/docs/guides/account-portal/overview) consent page unless you have a specific product requirement that it cannot satisfy.
 
 ## Token expiration and management
 
diff --git a/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx b/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx
index 8729020b48..5dac5ca9b6 100644
--- a/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx
@@ -70,7 +70,7 @@ This guide provides step-by-step instructions on how to build OAuth scoped acces
   >
   > By default, the consent screen is shown for all newly created OAuth apps, but this can be disabled in each app's settings [in the Clerk Dashboard](https://dashboard.clerk.com/~/oauth-applications), although not recommended. Learn more about [how Clerk's OAuth consent screen works](/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth#consent-screen-management).
   >
-  > If you need to host the consent page yourself, see [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page). Clerk strongly recommends using the default [Account Portal](/docs/guides/account-portal/overview) consent page unless you have a specific product requirement that it cannot satisfy.
+  > If you need to host the consent page on your own application domain, see [Set up a custom OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page). Clerk strongly recommends using the default [Account Portal](/docs/guides/account-portal/overview) consent page unless you have a specific product requirement that it cannot satisfy.
 
   Once you have accepted, you'll be redirected to the OAuth callback route, the `redirect_uri` specified earlier. This process will exchange the authorization code for an [access token](!oauth-access-token), and return the access token and refresh token as a JSON response, similar to this:
 
diff --git a/docs/manifest.json b/docs/manifest.json
index 6330f0796b..29e7af039e 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -363,7 +363,7 @@
                                 "href": "/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth"
                               },
                               {
-                                "title": "Customize the OAuth consent page",
+                                "title": "Set up a custom OAuth consent page",
                                 "href": "/docs/guides/configure/auth-strategies/oauth/custom-consent-page"
                               },
                               {
diff --git a/docs/reference/components/authentication/oauth-consent.mdx b/docs/reference/components/authentication/oauth-consent.mdx
index 9b1e2049f3..ad6beb9bc2 100644
--- a/docs/reference/components/authentication/oauth-consent.mdx
+++ b/docs/reference/components/authentication/oauth-consent.mdx
@@ -8,7 +8,7 @@ The `<OAuthConsent />` component renders an OAuth consent screen for authenticat
 
 By default, `<OAuthConsent />` reads the OAuth `client_id`, `scope`, and `redirect_uri` from the current URL. You can override the `client_id` and `scope` with props when rendering the component on a custom route.
 
-For route setup guidance and security considerations, see [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page).
+For route setup guidance and security considerations, see [Set up a custom OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page).
 
 > [!IMPORTANT]
 > `<OAuthConsent />` only renders for authenticated users. If the user is signed out, the component will not be displayed.
@@ -21,7 +21,7 @@ The following example includes a basic implementation of the `<OAuthConsent />`
 
 <If sdk="nextjs">
   ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
-  import { OAuthConsent } from '@clerk/nextjs'
+  import { OAuthConsent, Show } from '@clerk/nextjs'
   import type { Metadata } from 'next'
 
   export const metadata: Metadata = {
@@ -29,17 +29,25 @@ The following example includes a basic implementation of the `<OAuthConsent />`
   }
 
   export default function Page() {
-    return <OAuthConsent />
+    return (
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    )
   }
   ```
 </If>
 
 <If sdk="react">
   ```tsx {{ filename: 'src/OAuthConsentPage.tsx' }}
-  import { OAuthConsent } from '@clerk/react'
+  import { OAuthConsent, Show } from '@clerk/react'
 
   export default function OAuthConsentPage() {
-    return <OAuthConsent />
+    return (
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    )
   }
   ```
 
@@ -51,7 +59,7 @@ The following example includes a basic implementation of the `<OAuthConsent />`
 <If sdk="react-router">
   ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
   import type { Route } from './+types/oauth-consent'
-  import { OAuthConsent } from '@clerk/react-router'
+  import { OAuthConsent, Show } from '@clerk/react-router'
 
   export const meta: Route.MetaFunction = () => [
     {
@@ -61,14 +69,18 @@ The following example includes a basic implementation of the `<OAuthConsent />`
   ]
 
   export default function OAuthConsentPage() {
-    return <OAuthConsent />
+    return (
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    )
   }
   ```
 </If>
 
 <If sdk="tanstack-react-start">
   ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
-  import { OAuthConsent } from '@clerk/tanstack-react-start'
+  import { OAuthConsent, Show } from '@clerk/tanstack-react-start'
   import { createFileRoute } from '@tanstack/react-router'
 
   export const Route = createFileRoute('/oauth-consent')({
@@ -84,7 +96,11 @@ The following example includes a basic implementation of the `<OAuthConsent />`
   })
 
   function OAuthConsentPage() {
-    return <OAuthConsent />
+    return (
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    )
   }
   ```
 </If>
@@ -92,7 +108,7 @@ The following example includes a basic implementation of the `<OAuthConsent />`
 <If sdk="astro">
   ```astro {{ filename: 'src/pages/oauth-consent.astro' }}
   ---
-  import { OAuthConsent } from '@clerk/astro/components'
+  import { OAuthConsent, Show } from '@clerk/astro/components'
   ---
 
   <html lang="en">
@@ -100,16 +116,18 @@ The following example includes a basic implementation of the `<OAuthConsent />`
       <meta name="referrer" content="strict-origin-when-cross-origin" />
     </head>
     <body>
-      <OAuthConsent />
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
     </body>
   </html>
   ```
 </If>
 
 <If sdk="vue">
-  ```vue {{ filename: 'src/pages/OAuthConsentPage.vue' }}
+  ```vue {{ filename: 'src/pages/oauth-consent.vue' }}
   <script setup lang="ts">
-  import { OAuthConsent } from '@clerk/vue'
+  import { OAuthConsent, Show } from '@clerk/vue'
   import { useHead } from '@unhead/vue'
 
   useHead({
@@ -123,7 +141,9 @@ The following example includes a basic implementation of the `<OAuthConsent />`
   </script>
 
   <template>
-    <OAuthConsent />
+    <Show when="signed-in">
+      <OAuthConsent />
+    </Show>
   </template>
   ```
 </If>
@@ -131,7 +151,7 @@ The following example includes a basic implementation of the `<OAuthConsent />`
 <If sdk="nuxt">
   ```vue {{ filename: 'pages/oauth-consent.vue' }}
   <script setup lang="ts">
-  import { OAuthConsent } from '@clerk/nuxt/components'
+  // Components are automatically imported
 
   useHead({
     meta: [
@@ -144,7 +164,9 @@ The following example includes a basic implementation of the `<OAuthConsent />`
   </script>
 
   <template>
-    <OAuthConsent />
+    <Show when="signed-in">
+      <OAuthConsent />
+    </Show>
   </template>
   ```
 </If>
diff --git a/docs/reference/hooks/use-oauth-consent.mdx b/docs/reference/hooks/use-oauth-consent.mdx
index eeae68b4a3..5c0436e222 100644
--- a/docs/reference/hooks/use-oauth-consent.mdx
+++ b/docs/reference/hooks/use-oauth-consent.mdx
@@ -8,7 +8,7 @@ The `useOAuthConsent()` hook loads OAuth consent metadata for an authenticated u
 
 Unlike the [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component, this hook doesn't read values from the current URL. Pass the `oauthClientId` explicitly, and optionally pass `scope` if you want Clerk to scope the request to a specific space-delimited scope string.
 
-Building a low-level custom consent flow is security-sensitive. For setup guidance, redirect URL presentation requirements, and a safer prebuilt component option, see [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page).
+Building a low-level custom consent flow is security-sensitive. For setup guidance, redirect URL presentation requirements, and a safer prebuilt component option, see [Set up a custom OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page).
 
 <Include src="_partials/oauth-consent/callout" />
 
@@ -24,7 +24,7 @@ Building a low-level custom consent flow is security-sensitive. For setup guidan
 
 ## Example
 
-The following example demonstrates how to use the `useOAuthConsent()` hook to fetch OAuth consent metadata and build a custom consent form. In this example, the `client_id` is read from the current URL and passed to the hook, and the form submits to the URL generated by the [`buildConsentActionUrl()`](/docs/reference/types/oauth-application) method. The example intentionally focuses on the hook API; production consent pages must also clearly present the redirect destination and other security context described in [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page).
+The following example demonstrates how to use the `useOAuthConsent()` hook to fetch OAuth consent metadata and build a custom consent form. In this example, the `client_id` is read from the current URL and passed to the hook, and the form submits to the URL generated by the [`buildConsentActionUrl()`](/docs/reference/types/oauth-application) method. The example intentionally focuses on the hook API; production consent pages must also clearly present the redirect destination and other security context described in [Set up a custom OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page).
 
 <If sdk="react">
   ```tsx {{ filename: 'src/OAuthConsentPage.tsx' }}

From 7546f9e857a9327f9532c5a096a57a00e6732751 Mon Sep 17 00:00:00 2001
From: Jeff Escalante <jescalan@users.noreply.github.com>
Date: Mon, 15 Jun 2026 17:29:44 -0400
Subject: [PATCH 3/7] Scope OAuth consent snippets by SDK

---
 .../oauth-consent-custom-flow-examples.mdx    | 808 +++++++++---------
 .../components/oauth-consent-examples.mdx     | 276 +++---
 .../oauth/custom-consent-page.mdx             |   1 +
 3 files changed, 551 insertions(+), 534 deletions(-)

diff --git a/docs/_partials/components/oauth-consent-custom-flow-examples.mdx b/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
index 872b94c317..278274103e 100644
--- a/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
+++ b/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
@@ -1,445 +1,443 @@
-<Tabs items={["Next.js", "React", "React Router", "TanStack React Start"]}>
-  <Tab>
-    ```tsx {{ filename: 'app/oauth-consent/custom-consent-form.tsx', collapsible: true }}
-    'use client'
-
-    import { useClerk, useOAuthConsent } from '@clerk/nextjs'
-    import { useSearchParams } from 'next/navigation'
-
-    function getRedirectHostname(redirectUri: string) {
-      try {
-        return new URL(redirectUri).hostname
-      } catch {
-        return ''
-      }
+<If sdk="nextjs">
+  ```tsx {{ filename: 'app/oauth-consent/custom-consent-form.tsx', collapsible: true }}
+  'use client'
+
+  import { useClerk, useOAuthConsent } from '@clerk/nextjs'
+  import { useSearchParams } from 'next/navigation'
+
+  function getRedirectHostname(redirectUri: string) {
+    try {
+      return new URL(redirectUri).hostname
+    } catch {
+      return ''
     }
+  }
 
-    export function CustomConsentForm() {
-      const clerk = useClerk()
-      const searchParams = useSearchParams()
-
-      const clientId = searchParams.get('client_id') ?? ''
-      const redirectUri = searchParams.get('redirect_uri') ?? ''
-      const scope = searchParams.get('scope') ?? undefined
-      const redirectHostname = getRedirectHostname(redirectUri)
-
-      const { data, isLoading, error } = useOAuthConsent({
-        oauthClientId: clientId,
-        scope,
-      })
-
-      if (!clientId || !redirectUri) {
-        return <p>Missing OAuth consent parameters.</p>
-      }
-
-      if (isLoading) {
-        return <p>Loading consent request...</p>
-      }
-
-      if (error || !data) {
-        return <p>Unable to load consent request.</p>
-      }
-
-      return (
-        <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
-          <h1>{data.oauthApplicationName} wants access to your account</h1>
-
-          {data.oauthApplicationLogoUrl && (
-            <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
-          )}
-
-          {data.oauthApplicationUrl && (
-            <p>
-              Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
-            </p>
-          )}
-          <p>
-            Client ID: <code>{data.clientId}</code>
-          </p>
+  export function CustomConsentForm() {
+    const clerk = useClerk()
+    const searchParams = useSearchParams()
 
-          <p>
-            Review the requested permissions before continuing. After you allow or deny access, you will
-            be redirected to <strong>{redirectHostname}</strong>.
-          </p>
+    const clientId = searchParams.get('client_id') ?? ''
+    const redirectUri = searchParams.get('redirect_uri') ?? ''
+    const scope = searchParams.get('scope') ?? undefined
+    const redirectHostname = getRedirectHostname(redirectUri)
 
-          <details>
-            <summary>View full redirect URL</summary>
-            <code>{redirectUri}</code>
-          </details>
-
-          <ul>
-            {data.scopes.map((scope) => (
-              <li key={scope.scope}>{scope.description || scope.scope}</li>
-            ))}
-          </ul>
-
-          {/* Forward the original OAuth parameters, except fields set by this form. */}
-          {Array.from(searchParams.entries())
-            .filter(([key]) => key !== 'consented' && key !== 'organization_id')
-            .map(([key, value], index) => (
-              <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
-            ))}
-
-          <button type="submit" name="consented" value="false">
-            Deny
-          </button>
-          <button type="submit" name="consented" value="true">
-            Allow
-          </button>
-        </form>
-      )
-    }
-    ```
+    const { data, isLoading, error } = useOAuthConsent({
+      oauthClientId: clientId,
+      scope,
+    })
 
-    ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
-    import { Show } from '@clerk/nextjs'
-    import type { Metadata } from 'next'
-    import { Suspense } from 'react'
-    import { CustomConsentForm } from './custom-consent-form'
+    if (!clientId || !redirectUri) {
+      return <p>Missing OAuth consent parameters.</p>
+    }
 
-    export const metadata: Metadata = {
-      referrer: 'strict-origin-when-cross-origin',
+    if (isLoading) {
+      return <p>Loading consent request...</p>
     }
 
-    export default function OAuthConsentPage() {
-      return (
-        <Show when="signed-in">
-          <Suspense fallback={<p>Loading consent request...</p>}>
-            <CustomConsentForm />
-          </Suspense>
-        </Show>
-      )
+    if (error || !data) {
+      return <p>Unable to load consent request.</p>
     }
-    ```
-  </Tab>
 
-  <Tab>
-    ```tsx {{ filename: 'src/OAuthConsentPage.tsx', collapsible: true }}
-    import { Show, useClerk, useOAuthConsent } from '@clerk/react'
+    return (
+      <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
+        <h1>{data.oauthApplicationName} wants access to your account</h1>
 
-    function getConsentSearchParams() {
-      if (typeof window === 'undefined') {
-        return new URLSearchParams()
-      }
+        {data.oauthApplicationLogoUrl && (
+          <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
+        )}
 
-      return new URLSearchParams(window.location.search)
+        {data.oauthApplicationUrl && (
+          <p>
+            Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
+          </p>
+        )}
+        <p>
+          Client ID: <code>{data.clientId}</code>
+        </p>
+
+        <p>
+          Review the requested permissions before continuing. After you allow or deny access, you will
+          be redirected to <strong>{redirectHostname}</strong>.
+        </p>
+
+        <details>
+          <summary>View full redirect URL</summary>
+          <code>{redirectUri}</code>
+        </details>
+
+        <ul>
+          {data.scopes.map((scope) => (
+            <li key={scope.scope}>{scope.description || scope.scope}</li>
+          ))}
+        </ul>
+
+        {/* Forward the original OAuth parameters, except fields set by this form. */}
+        {Array.from(searchParams.entries())
+          .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+          .map(([key, value], index) => (
+            <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+          ))}
+
+        <button type="submit" name="consented" value="false">
+          Deny
+        </button>
+        <button type="submit" name="consented" value="true">
+          Allow
+        </button>
+      </form>
+    )
+  }
+  ```
+
+  ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
+  import { Show } from '@clerk/nextjs'
+  import type { Metadata } from 'next'
+  import { Suspense } from 'react'
+  import { CustomConsentForm } from './custom-consent-form'
+
+  export const metadata: Metadata = {
+    referrer: 'strict-origin-when-cross-origin',
+  }
+
+  export default function OAuthConsentPage() {
+    return (
+      <Show when="signed-in">
+        <Suspense fallback={<p>Loading consent request...</p>}>
+          <CustomConsentForm />
+        </Suspense>
+      </Show>
+    )
+  }
+  ```
+</If>
+
+<If sdk="react">
+  ```tsx {{ filename: 'src/OAuthConsentPage.tsx', collapsible: true }}
+  import { Show, useClerk, useOAuthConsent } from '@clerk/react'
+
+  function getConsentSearchParams() {
+    if (typeof window === 'undefined') {
+      return new URLSearchParams()
     }
 
-    function getRedirectHostname(redirectUri: string) {
-      try {
-        return new URL(redirectUri).hostname
-      } catch {
-        return ''
-      }
+    return new URLSearchParams(window.location.search)
+  }
+
+  function getRedirectHostname(redirectUri: string) {
+    try {
+      return new URL(redirectUri).hostname
+    } catch {
+      return ''
     }
+  }
 
-    function CustomConsentForm() {
-      const clerk = useClerk()
-      const searchParams = getConsentSearchParams()
-
-      const clientId = searchParams.get('client_id') ?? ''
-      const redirectUri = searchParams.get('redirect_uri') ?? ''
-      const scope = searchParams.get('scope') ?? undefined
-      const redirectHostname = getRedirectHostname(redirectUri)
-
-      const { data, isLoading, error } = useOAuthConsent({
-        oauthClientId: clientId,
-        scope,
-      })
-
-      if (!clientId || !redirectUri) {
-        return <p>Missing OAuth consent parameters.</p>
-      }
-
-      if (isLoading) {
-        return <p>Loading consent request...</p>
-      }
-
-      if (error || !data) {
-        return <p>Unable to load consent request.</p>
-      }
-
-      return (
-        <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
-          <h1>{data.oauthApplicationName} wants access to your account</h1>
-
-          {data.oauthApplicationLogoUrl && (
-            <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
-          )}
-
-          {data.oauthApplicationUrl && (
-            <p>
-              Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
-            </p>
-          )}
-          <p>
-            Client ID: <code>{data.clientId}</code>
-          </p>
+  function CustomConsentForm() {
+    const clerk = useClerk()
+    const searchParams = getConsentSearchParams()
 
-          <p>
-            Review the requested permissions before continuing. After you allow or deny access, you will
-            be redirected to <strong>{redirectHostname}</strong>.
-          </p>
+    const clientId = searchParams.get('client_id') ?? ''
+    const redirectUri = searchParams.get('redirect_uri') ?? ''
+    const scope = searchParams.get('scope') ?? undefined
+    const redirectHostname = getRedirectHostname(redirectUri)
 
-          <details>
-            <summary>View full redirect URL</summary>
-            <code>{redirectUri}</code>
-          </details>
-
-          <ul>
-            {data.scopes.map((scope) => (
-              <li key={scope.scope}>{scope.description || scope.scope}</li>
-            ))}
-          </ul>
-
-          {/* Forward the original OAuth parameters, except fields set by this form. */}
-          {Array.from(searchParams.entries())
-            .filter(([key]) => key !== 'consented' && key !== 'organization_id')
-            .map(([key, value], index) => (
-              <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
-            ))}
-
-          <button type="submit" name="consented" value="false">
-            Deny
-          </button>
-          <button type="submit" name="consented" value="true">
-            Allow
-          </button>
-        </form>
-      )
+    const { data, isLoading, error } = useOAuthConsent({
+      oauthClientId: clientId,
+      scope,
+    })
+
+    if (!clientId || !redirectUri) {
+      return <p>Missing OAuth consent parameters.</p>
     }
 
-    export function OAuthConsentPage() {
-      return (
-        <Show when="signed-in">
-          <CustomConsentForm />
-        </Show>
-      )
+    if (isLoading) {
+      return <p>Loading consent request...</p>
     }
-    ```
-
-    ```html {{ filename: 'index.html' }}
-    <meta name="referrer" content="strict-origin-when-cross-origin" />
-    ```
-  </Tab>
-
-  <Tab>
-    ```tsx {{ filename: 'app/routes/oauth-consent.tsx', collapsible: true }}
-    import type { Route } from './+types/oauth-consent'
-    import { Show, useClerk, useOAuthConsent } from '@clerk/react-router'
-    import { useLocation } from 'react-router'
-
-    export const meta: Route.MetaFunction = () => [
-      {
-        name: 'referrer',
-        content: 'strict-origin-when-cross-origin',
-      },
-    ]
-
-    function getRedirectHostname(redirectUri: string) {
-      try {
-        return new URL(redirectUri).hostname
-      } catch {
-        return ''
-      }
+
+    if (error || !data) {
+      return <p>Unable to load consent request.</p>
     }
 
-    function CustomConsentForm() {
-      const clerk = useClerk()
-      const { search } = useLocation()
-      const searchParams = new URLSearchParams(search)
-
-      const clientId = searchParams.get('client_id') ?? ''
-      const redirectUri = searchParams.get('redirect_uri') ?? ''
-      const scope = searchParams.get('scope') ?? undefined
-      const redirectHostname = getRedirectHostname(redirectUri)
-
-      const { data, isLoading, error } = useOAuthConsent({
-        oauthClientId: clientId,
-        scope,
-      })
-
-      if (!clientId || !redirectUri) {
-        return <p>Missing OAuth consent parameters.</p>
-      }
-
-      if (isLoading) {
-        return <p>Loading consent request...</p>
-      }
-
-      if (error || !data) {
-        return <p>Unable to load consent request.</p>
-      }
-
-      return (
-        <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
-          <h1>{data.oauthApplicationName} wants access to your account</h1>
-
-          {data.oauthApplicationLogoUrl && (
-            <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
-          )}
-
-          {data.oauthApplicationUrl && (
-            <p>
-              Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
-            </p>
-          )}
-          <p>
-            Client ID: <code>{data.clientId}</code>
-          </p>
+    return (
+      <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
+        <h1>{data.oauthApplicationName} wants access to your account</h1>
 
+        {data.oauthApplicationLogoUrl && (
+          <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
+        )}
+
+        {data.oauthApplicationUrl && (
           <p>
-            Review the requested permissions before continuing. After you allow or deny access, you will
-            be redirected to <strong>{redirectHostname}</strong>.
+            Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
           </p>
+        )}
+        <p>
+          Client ID: <code>{data.clientId}</code>
+        </p>
+
+        <p>
+          Review the requested permissions before continuing. After you allow or deny access, you will
+          be redirected to <strong>{redirectHostname}</strong>.
+        </p>
+
+        <details>
+          <summary>View full redirect URL</summary>
+          <code>{redirectUri}</code>
+        </details>
+
+        <ul>
+          {data.scopes.map((scope) => (
+            <li key={scope.scope}>{scope.description || scope.scope}</li>
+          ))}
+        </ul>
+
+        {/* Forward the original OAuth parameters, except fields set by this form. */}
+        {Array.from(searchParams.entries())
+          .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+          .map(([key, value], index) => (
+            <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+          ))}
+
+        <button type="submit" name="consented" value="false">
+          Deny
+        </button>
+        <button type="submit" name="consented" value="true">
+          Allow
+        </button>
+      </form>
+    )
+  }
+
+  export function OAuthConsentPage() {
+    return (
+      <Show when="signed-in">
+        <CustomConsentForm />
+      </Show>
+    )
+  }
+  ```
+
+  ```html {{ filename: 'index.html' }}
+  <meta name="referrer" content="strict-origin-when-cross-origin" />
+  ```
+</If>
+
+<If sdk="react-router">
+  ```tsx {{ filename: 'app/routes/oauth-consent.tsx', collapsible: true }}
+  import type { Route } from './+types/oauth-consent'
+  import { Show, useClerk, useOAuthConsent } from '@clerk/react-router'
+  import { useLocation } from 'react-router'
+
+  export const meta: Route.MetaFunction = () => [
+    {
+      name: 'referrer',
+      content: 'strict-origin-when-cross-origin',
+    },
+  ]
+
+  function getRedirectHostname(redirectUri: string) {
+    try {
+      return new URL(redirectUri).hostname
+    } catch {
+      return ''
+    }
+  }
 
-          <details>
-            <summary>View full redirect URL</summary>
-            <code>{redirectUri}</code>
-          </details>
-
-          <ul>
-            {data.scopes.map((scope) => (
-              <li key={scope.scope}>{scope.description || scope.scope}</li>
-            ))}
-          </ul>
-
-          {/* Forward the original OAuth parameters, except fields set by this form. */}
-          {Array.from(searchParams.entries())
-            .filter(([key]) => key !== 'consented' && key !== 'organization_id')
-            .map(([key, value], index) => (
-              <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
-            ))}
-
-          <button type="submit" name="consented" value="false">
-            Deny
-          </button>
-          <button type="submit" name="consented" value="true">
-            Allow
-          </button>
-        </form>
-      )
+  function CustomConsentForm() {
+    const clerk = useClerk()
+    const { search } = useLocation()
+    const searchParams = new URLSearchParams(search)
+
+    const clientId = searchParams.get('client_id') ?? ''
+    const redirectUri = searchParams.get('redirect_uri') ?? ''
+    const scope = searchParams.get('scope') ?? undefined
+    const redirectHostname = getRedirectHostname(redirectUri)
+
+    const { data, isLoading, error } = useOAuthConsent({
+      oauthClientId: clientId,
+      scope,
+    })
+
+    if (!clientId || !redirectUri) {
+      return <p>Missing OAuth consent parameters.</p>
     }
 
-    export default function OAuthConsentPage() {
-      return (
-        <Show when="signed-in">
-          <CustomConsentForm />
-        </Show>
-      )
+    if (isLoading) {
+      return <p>Loading consent request...</p>
     }
-    ```
-  </Tab>
-
-  <Tab>
-    ```tsx {{ filename: 'app/routes/oauth-consent.tsx', collapsible: true }}
-    import { Show, useClerk, useOAuthConsent } from '@clerk/tanstack-react-start'
-    import { createFileRoute, useLocation } from '@tanstack/react-router'
-
-    export const Route = createFileRoute('/oauth-consent')({
-      head: () => ({
-        meta: [
-          {
-            name: 'referrer',
-            content: 'strict-origin-when-cross-origin',
-          },
-        ],
-      }),
-      component: OAuthConsentPage,
-    })
 
-    function getRedirectHostname(redirectUri: string) {
-      try {
-        return new URL(redirectUri).hostname
-      } catch {
-        return ''
-      }
+    if (error || !data) {
+      return <p>Unable to load consent request.</p>
     }
 
-    function CustomConsentForm() {
-      const clerk = useClerk()
-      const location = useLocation()
-      const searchParams = new URLSearchParams(location.searchStr)
-
-      const clientId = searchParams.get('client_id') ?? ''
-      const redirectUri = searchParams.get('redirect_uri') ?? ''
-      const scope = searchParams.get('scope') ?? undefined
-      const redirectHostname = getRedirectHostname(redirectUri)
-
-      const { data, isLoading, error } = useOAuthConsent({
-        oauthClientId: clientId,
-        scope,
-      })
-
-      if (!clientId || !redirectUri) {
-        return <p>Missing OAuth consent parameters.</p>
-      }
-
-      if (isLoading) {
-        return <p>Loading consent request...</p>
-      }
-
-      if (error || !data) {
-        return <p>Unable to load consent request.</p>
-      }
-
-      return (
-        <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
-          <h1>{data.oauthApplicationName} wants access to your account</h1>
-
-          {data.oauthApplicationLogoUrl && (
-            <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
-          )}
-
-          {data.oauthApplicationUrl && (
-            <p>
-              Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
-            </p>
-          )}
-          <p>
-            Client ID: <code>{data.clientId}</code>
-          </p>
+    return (
+      <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
+        <h1>{data.oauthApplicationName} wants access to your account</h1>
+
+        {data.oauthApplicationLogoUrl && (
+          <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
+        )}
 
+        {data.oauthApplicationUrl && (
           <p>
-            Review the requested permissions before continuing. After you allow or deny access, you will
-            be redirected to <strong>{redirectHostname}</strong>.
+            Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
           </p>
+        )}
+        <p>
+          Client ID: <code>{data.clientId}</code>
+        </p>
+
+        <p>
+          Review the requested permissions before continuing. After you allow or deny access, you will
+          be redirected to <strong>{redirectHostname}</strong>.
+        </p>
+
+        <details>
+          <summary>View full redirect URL</summary>
+          <code>{redirectUri}</code>
+        </details>
+
+        <ul>
+          {data.scopes.map((scope) => (
+            <li key={scope.scope}>{scope.description || scope.scope}</li>
+          ))}
+        </ul>
+
+        {/* Forward the original OAuth parameters, except fields set by this form. */}
+        {Array.from(searchParams.entries())
+          .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+          .map(([key, value], index) => (
+            <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+          ))}
+
+        <button type="submit" name="consented" value="false">
+          Deny
+        </button>
+        <button type="submit" name="consented" value="true">
+          Allow
+        </button>
+      </form>
+    )
+  }
+
+  export default function OAuthConsentPage() {
+    return (
+      <Show when="signed-in">
+        <CustomConsentForm />
+      </Show>
+    )
+  }
+  ```
+</If>
+
+<If sdk="tanstack-react-start">
+  ```tsx {{ filename: 'app/routes/oauth-consent.tsx', collapsible: true }}
+  import { Show, useClerk, useOAuthConsent } from '@clerk/tanstack-react-start'
+  import { createFileRoute, useLocation } from '@tanstack/react-router'
+
+  export const Route = createFileRoute('/oauth-consent')({
+    head: () => ({
+      meta: [
+        {
+          name: 'referrer',
+          content: 'strict-origin-when-cross-origin',
+        },
+      ],
+    }),
+    component: OAuthConsentPage,
+  })
+
+  function getRedirectHostname(redirectUri: string) {
+    try {
+      return new URL(redirectUri).hostname
+    } catch {
+      return ''
+    }
+  }
+
+  function CustomConsentForm() {
+    const clerk = useClerk()
+    const location = useLocation()
+    const searchParams = new URLSearchParams(location.searchStr)
 
-          <details>
-            <summary>View full redirect URL</summary>
-            <code>{redirectUri}</code>
-          </details>
-
-          <ul>
-            {data.scopes.map((scope) => (
-              <li key={scope.scope}>{scope.description || scope.scope}</li>
-            ))}
-          </ul>
-
-          {/* Forward the original OAuth parameters, except fields set by this form. */}
-          {Array.from(searchParams.entries())
-            .filter(([key]) => key !== 'consented' && key !== 'organization_id')
-            .map(([key, value], index) => (
-              <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
-            ))}
-
-          <button type="submit" name="consented" value="false">
-            Deny
-          </button>
-          <button type="submit" name="consented" value="true">
-            Allow
-          </button>
-        </form>
-      )
+    const clientId = searchParams.get('client_id') ?? ''
+    const redirectUri = searchParams.get('redirect_uri') ?? ''
+    const scope = searchParams.get('scope') ?? undefined
+    const redirectHostname = getRedirectHostname(redirectUri)
+
+    const { data, isLoading, error } = useOAuthConsent({
+      oauthClientId: clientId,
+      scope,
+    })
+
+    if (!clientId || !redirectUri) {
+      return <p>Missing OAuth consent parameters.</p>
     }
 
-    function OAuthConsentPage() {
-      return (
-        <Show when="signed-in">
-          <CustomConsentForm />
-        </Show>
-      )
+    if (isLoading) {
+      return <p>Loading consent request...</p>
+    }
+
+    if (error || !data) {
+      return <p>Unable to load consent request.</p>
     }
-    ```
-  </Tab>
-</Tabs>
+
+    return (
+      <form method="POST" action={clerk.oauthApplication.buildConsentActionUrl({ clientId })}>
+        <h1>{data.oauthApplicationName} wants access to your account</h1>
+
+        {data.oauthApplicationLogoUrl && (
+          <img src={data.oauthApplicationLogoUrl} alt={`${data.oauthApplicationName} logo`} />
+        )}
+
+        {data.oauthApplicationUrl && (
+          <p>
+            Application URL: <a href={data.oauthApplicationUrl}>{data.oauthApplicationUrl}</a>
+          </p>
+        )}
+        <p>
+          Client ID: <code>{data.clientId}</code>
+        </p>
+
+        <p>
+          Review the requested permissions before continuing. After you allow or deny access, you will
+          be redirected to <strong>{redirectHostname}</strong>.
+        </p>
+
+        <details>
+          <summary>View full redirect URL</summary>
+          <code>{redirectUri}</code>
+        </details>
+
+        <ul>
+          {data.scopes.map((scope) => (
+            <li key={scope.scope}>{scope.description || scope.scope}</li>
+          ))}
+        </ul>
+
+        {/* Forward the original OAuth parameters, except fields set by this form. */}
+        {Array.from(searchParams.entries())
+          .filter(([key]) => key !== 'consented' && key !== 'organization_id')
+          .map(([key, value], index) => (
+            <input key={`${key}:${index}`} type="hidden" name={key} value={value} />
+          ))}
+
+        <button type="submit" name="consented" value="false">
+          Deny
+        </button>
+        <button type="submit" name="consented" value="true">
+          Allow
+        </button>
+      </form>
+    )
+  }
+
+  function OAuthConsentPage() {
+    return (
+      <Show when="signed-in">
+        <CustomConsentForm />
+      </Show>
+    )
+  }
+  ```
+</If>
diff --git a/docs/_partials/components/oauth-consent-examples.mdx b/docs/_partials/components/oauth-consent-examples.mdx
index 560d127999..b0d0603469 100644
--- a/docs/_partials/components/oauth-consent-examples.mdx
+++ b/docs/_partials/components/oauth-consent-examples.mdx
@@ -1,140 +1,158 @@
-<Tabs items={["Next.js", "React", "React Router", "TanStack React Start", "Astro", "Vue", "Nuxt"]}>
-  <Tab>
-    ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
-    import { OAuthConsent, Show } from '@clerk/nextjs'
-    import type { Metadata } from 'next'
-
-    export const metadata: Metadata = {
-      referrer: 'strict-origin-when-cross-origin',
-    }
-
-    export default function OAuthConsentPage() {
-      return (
-        <Show when="signed-in">
-          <OAuthConsent />
-        </Show>
-      )
-    }
-    ```
-  </Tab>
-
-  <Tab>
-    ```tsx {{ filename: 'src/OAuthConsentPage.tsx' }}
-    import { OAuthConsent, Show } from '@clerk/react'
-
-    export function OAuthConsentPage() {
-      return (
-        <Show when="signed-in">
-          <OAuthConsent />
-        </Show>
-      )
-    }
-    ```
-
-    ```html {{ filename: 'index.html' }}
+<If sdk="nextjs">
+  ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
+  import { OAuthConsent, Show } from '@clerk/nextjs'
+  import type { Metadata } from 'next'
+
+  export const metadata: Metadata = {
+    referrer: 'strict-origin-when-cross-origin',
+  }
+
+  export default function OAuthConsentPage() {
+    return (
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    )
+  }
+  ```
+</If>
+
+<If sdk="react">
+  ```tsx {{ filename: 'src/OAuthConsentPage.tsx' }}
+  import { OAuthConsent, Show } from '@clerk/react'
+
+  export function OAuthConsentPage() {
+    return (
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    )
+  }
+  ```
+
+  ```html {{ filename: 'index.html' }}
+  <meta name="referrer" content="strict-origin-when-cross-origin" />
+  ```
+</If>
+
+<If sdk="react-router">
+  ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+  import type { Route } from './+types/oauth-consent'
+  import { OAuthConsent, Show } from '@clerk/react-router'
+
+  export const meta: Route.MetaFunction = () => [
+    {
+      name: 'referrer',
+      content: 'strict-origin-when-cross-origin',
+    },
+  ]
+
+  export default function OAuthConsentPage() {
+    return (
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    )
+  }
+  ```
+</If>
+
+<If sdk="tanstack-react-start">
+  ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+  import { OAuthConsent, Show } from '@clerk/tanstack-react-start'
+  import { createFileRoute } from '@tanstack/react-router'
+
+  export const Route = createFileRoute('/oauth-consent')({
+    head: () => ({
+      meta: [
+        {
+          name: 'referrer',
+          content: 'strict-origin-when-cross-origin',
+        },
+      ],
+    }),
+    component: OAuthConsentPage,
+  })
+
+  function OAuthConsentPage() {
+    return (
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    )
+  }
+  ```
+</If>
+
+<If sdk="astro">
+  ```astro {{ filename: 'src/pages/oauth-consent.astro' }}
+  ---
+  import { OAuthConsent, Show } from '@clerk/astro/components'
+  ---
+
+  <head>
     <meta name="referrer" content="strict-origin-when-cross-origin" />
-    ```
-  </Tab>
-
-  <Tab>
-    ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
-    import type { Route } from './+types/oauth-consent'
-    import { OAuthConsent, Show } from '@clerk/react-router'
-
-    export const meta: Route.MetaFunction = () => [
-      {
-        name: 'referrer',
-        content: 'strict-origin-when-cross-origin',
-      },
-    ]
-
-    export default function OAuthConsentPage() {
-      return (
-        <Show when="signed-in">
-          <OAuthConsent />
-        </Show>
-      )
-    }
-    ```
-  </Tab>
-
-  <Tab>
-    ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
-    import { OAuthConsent, Show } from '@clerk/tanstack-react-start'
-    import { createFileRoute } from '@tanstack/react-router'
-
-    export const Route = createFileRoute('/oauth-consent')({
-      head: () => ({
-        meta: [
-          {
-            name: 'referrer',
-            content: 'strict-origin-when-cross-origin',
-          },
-        ],
-      }),
-      component: OAuthConsentPage,
-    })
-
-    function OAuthConsentPage() {
-      return (
-        <Show when="signed-in">
-          <OAuthConsent />
-        </Show>
-      )
-    }
-    ```
-  </Tab>
-
-  <Tab>
-    ```astro {{ filename: 'src/pages/oauth-consent.astro' }}
-    ---
-    import { OAuthConsent, Show } from '@clerk/astro/components'
-    ---
-
-    <head>
-      <meta name="referrer" content="strict-origin-when-cross-origin" />
-    </head>
+  </head>
+
+  <Show when="signed-in">
+    <OAuthConsent />
+  </Show>
+  ```
+</If>
+
+<If sdk="vue">
+  ```vue {{ filename: 'src/pages/oauth-consent.vue' }}
+  <script setup lang="ts">
+  import { OAuthConsent, Show } from '@clerk/vue'
+  import { useHead } from '@unhead/vue'
+
+  useHead({
+    meta: [{ name: 'referrer', content: 'strict-origin-when-cross-origin' }],
+  })
+  </script>
+
+  <template>
+    <Show when="signed-in">
+      <OAuthConsent />
+    </Show>
+  </template>
+  ```
+</If>
+
+<If sdk="nuxt">
+  ```vue {{ filename: 'pages/oauth-consent.vue' }}
+  <script setup lang="ts">
+  // Components are automatically imported
+
+  useHead({
+    meta: [{ name: 'referrer', content: 'strict-origin-when-cross-origin' }],
+  })
+  </script>
 
+  <template>
     <Show when="signed-in">
       <OAuthConsent />
     </Show>
-    ```
-  </Tab>
+  </template>
+  ```
+</If>
 
-  <Tab>
-    ```vue {{ filename: 'src/pages/oauth-consent.vue' }}
-    <script setup lang="ts">
-    import { OAuthConsent, Show } from '@clerk/vue'
-    import { useHead } from '@unhead/vue'
+<If sdk="js-frontend">
+  ```html {{ filename: 'index.html' }}
+  <meta name="referrer" content="strict-origin-when-cross-origin" />
+  <div id="oauth-consent"></div>
+  ```
 
-    useHead({
-      meta: [{ name: 'referrer', content: 'strict-origin-when-cross-origin' }],
-    })
-    </script>
+  ```js {{ filename: 'main.js' }}
+  import { Clerk } from '@clerk/clerk-js'
 
-    <template>
-      <Show when="signed-in">
-        <OAuthConsent />
-      </Show>
-    </template>
-    ```
-  </Tab>
+  const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
 
-  <Tab>
-    ```vue {{ filename: 'pages/oauth-consent.vue' }}
-    <script setup lang="ts">
-    // Components are automatically imported
+  const clerk = new Clerk(clerkPubKey)
+  await clerk.load()
 
-    useHead({
-      meta: [{ name: 'referrer', content: 'strict-origin-when-cross-origin' }],
-    })
-    </script>
+  const oauthConsentDiv = document.getElementById('oauth-consent')
 
-    <template>
-      <Show when="signed-in">
-        <OAuthConsent />
-      </Show>
-    </template>
-    ```
-  </Tab>
-</Tabs>
+  clerk.mountOAuthConsent(oauthConsentDiv)
+  ```
+</If>
diff --git a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
index 087a70be56..b9b629eb60 100644
--- a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
@@ -1,6 +1,7 @@
 ---
 title: Set up a custom OAuth consent page
 description: Learn how to configure a custom OAuth consent page, and how to avoid common consent phishing and token grant risks.
+sdk: astro, nextjs, nuxt, react, react-router, tanstack-react-start, vue, js-frontend
 ---
 
 Clerk strongly recommends using the default OAuth consent page hosted by the [Account Portal](/docs/guides/account-portal/overview). OAuth consent is a security boundary: it is where a signed-in user decides whether an OAuth [client](!oauth-client) can receive [OAuth access tokens](!oauth-access-token) and access the requested data. A custom page can weaken that boundary if it hides the requesting application, misstates the requested scopes, buries the deny action, auto-approves access, or trains users to trust an unfamiliar consent surface.

From 462f082602ab707cd3483709da27dc2106c5c9a5 Mon Sep 17 00:00:00 2001
From: Jeff Escalante <jescalan@users.noreply.github.com>
Date: Mon, 15 Jun 2026 18:05:55 -0400
Subject: [PATCH 4/7] Fix OAuth consent SDK examples

---
 .../oauth-consent-custom-flow-examples.mdx    | 34 ++++++++++++++++---
 .../components/oauth-consent-examples.mdx     | 13 ++++---
 .../oauth/custom-consent-page.mdx             |  2 +-
 .../authentication/oauth-consent.mdx          | 18 ++++------
 docs/reference/hooks/use-oauth-consent.mdx    |  2 +-
 5 files changed, 43 insertions(+), 26 deletions(-)

diff --git a/docs/_partials/components/oauth-consent-custom-flow-examples.mdx b/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
index 278274103e..0867e0bf21 100644
--- a/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
+++ b/docs/_partials/components/oauth-consent-custom-flow-examples.mdx
@@ -2,7 +2,7 @@
   ```tsx {{ filename: 'app/oauth-consent/custom-consent-form.tsx', collapsible: true }}
   'use client'
 
-  import { useClerk, useOAuthConsent } from '@clerk/nextjs'
+  import { useClerk, useOAuthConsent, useUser } from '@clerk/nextjs'
   import { useSearchParams } from 'next/navigation'
 
   function getRedirectHostname(redirectUri: string) {
@@ -15,6 +15,7 @@
 
   export function CustomConsentForm() {
     const clerk = useClerk()
+    const { user } = useUser()
     const searchParams = useSearchParams()
 
     const clientId = searchParams.get('client_id') ?? ''
@@ -55,6 +56,11 @@
         <p>
           Client ID: <code>{data.clientId}</code>
         </p>
+        <p>
+          Signed-in user:{' '}
+          <strong>{user?.primaryEmailAddress?.emailAddress ?? user?.username ?? user?.id}</strong>
+        </p>
+        <p>Resource service: Clerk user data</p>
 
         <p>
           Review the requested permissions before continuing. After you allow or deny access, you will
@@ -114,7 +120,7 @@
 
 <If sdk="react">
   ```tsx {{ filename: 'src/OAuthConsentPage.tsx', collapsible: true }}
-  import { Show, useClerk, useOAuthConsent } from '@clerk/react'
+  import { Show, useClerk, useOAuthConsent, useUser } from '@clerk/react'
 
   function getConsentSearchParams() {
     if (typeof window === 'undefined') {
@@ -134,6 +140,7 @@
 
   function CustomConsentForm() {
     const clerk = useClerk()
+    const { user } = useUser()
     const searchParams = getConsentSearchParams()
 
     const clientId = searchParams.get('client_id') ?? ''
@@ -174,6 +181,11 @@
         <p>
           Client ID: <code>{data.clientId}</code>
         </p>
+        <p>
+          Signed-in user:{' '}
+          <strong>{user?.primaryEmailAddress?.emailAddress ?? user?.username ?? user?.id}</strong>
+        </p>
+        <p>Resource service: Clerk user data</p>
 
         <p>
           Review the requested permissions before continuing. After you allow or deny access, you will
@@ -225,7 +237,7 @@
 <If sdk="react-router">
   ```tsx {{ filename: 'app/routes/oauth-consent.tsx', collapsible: true }}
   import type { Route } from './+types/oauth-consent'
-  import { Show, useClerk, useOAuthConsent } from '@clerk/react-router'
+  import { Show, useClerk, useOAuthConsent, useUser } from '@clerk/react-router'
   import { useLocation } from 'react-router'
 
   export const meta: Route.MetaFunction = () => [
@@ -245,6 +257,7 @@
 
   function CustomConsentForm() {
     const clerk = useClerk()
+    const { user } = useUser()
     const { search } = useLocation()
     const searchParams = new URLSearchParams(search)
 
@@ -286,6 +299,11 @@
         <p>
           Client ID: <code>{data.clientId}</code>
         </p>
+        <p>
+          Signed-in user:{' '}
+          <strong>{user?.primaryEmailAddress?.emailAddress ?? user?.username ?? user?.id}</strong>
+        </p>
+        <p>Resource service: Clerk user data</p>
 
         <p>
           Review the requested permissions before continuing. After you allow or deny access, you will
@@ -331,8 +349,8 @@
 </If>
 
 <If sdk="tanstack-react-start">
-  ```tsx {{ filename: 'app/routes/oauth-consent.tsx', collapsible: true }}
-  import { Show, useClerk, useOAuthConsent } from '@clerk/tanstack-react-start'
+  ```tsx {{ filename: 'src/routes/oauth-consent.tsx', collapsible: true }}
+  import { Show, useClerk, useOAuthConsent, useUser } from '@clerk/tanstack-react-start'
   import { createFileRoute, useLocation } from '@tanstack/react-router'
 
   export const Route = createFileRoute('/oauth-consent')({
@@ -357,6 +375,7 @@
 
   function CustomConsentForm() {
     const clerk = useClerk()
+    const { user } = useUser()
     const location = useLocation()
     const searchParams = new URLSearchParams(location.searchStr)
 
@@ -398,6 +417,11 @@
         <p>
           Client ID: <code>{data.clientId}</code>
         </p>
+        <p>
+          Signed-in user:{' '}
+          <strong>{user?.primaryEmailAddress?.emailAddress ?? user?.username ?? user?.id}</strong>
+        </p>
+        <p>Resource service: Clerk user data</p>
 
         <p>
           Review the requested permissions before continuing. After you allow or deny access, you will
diff --git a/docs/_partials/components/oauth-consent-examples.mdx b/docs/_partials/components/oauth-consent-examples.mdx
index b0d0603469..2c2ab84132 100644
--- a/docs/_partials/components/oauth-consent-examples.mdx
+++ b/docs/_partials/components/oauth-consent-examples.mdx
@@ -58,7 +58,7 @@
 </If>
 
 <If sdk="tanstack-react-start">
-  ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+  ```tsx {{ filename: 'src/routes/oauth-consent.tsx' }}
   import { OAuthConsent, Show } from '@clerk/tanstack-react-start'
   import { createFileRoute } from '@tanstack/react-router'
 
@@ -104,11 +104,6 @@
   ```vue {{ filename: 'src/pages/oauth-consent.vue' }}
   <script setup lang="ts">
   import { OAuthConsent, Show } from '@clerk/vue'
-  import { useHead } from '@unhead/vue'
-
-  useHead({
-    meta: [{ name: 'referrer', content: 'strict-origin-when-cross-origin' }],
-  })
   </script>
 
   <template>
@@ -117,10 +112,14 @@
     </Show>
   </template>
   ```
+
+  ```html {{ filename: 'index.html' }}
+  <meta name="referrer" content="strict-origin-when-cross-origin" />
+  ```
 </If>
 
 <If sdk="nuxt">
-  ```vue {{ filename: 'pages/oauth-consent.vue' }}
+  ```vue {{ filename: 'app/pages/oauth-consent.vue' }}
   <script setup lang="ts">
   // Components are automatically imported
 
diff --git a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
index b9b629eb60..c7ec71b97e 100644
--- a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
@@ -103,7 +103,7 @@ The custom flow needs to do the same work as the prebuilt component:
 
 1. Read `client_id`, `redirect_uri`, `scope`, `state`, `nonce`, `code_challenge`, `code_challenge_method`, and any other OAuth authorization parameters from the incoming URL.
 1. Load consent metadata for the signed-in user with `useOAuthConsent()` or `Clerk.oauthApplication.getConsentInfo()`.
-1. Display the returned OAuth application name, logo URL, application URL, client ID, and scopes without changing their meaning.
+1. Display the signed-in user, resource service, OAuth application name, logo URL, application URL, client ID, and scopes without changing their meaning.
 1. Display the redirect destination safely. Show a short domain summary, and let the user inspect the full `redirect_uri`.
 1. Preserve and forward the original OAuth authorization parameters when submitting the decision.
 1. Submit a form with `method="POST"` to the URL returned by `Clerk.oauthApplication.buildConsentActionUrl({ clientId })`.
diff --git a/docs/reference/components/authentication/oauth-consent.mdx b/docs/reference/components/authentication/oauth-consent.mdx
index ad6beb9bc2..b9bcb8dd3f 100644
--- a/docs/reference/components/authentication/oauth-consent.mdx
+++ b/docs/reference/components/authentication/oauth-consent.mdx
@@ -79,7 +79,7 @@ The following example includes a basic implementation of the `<OAuthConsent />`
 </If>
 
 <If sdk="tanstack-react-start">
-  ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+  ```tsx {{ filename: 'src/routes/oauth-consent.tsx' }}
   import { OAuthConsent, Show } from '@clerk/tanstack-react-start'
   import { createFileRoute } from '@tanstack/react-router'
 
@@ -128,16 +128,6 @@ The following example includes a basic implementation of the `<OAuthConsent />`
   ```vue {{ filename: 'src/pages/oauth-consent.vue' }}
   <script setup lang="ts">
   import { OAuthConsent, Show } from '@clerk/vue'
-  import { useHead } from '@unhead/vue'
-
-  useHead({
-    meta: [
-      {
-        name: 'referrer',
-        content: 'strict-origin-when-cross-origin',
-      },
-    ],
-  })
   </script>
 
   <template>
@@ -146,10 +136,14 @@ The following example includes a basic implementation of the `<OAuthConsent />`
     </Show>
   </template>
   ```
+
+  ```html {{ filename: 'index.html' }}
+  <meta name="referrer" content="strict-origin-when-cross-origin" />
+  ```
 </If>
 
 <If sdk="nuxt">
-  ```vue {{ filename: 'pages/oauth-consent.vue' }}
+  ```vue {{ filename: 'app/pages/oauth-consent.vue' }}
   <script setup lang="ts">
   // Components are automatically imported
 
diff --git a/docs/reference/hooks/use-oauth-consent.mdx b/docs/reference/hooks/use-oauth-consent.mdx
index 5c0436e222..12a3254a0f 100644
--- a/docs/reference/hooks/use-oauth-consent.mdx
+++ b/docs/reference/hooks/use-oauth-consent.mdx
@@ -216,7 +216,7 @@ The following example demonstrates how to use the `useOAuthConsent()` hook to fe
 </If>
 
 <If sdk="tanstack-react-start">
-  ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+  ```tsx {{ filename: 'src/routes/oauth-consent.tsx' }}
   import { useClerk, useOAuthConsent } from '@clerk/tanstack-react-start'
   import { createFileRoute, useLocation } from '@tanstack/react-router'
 

From 18e9ae233aae6a077990e1fc2419799b46630b8e Mon Sep 17 00:00:00 2001
From: Jeff Escalante <jescalan@users.noreply.github.com>
Date: Mon, 15 Jun 2026 18:07:57 -0400
Subject: [PATCH 5/7] Clarify OAuth org selection guidance

---
 .../configure/auth-strategies/oauth/custom-consent-page.mdx     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
index c7ec71b97e..950c78f78f 100644
--- a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
@@ -119,7 +119,7 @@ The following examples show the minimum shape of a custom consent page. They int
 
 These examples display the full redirect hostname and an expandable full URL. For a production custom flow, use a public-suffix-aware approach for root-domain summaries, handle IP addresses and `localhost` explicitly, and test long redirect URIs to make sure the real destination remains visible.
 
-These examples also do not implement organization selection. If an OAuth application can request `user:org:read`, use `<OAuthConsent />` or add an organization selector that submits the selected `organization_id` with the allow action.
+These examples also do not implement organization selection. Until Clerk exposes a public organization selector for OAuth consent flows, if an OAuth application can request `user:org:read`, use `<OAuthConsent />` or add an organization selector that submits the selected `organization_id` with the allow action.
 
 The low-level `useOAuthConsent()` examples in this guide are available for Clerk's React-based SDKs. For Astro, Vue, and Nuxt, use the prebuilt `<OAuthConsent />` component unless you are prepared to build directly against [ClerkJS](/docs/reference/javascript/overview) and maintain the consent flow yourself.
 

From f34770b799827fcb7f8e72cf56dffd9a29eda024 Mon Sep 17 00:00:00 2001
From: Sarah Soutoul <sarah@clerk.dev>
Date: Mon, 15 Jun 2026 16:46:32 -0600
Subject: [PATCH 6/7] docs review pt2

---
 .../oauth/custom-consent-page.mdx             | 99 ++++++++++---------
 .../auth-strategies/oauth/scoped-access.mdx   |  4 +-
 2 files changed, 53 insertions(+), 50 deletions(-)

diff --git a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
index 950c78f78f..8226d4d952 100644
--- a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
@@ -6,13 +6,16 @@ sdk: astro, nextjs, nuxt, react, react-router, tanstack-react-start, vue, js-fro
 
 Clerk strongly recommends using the default OAuth consent page hosted by the [Account Portal](/docs/guides/account-portal/overview). OAuth consent is a security boundary: it is where a signed-in user decides whether an OAuth [client](!oauth-client) can receive [OAuth access tokens](!oauth-access-token) and access the requested data. A custom page can weaken that boundary if it hides the requesting application, misstates the requested scopes, buries the deny action, auto-approves access, or trains users to trust an unfamiliar consent surface.
 
-Only customize the OAuth consent page when you have a specific product requirement that the Account Portal cannot satisfy. If you customize it, the safest approach is to host a page on your own application domain and render Clerk's prebuilt [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component. This keeps Clerk's consent logic, scope rendering, organization selection, form submission, and denial handling intact while letting you control the route, page styling, and surrounding page.
+**Only set up a custom OAuth consent page when you have a specific product requirement that the Account Portal cannot satisfy**. If you only need visual customization, see [Use `appearance` for visual changes](#use-appearance-for-visual-changes). If you do need a custom page, there are two ways to do this:
 
-> [!CAUTION]
-> Consent phishing is a real OAuth attack pattern. Attackers can trick users into granting a malicious app access to their account data without stealing their password. Microsoft describes consent phishing as an attack where users grant permissions to malicious cloud applications, and notes that MFA or password resets do not remediate illicit consent grants because the user authorized the app itself. See Microsoft's guidance on [protecting against consent phishing](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/protect-against-consent-phishing) and [detecting illicit consent grants](https://learn.microsoft.com/en-us/defender-office-365/detect-and-remediate-illicit-consent-grants).
+- [Use Clerk's prebuilt `<OAuthConsent />` component on your application domain](#recommended-implementation) - This is the safest and recommended option. This keeps Clerk's consent logic, scope rendering, organization selection, form submission, and denial handling intact while letting you control the route, page styling, and surrounding page.
+- [Build a custom flow](#build-a-custom-flow) - Use this only if the prebuilt component cannot support your required layout or interaction.
 
 After shipping a custom consent page, monitor [Application Logs](/docs/guides/dashboard/logs/application-logs) for OAuth grant activity. The `oauth_authorization.granted` event records successful user consent, and the `oauth_token.created` event records token issuance. Review these events for unfamiliar OAuth applications, unexpected users, or unusual grant volume.
 
+> [!CAUTION]
+> Consent phishing is a real OAuth attack pattern. Attackers can trick users into granting a malicious app access to their account data without stealing their password. Microsoft describes consent phishing as an attack where users grant permissions to malicious cloud applications, and notes that MFA or password resets do not remediate illicit consent grants because the user authorized the app itself. See Microsoft's guidance on [protecting against consent phishing](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/protect-against-consent-phishing) and [detecting illicit consent grants](https://learn.microsoft.com/en-us/defender-office-365/detect-and-remediate-illicit-consent-grants).
+
 ## Before you start
 
 Custom consent pages apply to Clerk's OAuth provider flows, where Clerk acts as the authorization service for OAuth applications that request access to user data through Clerk.
@@ -20,14 +23,14 @@ Custom consent pages apply to Clerk's OAuth provider flows, where Clerk acts as
 > [!NOTE]
 > If you're new to OAuth terminology, start with the [OAuth terminology guide](/docs/guides/configure/auth-strategies/oauth/overview#key-terminology).
 
-Before customizing the page:
+Before setting up the custom consent page:
 
 - Keep the consent screen enabled for every OAuth application. Without consent, a signed-in user who visits a valid authorization URL can grant access without seeing the request.
 - Use narrow [scopes](/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth#scopes). OAuth security guidance recommends restricting access tokens to the minimum required privileges, and Google recommends choosing the most narrowly focused scopes possible. See [RFC 9700](https://www.rfc-editor.org/rfc/rfc9700) and Google's guide to [configuring OAuth consent and choosing scopes](https://developers.google.com/workspace/guides/configure-oauth-consent).
 - Treat OAuth application branding as user-facing security information. App names, logos, client URLs, and redirect domains help users decide whether to grant access.
 - Verify the route in development and production before enabling it for real users. A broken custom consent page can block OAuth authorization flows.
 
-## What the consent page must show
+## What to show on the consent page
 
 A safe consent page must give users enough information to make an informed decision. At minimum, show:
 
@@ -37,36 +40,33 @@ A safe consent page must give users enough information to make an informed decis
 - The [resource service](!oauth-resource-service) receiving the access request.
 - The signed-in user who is granting access.
 - Every requested scope that requires consent, using clear descriptions.
-- The redirect destination the user will return to after allowing or denying access.
+- The [redirect destination](#show-the-redirect-destination-clearly) the user will return to after allowing or denying access.
 - Equally visible **Allow** and **Deny** actions.
 
-The redirect destination presentation is security-sensitive. The prebuilt consent page shows a short domain derived from the `redirect_uri`, and lets the user expand it to view the full URL. This makes it harder for an attacker to hide the real root domain inside a very long URL with many subdomains or path segments. If you build your own UI, do not show only a truncated full URL. Show a clear domain summary, provide a way to view the full `redirect_uri`, and make sure the root domain cannot be pushed out of view by long subdomains.
-
-If you use the prebuilt component, do not hide the requested scopes, redirect warning, deny action, or application identity with `appearance` overrides. If you build a custom flow, include equivalent warning copy near the allow/deny controls. For example: "`<OAuth app name>` will be able to access `<application name>` and redirect you to `<redirect domain>`. Review the requested permissions before continuing."
-
-## Recommended implementation
-
-Use Clerk's prebuilt [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component on your custom consent route. The component reads the OAuth authorization parameters from the current URL, loads consent metadata for the signed-in user, renders the requested scopes, and submits the user's decision to Clerk.
+#### Show the redirect destination clearly
 
-For example, create a route that renders `<OAuthConsent />`:
+The redirect destination presentation is security-sensitive. The prebuilt consent page shows a short domain derived from the `redirect_uri`, and lets the user expand it to view the full URL. This helps prevent attackers from hiding the real root domain inside a very long URL with many subdomains or path segments. To preserve that safety:
 
-<Include src="_partials/components/oauth-consent-examples" />
+- If you build your own UI, do not show only a truncated full URL. Show a clear domain summary, provide a way to view the full `redirect_uri`, and make sure the root domain cannot be pushed out of view by long subdomains.
+- If you use the prebuilt component, do not hide the requested scopes, redirect warning, deny action, or application identity with `appearance` overrides.
+- If you build a custom flow, include equivalent warning copy near the allow/deny controls. For example: "`<OAuth app name>` will be able to access `<application name>` and redirect you to `<redirect domain>`. Review the requested permissions before continuing."
 
-The [`<Show />`](/docs/reference/components/control/show) component renders the consent screen only for signed-in users. In a normal OAuth authorization flow, Clerk redirects signed-out users to sign-in before sending them to the consent page. If users can visit your custom consent route directly, handle signed-out users the same way you handle any other protected route in your app.
+## Recommended implementation
 
-Keep the consent route focused on the consent decision. If your application uses a shared layout with navigation, account menus, sign-in or sign-out controls, or other links, use a minimal layout for this route instead. Unrelated navigation can take the user away from the OAuth flow and cause the authorization request to fail or lose its original parameters.
+The safest way to customize the OAuth consent page is to host a custom route on your application domain and render Clerk's prebuilt [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component. The component reads the OAuth authorization parameters from the current URL, loads consent metadata for the signed-in user, renders the requested scopes, and submits the user's decision to Clerk.
 
-If your framework does not support route metadata, set the same referrer policy with a `<meta>` tag or equivalent framework API:
+The following example creates a route that renders `<OAuthConsent />`. When setting up this route:
 
-```tsx
-<meta name="referrer" content="strict-origin-when-cross-origin" />
-```
+- Render the consent screen only for signed-in users using the [`<Show />`](/docs/reference/components/control/show) component. In a normal OAuth flow, Clerk redirects signed-out users to sign-in before sending them to the consent page. If users can visit the route directly, handle signed-out users the same way you would any other protected route.
+- Keep the route focused on the consent decision. Avoid shared navigation, account menus, sign-in or sign-out controls, or other links that could take the user away from the OAuth flow.
+- Set the referrer policy to `strict-origin-when-cross-origin`. Since the consent form posts to Clerk's [Frontend API URL](!frontend-api-url), this referrer policy prevents some cross-origin form submissions from sending `Origin: null`, causing Clerk to reject the request. If your framework does not provide route metadata, set the same referrer policy with a `<meta>` tag.
 
-The referrer policy is required because the consent form posts to Clerk's [Frontend API URL](!frontend-api-url). Without it, some cross-origin form submissions can send `Origin: null`, causing Clerk to reject the request.
+<Include src="_partials/components/oauth-consent-examples" />
 
-You can style `<OAuthConsent />` with the standard [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview) prop, but keep the security content intact. The Account Portal consent page is built from Clerk's prebuilt consent component, so using `appearance` is the safer option when your goal is visual customization. Use a fully custom flow only when the prebuilt component cannot support your required layout or interaction.
+> [!TIP]
+> You can style `<OAuthConsent />` with the standard [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview) prop while keeping Clerk's consent logic intact. This is the same approach Clerk uses for the Account Portal consent page, and it is the safer option when your goal is visual customization. For more guidance, see [Use appearance for visual changes](#use-appearance-for-visual-changes).
 
-## Configure the custom route
+### Configure the custom route
 
 After you create and deploy the route, configure Clerk to send users to it during OAuth flows that require consent.
 
@@ -80,9 +80,7 @@ After you create and deploy the route, configure Clerk to send users to it durin
   Under **Component paths**, locate the the **OAuth consent** section and choose your custom location:
 
   - For a development instance, enter a path on the development host, such as `/oauth-consent`.
-  - For a production instance, enter an `https://` URL on your application domain, such as `https://example.com/oauth-consent`.
-
-  Clerk only accepts production OAuth consent URLs that use HTTPS and belong to the same registrable domain as your instance domain, such as `example.com` or a subdomain of `example.com`.
+  - For a production instance, enter an `https://` URL on your application domain, such as `https://example.com/oauth-consent`. Clerk only accepts production OAuth consent URLs that use HTTPS and belong to the same registrable domain as your instance domain, such as `example.com` or a subdomain of `example.com`.
 
   ### Keep OAuth application consent enabled
 
@@ -97,9 +95,9 @@ After you create and deploy the route, configure Clerk to send users to it durin
 
 ## Build a custom flow
 
-Building a [custom flow](!custom-flow) from low-level APIs is riskier than using `<OAuthConsent />`. Only do this if you need a layout or interaction that the prebuilt component cannot support.
+Building a [custom flow](!custom-flow) from low-level APIs is riskier than using `<OAuthConsent />`. Only choose this path if you need a layout or interaction that the prebuilt component cannot support.
 
-The custom flow needs to do the same work as the prebuilt component:
+A custom flow must do the same work as the prebuilt component:
 
 1. Read `client_id`, `redirect_uri`, `scope`, `state`, `nonce`, `code_challenge`, `code_challenge_method`, and any other OAuth authorization parameters from the incoming URL.
 1. Load consent metadata for the signed-in user with `useOAuthConsent()` or `Clerk.oauthApplication.getConsentInfo()`.
@@ -111,17 +109,35 @@ The custom flow needs to do the same work as the prebuilt component:
 1. Include `organization_id` when the user grants access for a specific organization.
 1. Preserve the user's ability to deny access. A denial returns an OAuth `access_denied` response to the OAuth client.
 
-Do not construct the [Frontend API URL](!frontend-api-url) by hand. Use `buildConsentActionUrl()` so Clerk can include the current session and development browser parameters that are required for the request.
+> [!IMPORTANT]
+> Do not construct the [Frontend API URL](!frontend-api-url) by hand. Use [`buildConsentActionUrl()`](/docs/reference/types/oauth-application#build-consent-action-url) so Clerk can include the current session and development browser parameters that are required for the request.
+
+<If notSdk={["astro", "vue", "nuxt", "js-frontend"]}>
+  The following examples show the minimum shape of a custom consent page. They intentionally keep the UI plain so you can focus on the OAuth-specific requirements. These examples have a few important limitations:
+
+  - The examples display the full redirect hostname and an expandable full URL. In production, use a public-suffix-aware approach for root-domain summaries, handle IP addresses and `localhost` explicitly, and test long redirect URIs to make sure the real destination remains visible.
+  - These examples also do not implement organization selection. Until Clerk exposes a public organization selector for OAuth consent flows, if an OAuth application can request `user:org:read`, use [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) or add an organization selector that submits the selected `organization_id` with the **Allow** action.
+
+  <Include src="_partials/components/oauth-consent-custom-flow-examples" />
+</If>
 
-The following examples show the minimum shape of a custom consent page. They intentionally keep the UI plain so you can see the OAuth-specific requirements.
+<If sdk={["astro", "vue", "nuxt", "js-frontend"]}>
+  > [!NOTE]
+  > Building a custom flow only applies to Clerk's React-based SDKs. For this SDK, use the prebuilt [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component instead, unless you build the consent flow directly  with the [JavaScript SDK](/docs/reference/javascript/overview).
+</If>
 
-<Include src="_partials/components/oauth-consent-custom-flow-examples" />
+## Use `appearance` for visual changes
 
-These examples display the full redirect hostname and an expandable full URL. For a production custom flow, use a public-suffix-aware approach for root-domain summaries, handle IP addresses and `localhost` explicitly, and test long redirect URIs to make sure the real destination remains visible.
+If your main goal is to change colors, fonts, spacing, or logos, use the [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview) prop with `<OAuthConsent />` instead of building a custom flow. This keeps Clerk's consent behavior, redirect destination presentation, organization selection, form submission, and future security updates intact.
+
+Only build a custom flow if:
 
-These examples also do not implement organization selection. Until Clerk exposes a public organization selector for OAuth consent flows, if an OAuth application can request `user:org:read`, use `<OAuthConsent />` or add an organization selector that submits the selected `organization_id` with the allow action.
+- The prebuilt component cannot support your required layout or interaction.
+- You can maintain the route as a security-sensitive surface.
+- You can show the requesting OAuth application's identity, requested scopes, and redirect destination clearly.
+- You can preserve an equally visible **Deny** action.
 
-The low-level `useOAuthConsent()` examples in this guide are available for Clerk's React-based SDKs. For Astro, Vue, and Nuxt, use the prebuilt `<OAuthConsent />` component unless you are prepared to build directly against [ClerkJS](/docs/reference/javascript/overview) and maintain the consent flow yourself.
+Do not build a custom flow to hide scopes, hide redirect destinations, remove the deny action, or auto-approve trusted clients. Instead, model trust through OAuth application configuration, narrow scopes, and administrative review. Custom consent pages should make the consent decision clearer, not easier to miss.
 
 ## Security checklist
 
@@ -140,16 +156,3 @@ Before shipping a custom consent page, verify the following:
 - The page uses `strict-origin-when-cross-origin` referrer policy.
 - The OAuth application requests only the scopes it needs.
 - Your team can audit OAuth applications and revoke suspicious grants if needed.
-
-## Prefer appearance for visual changes
-
-If your main goal is to change colors, fonts, spacing, or logos, use the [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview) prop with `<OAuthConsent />` instead of building a custom flow. This keeps Clerk's consent behavior, redirect destination presentation, organization selection, form submission, and future security updates intact.
-
-Only build a low-level custom flow if:
-
-- The prebuilt component cannot support your required layout or interaction.
-- You can maintain the route as a security-sensitive surface.
-- You can show the requesting OAuth application's identity, requested scopes, and redirect destination clearly.
-- You can preserve an equally visible deny action.
-
-Do not build a custom flow to hide scopes, hide redirect destinations, remove the deny action, or auto-approve trusted clients. Instead, model trust through OAuth application configuration, narrow scopes, and administrative review. Custom consent pages should make the consent decision clearer, not easier to miss.
diff --git a/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx b/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx
index 5dac5ca9b6..d72754a050 100644
--- a/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/scoped-access.mdx
@@ -14,7 +14,7 @@ Before diving into implementations details, it's important to understand the dif
 - **Resource service (or Service Provider, SP)**: The service that holds the data that the [client](!oauth-client) wants to access. In this example, this would be **your own application** that uses Clerk for authentication and route protection.
 
 > [!NOTE]
-> If you would like to know more about the terminology around OAuth, check out the [OAuth terminology guide](/docs/guides/configure/auth-strategies/oauth/overview#key-terminology).
+> If you're new to OAuth terminology, start with the [OAuth terminology guide](/docs/guides/configure/auth-strategies/oauth/overview#key-terminology).
 
 This guide provides step-by-step instructions on how to build OAuth scoped access into a Clerk app.
 
@@ -65,7 +65,7 @@ This guide provides step-by-step instructions on how to build OAuth scoped acces
 
   Once this is complete, you'll be able to see the OAuth flow begin. If you are not currently signed in, you'll first be presented with a sign in screen. After signing in, Clerk will redirect to an OAuth consent screen, showing the requested scopes and asking for your consent.
 
-  > [!NOTE]
+  > [!IMPORTANT]
   > The consent screen uses the scopes passed in the authorization request to inform the user exactly what they're granting access to, and to whom.
   >
   > By default, the consent screen is shown for all newly created OAuth apps, but this can be disabled in each app's settings [in the Clerk Dashboard](https://dashboard.clerk.com/~/oauth-applications), although not recommended. Learn more about [how Clerk's OAuth consent screen works](/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth#consent-screen-management).

From 66684f26d9d44f1eda06b147593e0066a4cae3d9 Mon Sep 17 00:00:00 2001
From: Sarah Soutoul <sarah@clerk.dev>
Date: Tue, 16 Jun 2026 10:12:11 -0600
Subject: [PATCH 7/7] Refinements based on changes

---
 .../oauth/custom-consent-page.mdx             | 58 +++++++++----------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
index 8226d4d952..b6697f8150 100644
--- a/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
+++ b/docs/guides/configure/auth-strategies/oauth/custom-consent-page.mdx
@@ -11,7 +11,7 @@ Clerk strongly recommends using the default OAuth consent page hosted by the [Ac
 - [Use Clerk's prebuilt `<OAuthConsent />` component on your application domain](#recommended-implementation) - This is the safest and recommended option. This keeps Clerk's consent logic, scope rendering, organization selection, form submission, and denial handling intact while letting you control the route, page styling, and surrounding page.
 - [Build a custom flow](#build-a-custom-flow) - Use this only if the prebuilt component cannot support your required layout or interaction.
 
-After shipping a custom consent page, monitor [Application Logs](/docs/guides/dashboard/logs/application-logs) for OAuth grant activity. The `oauth_authorization.granted` event records successful user consent, and the `oauth_token.created` event records token issuance. Review these events for unfamiliar OAuth applications, unexpected users, or unusual grant volume.
+After you create and deploy your custom consent route, you'll need to [configure the custom route](#configure-the-custom-route) so Clerk sends users to it during OAuth flows that require consent. You should also monitor [Application Logs](/docs/guides/dashboard/logs/application-logs) for OAuth grant activity. The `oauth_authorization.granted` event records successful user consent, and the `oauth_token.created` event records token issuance. Review these events for unfamiliar OAuth applications, unexpected users, or unusual grant volume.
 
 > [!CAUTION]
 > Consent phishing is a real OAuth attack pattern. Attackers can trick users into granting a malicious app access to their account data without stealing their password. Microsoft describes consent phishing as an attack where users grant permissions to malicious cloud applications, and notes that MFA or password resets do not remediate illicit consent grants because the user authorized the app itself. See Microsoft's guidance on [protecting against consent phishing](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/protect-against-consent-phishing) and [detecting illicit consent grants](https://learn.microsoft.com/en-us/defender-office-365/detect-and-remediate-illicit-consent-grants).
@@ -66,33 +66,6 @@ The following example creates a route that renders `<OAuthConsent />`. When sett
 > [!TIP]
 > You can style `<OAuthConsent />` with the standard [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview) prop while keeping Clerk's consent logic intact. This is the same approach Clerk uses for the Account Portal consent page, and it is the safer option when your goal is visual customization. For more guidance, see [Use appearance for visual changes](#use-appearance-for-visual-changes).
 
-### Configure the custom route
-
-After you create and deploy the route, configure Clerk to send users to it during OAuth flows that require consent.
-
-<Steps>
-  ### Open path settings
-
-  In the Clerk Dashboard, navigate to the [**Paths**](https://dashboard.clerk.com/~/paths) page of your application.
-
-  ### Set the OAuth consent location
-
-  Under **Component paths**, locate the the **OAuth consent** section and choose your custom location:
-
-  - For a development instance, enter a path on the development host, such as `/oauth-consent`.
-  - For a production instance, enter an `https://` URL on your application domain, such as `https://example.com/oauth-consent`. Clerk only accepts production OAuth consent URLs that use HTTPS and belong to the same registrable domain as your instance domain, such as `example.com` or a subdomain of `example.com`.
-
-  ### Keep OAuth application consent enabled
-
-  Navigate to [**OAuth applications**](https://dashboard.clerk.com/~/oauth-applications) and confirm that the consent screen is enabled for every OAuth application that can use the custom route.
-
-  If [dynamic client registration](/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth#dynamic-client-registration) is enabled, Clerk enforces the consent screen and does not allow it to be disabled.
-
-  ### Test an authorization request
-
-  Start an OAuth authorization flow for one of your OAuth applications. If the user is signed out, Clerk redirects to sign-in first, then redirects to your custom consent route with the original OAuth parameters. After the user allows or denies access, Clerk continues the OAuth flow and redirects back to the OAuth client's `redirect_uri`.
-</Steps>
-
 ## Build a custom flow
 
 Building a [custom flow](!custom-flow) from low-level APIs is riskier than using `<OAuthConsent />`. Only choose this path if you need a layout or interaction that the prebuilt component cannot support.
@@ -123,9 +96,36 @@ A custom flow must do the same work as the prebuilt component:
 
 <If sdk={["astro", "vue", "nuxt", "js-frontend"]}>
   > [!NOTE]
-  > Building a custom flow only applies to Clerk's React-based SDKs. For this SDK, use the prebuilt [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component instead, unless you build the consent flow directly  with the [JavaScript SDK](/docs/reference/javascript/overview).
+  > The low-level custom flow documented in this section is only available for Clerk's React-based SDKs. If you're using this SDK, use the prebuilt [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component instead.
 </If>
 
+## Configure the custom route
+
+After you create and deploy your custom consent route, configure Clerk to send users to it during OAuth flows that require consent. This applies whether you use the prebuilt [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent) component or build a fully custom flow.
+
+<Steps>
+  ### Open path settings
+
+  In the Clerk Dashboard, navigate to the [**Paths**](https://dashboard.clerk.com/~/paths) page of your application.
+
+  ### Set the OAuth consent location
+
+  Under **Component paths**, locate the the **OAuth consent** section and choose your custom location:
+
+  - For a development instance, enter a path on the development host, such as `/oauth-consent`.
+  - For a production instance, enter an `https://` URL on your application domain, such as `https://example.com/oauth-consent`. Clerk only accepts production OAuth consent URLs that use HTTPS and belong to the same registrable domain as your instance domain, such as `example.com` or a subdomain of `example.com`.
+
+  ### Keep OAuth application consent enabled
+
+  Navigate to [**OAuth applications**](https://dashboard.clerk.com/~/oauth-applications) and confirm that the consent screen is enabled for every OAuth application that can use the custom route.
+
+  If [dynamic client registration](/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth#dynamic-client-registration) is enabled, Clerk enforces the consent screen and does not allow it to be disabled.
+
+  ### Test an authorization request
+
+  Start an OAuth authorization flow for one of your OAuth applications. If the user is signed out, Clerk redirects to sign-in first, then redirects to your custom consent route with the original OAuth parameters. After the user allows or denies access, Clerk continues the OAuth flow and redirects back to the OAuth client's `redirect_uri`.
+</Steps>
+
 ## Use `appearance` for visual changes
 
 If your main goal is to change colors, fonts, spacing, or logos, use the [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview) prop with `<OAuthConsent />` instead of building a custom flow. This keeps Clerk's consent behavior, redirect destination presentation, organization selection, form submission, and future security updates intact.