Add OAuthConsent and useOAuthConsent docs

docs/_partials/hooks/hook-list.mdx

@@ -1,6 +1,7 @@
 - [`useUser()`](/docs/reference/hooks/use-user)
 - [`useClerk()`](/docs/reference/hooks/use-clerk)
 - [`useAuth()`](/docs/reference/hooks/use-auth)
+- [`useOAuthConsent()`](/docs/reference/hooks/use-oauth-consent)
 - [`useSignIn()`](/docs/reference/hooks/use-sign-in)
 - [`useSignUp()`](/docs/reference/hooks/use-sign-up)
 - [`useWaitlist()`](/docs/reference/hooks/use-waitlist)

docs/_partials/oauth-consent/callout.mdx

@@ -0,0 +1,2 @@
+> [!IMPORTANT]
+> Pages that host OAuth consent flows must set the referrer policy to `strict-origin-when-cross-origin`. This ensures the cross-origin `POST` request to FAPI includes the `Origin` header and Clerk can validate the CSRF token.

docs/manifest.json

@@ -2309,6 +2309,10 @@
                           "title": "`useAuth()`",
                           "href": "/docs/reference/hooks/use-auth"
                         },
+                        {
+                          "title": "`useOAuthConsent()`",
+                          "href": "/docs/reference/hooks/use-oauth-consent"
+                        },
                         {
                           "title": "`useSignIn()`",
                           "href": "/docs/reference/hooks/use-sign-in"
@@ -2611,6 +2615,18 @@
                           "title": "Metadata types",
                           "href": "/docs/reference/types/metadata"
                         },
+                        {
+                          "title": "`OAuthApplication`",
+                          "href": "/docs/reference/types/oauth-application"
+                        },
+                        {
+                          "title": "`OAuthConsentInfo`",
+                          "href": "/docs/reference/types/oauth-consent-info"
+                        },
+                        {
+                          "title": "`OAuthConsentScope`",
+                          "href": "/docs/reference/types/oauth-consent-scope"
+                        },
                         {
                           "title": "`OrganizationCreationDefaults`",
                           "href": "/docs/reference/types/organization-creation-defaults"
@@ -3627,6 +3643,10 @@
                           "title": "`<GoogleOneTap />`",
                           "href": "/docs/reference/components/authentication/google-one-tap"
                         },
+                        {
+                          "title": "`<OAuthConsent />`",
+                          "href": "/docs/reference/components/authentication/oauth-consent"
+                        },
                         {
                           "title": "`<TaskChooseOrganization />`",
                           "href": "/docs/reference/components/authentication/task-choose-organization"

docs/reference/components/authentication/oauth-consent.mdx

@@ -0,0 +1,281 @@
+---
+title: '`<OAuthConsent />` component'
+description: Clerk's <OAuthConsent /> component renders an OAuth consent screen for authenticated users.
+sdk: astro, nextjs, nuxt, react, react-router, tanstack-react-start, vue, js-frontend
+---
+
+The `<OAuthConsent />` component renders an OAuth consent screen for authenticated users after they are redirected to the OAuth authorization page. It retrieves the OAuth application's consent metadata and displays the requested scopes, allowing the user to approve or deny access.
+
+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.
+
+> [!IMPORTANT]
+> `<OAuthConsent />` only renders for authenticated users. If the user is signed out, the component will not be displayed.
+
+<Include src="_partials/oauth-consent/callout" />
+
+## Example
+
+The following example includes a basic implementation of the `<OAuthConsent />` component. You can use this as a starting point for your own implementation.
+
+<If sdk="nextjs">
+  ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
+  import { OAuthConsent } from '@clerk/nextjs'
+
+  export const metadata: Metadata = {
+    referrer: 'strict-origin-when-cross-origin',
+  }
+
+  export default function Page() {
+    return <OAuthConsent />
+  }
+  ```
+</If>
+
+<If sdk="react">
+  ```tsx {{ filename: 'src/routes/oauth-consent.tsx' }}
+  import { OAuthConsent } from '@clerk/react'
+
+  export const meta = () => [
+    {
+      name: 'referrer',
+      content: 'strict-origin-when-cross-origin',
+    },
+  ]
+
+  export default function OAuthConsentPage() {
+    return <OAuthConsent />
+  }
+  ```
+</If>
+
+<If sdk="react-router">
+  ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+  import type { Route } from './+types/oauth-consent'
+  import { OAuthConsent } from '@clerk/react-router'
+
+  export const meta: Route.MetaFunction = () => [
+    {
+      name: 'referrer',
+      content: 'strict-origin-when-cross-origin',
+    },
+  ]
+
+  export default function OAuthConsentPage() {
+    return <OAuthConsent />
+  }
+  ```
+</If>
+
+<If sdk="tanstack-react-start">
+  ```tsx {{ filename: 'app/routes/oauth-consent.tsx' }}
+  import { OAuthConsent } 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 <OAuthConsent />
+  }
+  ```
+</If>
+
+<If sdk="astro">
+  ```astro {{ filename: 'pages/oauth-consent.astro' }}
+  ---
+  import { OAuthConsent } from '@clerk/astro/components'
+  ---
+
+  <html lang="en">
+    <head>
+      <meta name="referrer" content="strict-origin-when-cross-origin" />
+    </head>
+    <body>
+      <OAuthConsent />
+    </body>
+  </html>
+  ```
+</If>
+
+<If sdk="vue">
+  ```vue {{ filename: 'oauth-consent.vue' }}
+  <script setup lang="ts">
+  import { OAuthConsent } from '@clerk/vue'
+  import { useHead } from '@unhead/vue'
+
+  useHead({
+    meta: [
+      {
+        name: 'referrer',
+        content: 'strict-origin-when-cross-origin',
+      },
+    ],
+  })
+  </script>
+
+  <template>
+    <OAuthConsent />
+  </template>
+  ```
+</If>
+
+<If sdk="nuxt">
+  ```vue {{ filename: 'oauth-consent.vue' }}
+  <script setup lang="ts">
+  // Components are automatically imported
+  useHead({
+    meta: [
+      {
+        name: 'referrer',
+        content: 'strict-origin-when-cross-origin',
+      },
+    ],
+  })
+  </script>
+
+  <template>
+    <OAuthConsent />
+  </template>
+  ```
+</If>
+
+<If sdk="js-frontend">
+  ## Usage with JavaScript
+
+  Add the following `<meta>` tag to the page that hosts the OAuth consent screen:
+
+  ```html {{ filename: 'index.html' }}
+  <meta name="referrer" content="strict-origin-when-cross-origin" />
+  ```
+
+  The following methods available on an instance of the [`Clerk`](/docs/reference/objects/clerk) class are used to render and control the `<OAuthConsent />` component:
+
+  - [`mountOAuthConsent()`](#mount-o-auth-consent)
+  - [`unmountOAuthConsent()`](#unmount-o-auth-consent)
+
+  The following examples assume that you have followed the [quickstart](/docs/js-frontend/getting-started/quickstart) in order to add Clerk to your JavaScript application.
+
+  ### `mountOAuthConsent()`
+
+  Render the `<OAuthConsent />` component to an HTML `<div>` element.
+
+  ```typescript
+  function mountOAuthConsent(node: HTMLDivElement, props?: OAuthConsentProps): void
+  ```
+
+  #### `mountOAuthConsent()` params
+
+  <Properties>
+    - `node`
+    - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement)
+
+    The container `<div>` element used to render the `<OAuthConsent />` component.
+
+    ---
+
+    - `props?`
+    - [`OAuthConsentProps`](#properties)
+
+    The properties to pass to the `<OAuthConsent />` component.
+  </Properties>
+
+  #### `mountOAuthConsent()` usage
+
+  ```js {{ filename: 'main.js', mark: [15] }}
+  import { Clerk } from '@clerk/clerk-js'
+
+  const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
+
+  const clerk = new Clerk(clerkPubKey)
+  await clerk.load()
+
+  document.getElementById('app').innerHTML = `
+    <div id="oauth-consent"></div>
+  `
+
+  const oauthConsentDiv = document.getElementById('oauth-consent')
+
+  clerk.mountOAuthConsent(oauthConsentDiv)
+  ```
+
+  ### `unmountOAuthConsent()`
+
+  Unmount and run cleanup on an existing `<OAuthConsent />` component instance.
+
+  ```typescript
+  function unmountOAuthConsent(node: HTMLDivElement): void
+  ```
+
+  #### `unmountOAuthConsent()` params
+
+  <Properties>
+    - `node`
+    - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement)
+
+    The container `<div>` element with a rendered `<OAuthConsent />` component instance.
+  </Properties>
+
+  #### `unmountOAuthConsent()` usage
+
+  ```js {{ filename: 'main.js', mark: [19] }}
+  import { Clerk } from '@clerk/clerk-js'
+
+  const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
+
+  const clerk = new Clerk(clerkPubKey)
+  await clerk.load()
+
+  document.getElementById('app').innerHTML = `
+    <div id="oauth-consent"></div>
+  `
+
+  const oauthConsentDiv = document.getElementById('oauth-consent')
+
+  clerk.mountOAuthConsent(oauthConsentDiv)
+
+  // ...
+
+  clerk.unmountOAuthConsent(oauthConsentDiv)
+  ```
+</If>
+
+## Properties
+
+All props are optional.
+
+<Properties>
+  - `appearance?`
+  - <code>[Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined</code>
+
+  An object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/account-portal/overview) pages.
+
+  ---
+
+  - `fallback?`
+  - `ReactNode`
+
+  An element to be rendered while the component is mounting.
+
+  ---
+
+  - `oauthClientId?`
+  - `string`
+
+  Override the OAuth client ID. By default, Clerk reads this from the `client_id` query parameter in the current URL.
+
+  ---
+
+  - `scope?`
+  - `string`
+
+  Override the OAuth scope. By default, Clerk reads this from the `scope` query parameter in the current URL.
+</Properties>

docs/reference/components/overview.mdx

@@ -11,6 +11,7 @@ Clerk offers a comprehensive suite of components designed to seamlessly integrat
 - [`<SignIn />`](/docs/reference/components/authentication/sign-in)
 - [`<SignUp />`](/docs/reference/components/authentication/sign-up)
 - [`<GoogleOneTap />`](/docs/reference/components/authentication/google-one-tap)
+- [`<OAuthConsent />`](/docs/reference/components/authentication/oauth-consent)
 - [`<TaskChooseOrganization />`](/docs/reference/components/authentication/task-choose-organization)
 - [`<TaskResetPassword />`](/docs/reference/components/authentication/task-reset-password)
 - [`<TaskSetupMFA />`](/docs/reference/components/authentication/task-setup-mfa)