Merge branch 'main' of github.com:clerk/clerk-docs

CONTRIBUTING.md

@@ -396,8 +396,8 @@ interface CodeBlockProps {
 
 You can use the following shortcodes within a code block to inject information from the user's current Clerk instance:
 
-- `{{pub_key}}` – Publishable key
-- `{{secret}}` – Secret key
+- `{{pub_key}}` – Publishable Key
+- `{{secret}}` – Secret Key
 - `{{fapi_url}}` – Frontend API URL
 
 ````mdx
@@ -407,7 +407,7 @@ CLERK_SECRET_KEY={{secret}}
 ```
 ````
 
-The video below shows what this example looks like once rendered. Notice the eye icon on the code block that once clicked on, reveals the user's secret key.
+The video below shows what this example looks like once rendered. Notice the eye icon on the code block that once clicked on, reveals the user's Secret Key.
 
 https://github.com/clerk/clerk-docs/assets/2615508/c1f3fc23-5581-481c-a89c-10c6a04b8536
 
@@ -439,18 +439,18 @@ console.log('ignored')
 
 ### `<Steps />`
 
-The `<Steps />` component is used to number a set of instructions with an outcome. It uses the highest heading available in the component to denote each step. Can be used with `h3` headings.
+The `<Steps />` component is used to number a set of instructions with an outcome. It uses the highest heading available in the component to denote each step. Can be used with `h2` and `h3` headings.
 
 ```mdx
 <Steps>
 
-### Step 1
+## Step 1
 
 Do these actions to complete Step 1.
 
-### Another step
+## Another step
 
-#### A heading inside a step
+### A heading inside a step
 
 Do these actions to complete Step 2.
 
@@ -468,7 +468,7 @@ A callout draws attention to something learners should slow down and read.
 > [!NOTE]
 > Callouts can be distracting when people are quickly skimming a page. So only use them if the information absolutely should not be missed!
 
-Callout syntax is based on [GitHub's markdown "alerts"](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts). To add a callout, use a special blockquote line specifying the callout type, followed by the callout information in a standard blockquote. Five types of callouts are available:
+Callout syntax is based on [GitHub's markdown "alerts"](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts). To add a callout, use a special blockquote line specifying the callout type, followed by the callout information in a standard blockquote. The following types of callouts are available:
 
 ```mdx
 > [!NOTE]
@@ -485,11 +485,34 @@ Callout syntax is based on [GitHub's markdown "alerts"](https://docs.github.com/
 
 > [!CAUTION]
 > Advises about risks or negative outcomes of certain actions.
+
+> [!QUIZ]
+> An opportunity for users to check their understanding.
 ```
 
 The image below shows what this example looks like once rendered.
 
-![An example of each callout type: NOTE, TIP, IMPORTANT, WARNING, CAUTION](/.github/media/callouts.png)
+![An example of each callout type: NOTE, TIP, IMPORTANT, WARNING, CAUTION, QUIZ](/.github/media/callouts.png)
+
+You can optionally specify an `id` attribute for a callout which allows for direct linking, e.g. `/docs/example#useful-info`:
+
+```mdx
+> [!NOTE useful-info]
+> Useful information that users should know, even when skimming content.
+```
+
+You can create a collapsible section within a callout by using a thematic break (`---`). Content following the break is hidden by default and can be toggled by the user:
+
+```mdx
+> [!QUIZ]
+> Why does handshake do a redirect? Why can’t it make a fetch request to FAPI and get a new token back that way? Not needing to redirect would be a better user experience.
+>
+> ---
+>
+> Occaecati esse ut iure in quam praesentium nesciunt nemo. Repellat aperiam eaque quia. Aperiam voluptatem consequuntur numquam tenetur. Quibusdam repellat modi qui dolor ducimus ut neque adipisci dolorem. Voluptates dolores nisi est fuga.
+```
+
+![An example of a collapsible section inside a quiz callout](/.github/media/callout-details.png)
 
 ### `<CodeBlockTabs />`
 
@@ -575,7 +598,7 @@ The `<TutorialHero />` component is used at the beginning of a tutorial-type con
 
 - Install `@clerk/nextjs`
 - Set up your environment keys to test your app locally
-- Add `<ClerkProvider />` to your application
+- Add `<ClerkProvider>` to your application
 - Use Clerk middleware to implement route-specific authentication
 - Create a header with Clerk components for users to sign in and out
 

docs/_partials/authenticate-req.mdx

@@ -0,0 +1,23 @@
+```tsx
+import { createClerkClient } from '@clerk/backend'
+
+export async function GET(req: Request) {
+  const clerkClient = createClerkClient({
+    secretKey: process.env.CLERK_SECRET_KEY,
+    publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+  })
+
+  const { isSignedIn } = await clerkClient.authenticateRequest(req, {
+    jwtKey: process.env.CLERK_JWT_KEY,
+    authorizedParties: ['https://example.com'],
+  })
+
+  if (!isSignedIn) {
+    return Response.json({ status: 401 })
+  }
+
+  // Add logic to perform protected actions
+
+  return Response.json({ message: 'This is a reply' })
+}
+```

docs/_partials/clerk-provider.mdx

@@ -0,0 +1 @@
+The [`<ClerkProvider>`](/docs/components/clerk-provider) component provides session and user context to Clerk's hooks and components. It's recommended to wrap your entire app at the entry point with `<ClerkProvider>` to make authentication globally accessible. See the [reference docs](/docs/components/clerk-provider) for other configuration options.

docs/_partials/expo/oauth-custom-flow.mdx

@@ -0,0 +1,58 @@
+The following example demonstrates how to create a custom OAuth sign-in flow for [Google accounts](/docs/authentication/social-connections/google).
+
+```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }}
+import React from 'react'
+import * as WebBrowser from 'expo-web-browser'
+import { Text, View, Button } from 'react-native'
+import { Link } from 'expo-router'
+import { useOAuth } from '@clerk/clerk-expo'
+import * as Linking from 'expo-linking'
+
+export const useWarmUpBrowser = () => {
+  React.useEffect(() => {
+    // Warm up the android browser to improve UX
+    // https://docs.expo.dev/guides/authentication/#improving-user-experience
+    void WebBrowser.warmUpAsync()
+    return () => {
+      void WebBrowser.coolDownAsync()
+    }
+  }, [])
+}
+
+WebBrowser.maybeCompleteAuthSession()
+
+export default function Page() {
+  useWarmUpBrowser()
+
+  const { startOAuthFlow } = useOAuth({ strategy: 'oauth_google' })
+
+  const onPress = React.useCallback(async () => {
+    try {
+      const { createdSessionId, signIn, signUp, setActive } = await startOAuthFlow({
+        redirectUrl: Linking.createURL('/dashboard', { scheme: 'myapp' }),
+      })
+
+      // If sign in was successful, set the active session
+      if (createdSessionId) {
+        setActive!({ session: createdSessionId })
+      } else {
+        // Use signIn or signUp returned from startOAuthFlow
+        // for next steps, such as MFA
+      }
+    } catch (err) {
+      // See https://clerk.com/docs/custom-flows/error-handling
+      // for more info on error handling
+      console.error(JSON.stringify(err, null, 2))
+    }
+  }, [])
+
+  return (
+    <View>
+      <Link href="/">
+        <Text>Home</Text>
+      </Link>
+      <Button title="Sign in with Google" onPress={onPress} />
+    </View>
+  )
+}
+```

docs/_partials/react-hooks.mdx

@@ -0,0 +1,9 @@
+- [`useUser()`](/docs/references/react/use-user){{ target: '_blank' }}
+- [`useClerk()`](/docs/references/react/use-clerk){{ target: '_blank' }}
+- [`useAuth()`](/docs/references/react/use-auth){{ target: '_blank' }}
+- [`useSignIn()`](/docs/references/react/use-sign-in){{ target: '_blank' }}
+- [`useSignUp()`](/docs/references/react/use-sign-up){{ target: '_blank' }}
+- [`useSession()`](/docs/references/react/use-session){{ target: '_blank' }}
+- [`useSessionList()`](/docs/references/react/use-session-list){{ target: '_blank' }}
+- [`useOrganization()`](/docs/references/react/use-organization){{ target: '_blank' }}
+- [`useOrganizationList()`](/docs/references/react/use-organization-list){{ target: '_blank' }}

docs/_partials/reverification-route-handler.mdx

@@ -0,0 +1,20 @@
+The following example uses the [`has()`](/docs/references/nextjs/auth-object#has) helper to check if the user has verified their credentials within a specific time period. The `strict` configuration sets the time period to 10 minutes. If the user hasn't verified their credentials within 10 minutes, the `reverificationErrorResponse` utility is used to return an error.
+
+```tsx {{ filename: 'app/api/reverification-example/route.ts' }}
+import { auth, reverificationErrorResponse } from '@clerk/nextjs/server'
+
+export const POST = async (req: Request) => {
+  const { has } = await auth()
+
+  // Check if the user has *not* verified their credentials within the past 10 minutes.
+  const shouldUserRevalidate = !has({ reverification: 'strict' })
+
+  // If the user hasn't reverified, return an error with the matching configuration (e.g., `strict`)
+  if (shouldUserRevalidate) {
+    return reverificationErrorResponse('strict')
+  }
+
+  // If the user has verified credentials, return a successful response
+  return new Response({ success: true })
+}
+```

docs/_partials/token-size-callout.mdx

@@ -0,0 +1,4 @@
+> [!CAUTION]
+> The entire session token has a max size of 4kb. Exceeding this size can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications.
+> It's recommended to move particularly large claims out of the JWT and fetch these using a separate API call from your backend.
+> [Learn more](/docs/backend-requests/resources/session-tokens#size-limitations).

docs/advanced-usage/satellite-domains.mdx

@@ -41,9 +41,8 @@ To access authentication state from a satellite domain, users will be transparen
 
   To add a satellite domain:
 
-  1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=domains)
-  1. In the navigation sidebar, select **Domains**.
-  1. Select the **Satellite** tab.
+  1. In the Clerk Dashboard, navigate to the [**Domains**](https://dashboard.clerk.com/last-active?path=domains) page.
+  1. Select the **Satellites** tab.
   1. Select the **Add satellite domain** button and follow the instructions provided.
 
   For the purposes of this guide:
@@ -65,11 +64,11 @@ To access authentication state from a satellite domain, users will be transparen
       You can configure your satellite application by setting the following environment variables:
 
       > [!NOTE]
-      > In development, your publishable and secret keys will start with `pk_test_` and `sk_test` respectively.
+      > In development, your Publishable and Secret Keys will start with `pk_test_` and `sk_test` respectively.
 
       - In the `.env` file associated with your primary domain:
 
-        <CodeBlockTabs type="framework" options={["Next.js", "Remix"]}>
+        <CodeBlockTabs options={["Next.js", "Remix"]}>
           ```env {{ filename: '.env.local' }}
           NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}}
           CLERK_SECRET_KEY={{secret}}
@@ -85,15 +84,15 @@ To access authentication state from a satellite domain, users will be transparen
         </CodeBlockTabs>
       - In the `.env` file associated with your other (satellite) domain:
 
-        <CodeBlockTabs type="framework" options={["Next.js", "Remix"]}>
+        <CodeBlockTabs options={["Next.js", "Remix"]}>
           ```env {{ filename: '.env.local' }}
           NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}}
           CLERK_SECRET_KEY={{secret}}
           NEXT_PUBLIC_CLERK_IS_SATELLITE=true
           # Production example:
           NEXT_PUBLIC_CLERK_DOMAIN=satellite.dev
           NEXT_PUBLIC_CLERK_SIGN_IN_URL=https://primary.dev/sign-in
-          NEXT_PUBLIC_CLERK_SIGN_UP_URL=https://primary.dev/sign-up 
+          NEXT_PUBLIC_CLERK_SIGN_UP_URL=https://primary.dev/sign-up
 
           # Development example:
           # NEXT_PUBLIC_CLERK_DOMAIN=http://localhost:3001
@@ -116,7 +115,7 @@ To access authentication state from a satellite domain, users will be transparen
           # CLERK_SIGN_UP_URL=http://localhost:3000/sign-up
           ```
         </CodeBlockTabs>
-      - You will also need to add the `allowedRedirectOrigins` property to `<ClerkProvider />` on your _primary domain app_ to ensure that the redirect back from primary to satellite domain works correctly. For example:
+      - You will also need to add the `allowedRedirectOrigins` property to `<ClerkProvider>` on your _primary domain app_ to ensure that the redirect back from primary to satellite domain works correctly. For example:
 
         <CodeBlockTabs options={["Development", "Production"]}>
           ```tsx {{ filename: 'app/layout.tsx' }}
@@ -153,15 +152,15 @@ To access authentication state from a satellite domain, users will be transparen
       You can configure your satellite application by setting the following properties:
 
       - `isSatellite` - Defines the app as a satellite app when `true`.
-      - `domain` - Sets the domain of the satellite application. This is required since we cannot figure this out by your publishable key, since it is the same for all of your multi-domain apps.
+      - `domain` - Sets the domain of the satellite application. This is required since we cannot figure this out by your Publishable Key, since it is the same for all of your multi-domain apps.
       - `signInUrl` - This url will be used when signing in on your satellite application and needs to point to your primary application. This option is optional for production instances and required for development instances.
       - `signUpUrl` - This url will be used for signing up on your satellite application and needs to point to your primary application. This option is optional for production instances and required for development instances.
       - `allowedRedirectOrigins` - This is a list of origins that are allowed to redirect back to from the primary domain.
 
       > [!TIP]
       > The `URL` parameter that can be passed to `isSatellite` and `domain` is the request url for server-side usage or the current location for client usage.
 
-      <Tabs type="framework" items={["Next.js", "Remix"]}>
+      <Tabs items={["Next.js", "Remix"]}>
         <Tab>
           In a Next.js application, you must set the properties in the [`<ClerkProvider>`](/docs/components/clerk-provider) component _and_ in your [`clerkMiddleware()`](/docs/references/nextjs/clerk-middleware#clerk-middleware).
 

docs/advanced-usage/using-proxies.mdx

@@ -35,7 +35,7 @@ When using a proxy, all requests to the Frontend API will be made through your d
   Three additional headers must be set
 
   - `Clerk-Proxy-Url`: Needs to have the full proxy URL.
-  - `Clerk-Secret-Key`: The secret key for your Clerk instance.
+  - `Clerk-Secret-Key`: The Secret Key for your Clerk instance.
   - `X-Forwarded-For`: The IP address of the original client making the request.
 
   #### Example configuration
@@ -158,9 +158,8 @@ When using a proxy, all requests to the Frontend API will be made through your d
 
   <Tabs items={["Dashboard", "Backend API"]}>
     <Tab>
-      1. In the Clerk Dashboard, go to the **[Domains](https://dashboard.clerk.com/last-active?path=domains)** page.
-      1. Navigate to the **Frontend API** section.
-      1. Select the **Advanced** drop down.
+      1. In the Clerk Dashboard, navigate to the **[Domains](https://dashboard.clerk.com/last-active?path=domains)** page.
+      1. In the **Frontend API** section, select the **Advanced** dropdown.
       1. In the **Proxy URL** field, enter your proxy URL. The proxy URL must be a valid URL and resolve correctly.
     </Tab>
 
@@ -187,7 +186,7 @@ When using a proxy, all requests to the Frontend API will be made through your d
 
   To configure your proxy setup using environment variables, your `.env.local` file should look like this:
 
-  <Tabs type="framework" items={["Next.js", "Remix", "JavaScript"]}>
+  <Tabs items={["Next.js", "Remix", "JavaScript"]}>
     <Tab>
       ```env {{ filename: '.env.local' }}
       NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}}
@@ -220,39 +219,23 @@ When using a proxy, all requests to the Frontend API will be made through your d
 
   #### Properties in your application
 
-  <Tabs type="framework" items={["Next.js", "Remix", "JavaScript"]}>
+  <Tabs items={["Next.js", "Remix", "JavaScript"]}>
     <Tab>
       To configure your proxy setup using properties in your Next.js application, set the `proxyUrl` property on the [`<ClerkProvider>`](/docs/components/clerk-provider) component.
 
-      <CodeBlockTabs type="router" options={["App Router", "Pages Router"]}>
-        ```tsx {{ filename: 'app/layout.tsx', mark: [5] }}
-        import { ClerkProvider } from '@clerk/nextjs'
-
-        export default function RootLayout({ children }: { children: React.ReactNode }) {
-          return (
-            <ClerkProvider proxyUrl="https://app.dev/__clerk">
-              <html lang="en">
-                <body>{children}</body>
-              </html>
-            </ClerkProvider>
-          )
-        }
-        ```
-
-        ```tsx {{ filename: '_app.tsx', mark: [6] }}
-        import { ClerkProvider } from '@clerk/nextjs'
-        import type { AppProps } from 'next/app'
+      ```tsx {{ filename: 'app/layout.tsx', mark: [5] }}
+      import { ClerkProvider } from '@clerk/nextjs'
 
-        function MyApp({ Component, pageProps }: AppProps) {
-          return (
-            <ClerkProvider proxyUrl="https://app.dev/__clerk" {...pageProps}>
-              <Component {...pageProps} />
-            </ClerkProvider>
-          )
-        }
-        export default MyApp
-        ```
-      </CodeBlockTabs>
+      export default function RootLayout({ children }: { children: React.ReactNode }) {
+        return (
+          <ClerkProvider proxyUrl="https://app.dev/__clerk">
+            <html lang="en">
+              <body>{children}</body>
+            </html>
+          </ClerkProvider>
+        )
+      }
+      ```
     </Tab>
 
     <Tab>
@@ -288,7 +271,7 @@ When using a proxy, all requests to the Frontend API will be made through your d
       ```js {{ filename: 'main.js' }}
       import { Clerk } from '@clerk/clerk-js'
 
-      // Initialize Clerk with your Clerk publishable key
+      // Initialize Clerk with your Clerk Publishable Key
       const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
 
       const clerk = new Clerk(clerkPubKey)