@@ -67,7 +67,7 @@
// Send the user an email with the verification link
startEmailLinkFlow({ redirectUrl: `${protocol}//${host}/account/add-email/verify` })
} catch (err) {
- // See https://clerk.com/docs/custom-flows/error-handling
+ // See https://clerk.com/docs/guides/development/custom-flows/error-handling
// for more info on error handling
console.error(JSON.stringify(err, null, 2))
setError('An error occurred.')
diff --git a/docs/_partials/custom-flows/sso-connections.mdx b/docs/_partials/custom-flows/sso-connections.mdx
index 38aa27c982..d338f58a35 100644
--- a/docs/_partials/custom-flows/sso-connections.mdx
+++ b/docs/_partials/custom-flows/sso-connections.mdx
@@ -1,10 +1,10 @@
-The following example **will both sign up _and_ sign in users**, eliminating the need for a separate sign-up page. However, if you want to have separate sign-up and sign-in pages, the sign-up and sign-in flows are equivalent, meaning that all you have to do is swap out the `SignIn` object for the `SignUp` object using the [`useSignUp()`](/docs/hooks/use-sign-up) hook.
+The following example **will both sign up _and_ sign in users**, eliminating the need for a separate sign-up page. However, if you want to have separate sign-up and sign-in pages, the sign-up and sign-in flows are equivalent, meaning that all you have to do is swap out the `SignIn` object for the `SignUp` object using the [`useSignUp()`](/docs/reference/hooks/use-sign-up) hook.
The following example:
-1. Accesses the [`SignIn`](/docs/references/javascript/sign-in) object using the [`useSignIn()`](/docs/hooks/use-sign-in) hook.
-1. Starts the authentication process by calling [`SignIn.authenticateWithRedirect(params)`](/docs/references/javascript/sign-in#authenticate-with-redirect). This method requires a `redirectUrl` param, which is the URL that the browser will be redirected to once the user authenticates with the identity provider.
-1. Creates a route at the URL that the `redirectUrl` param points to. The following example names this route `/sso-callback`. This route should either render the prebuilt [``](/docs/components/control/authenticate-with-callback) component or call the [`Clerk.handleRedirectCallback()`](/docs/references/javascript/clerk#handle-redirect-callback) method if you're not using the prebuilt component.
+1. Accesses the [`SignIn`](/docs/reference/javascript/sign-in) object using the [`useSignIn()`](/docs/reference/hooks/use-sign-in) hook.
+1. Starts the authentication process by calling [`SignIn.authenticateWithRedirect(params)`](/docs/reference/javascript/sign-in#authenticate-with-redirect). This method requires a `redirectUrl` param, which is the URL that the browser will be redirected to once the user authenticates with the identity provider.
+1. Creates a route at the URL that the `redirectUrl` param points to. The following example names this route `/sso-callback`. This route should either render the prebuilt [``](/docs/reference/components/control/authenticate-with-redirect-callback) component or call the [`Clerk.handleRedirectCallback()`](/docs/reference/javascript/clerk#handle-redirect-callback) method if you're not using the prebuilt component.
The following example shows two files:
diff --git a/docs/_partials/expo/sign-out-custom-flow.mdx b/docs/_partials/expo/sign-out-custom-flow.mdx
index 1b0dbc216f..1a4c5537c8 100644
--- a/docs/_partials/expo/sign-out-custom-flow.mdx
+++ b/docs/_partials/expo/sign-out-custom-flow.mdx
@@ -14,7 +14,7 @@ export const SignOutButton = () => {
// Redirect to your desired page
router.replace('/')
} catch (err) {
- // See https://clerk.com/docs/custom-flows/error-handling
+ // See https://clerk.com/docs/guides/development/custom-flows/error-handling
// for more info on error handling
console.error(JSON.stringify(err, null, 2))
}
diff --git a/docs/_partials/fastify/get-auth.mdx b/docs/_partials/fastify/get-auth.mdx
index 7936b6f203..20448c1abf 100644
--- a/docs/_partials/fastify/get-auth.mdx
+++ b/docs/_partials/fastify/get-auth.mdx
@@ -1,4 +1,4 @@
-The following example uses `getAuth()` to protect a route and load the user's data. If the user is authenticated, their `userId` is passed to [`clerkClient.users.getUser()`](/docs/references/backend/user/get-user){{ target: '_blank' }} to get the current user's [`User`](/docs/references/javascript/user){{ target: '_blank' }} object. If not authenticated, the request is rejected with a `401` status code.
+The following example uses `getAuth()` to protect a route and load the user's data. If the user is authenticated, their `userId` is passed to [`clerkClient.users.getUser()`](/docs/reference/backend/user/get-user){{ target: '_blank' }} to get the current user's [`User`](/docs/reference/javascript/user){{ target: '_blank' }} object. If not authenticated, the request is rejected with a `401` status code.
```ts
// dotenv must be imported before @clerk/fastify
@@ -21,7 +21,7 @@ fastify.get('/protected', async (request, reply) => {
return reply.code(401).send({ error: 'User not authenticated' })
}
- // Use `clerkClient` to access Clerk's Backend SDK methods
+ // Use `clerkClient` to access Clerk's JS Backend SDK methods
// and get the user's User object
const user = await clerkClient.users.getUser(userId)
diff --git a/docs/_partials/has-warning.mdx b/docs/_partials/has-warning.mdx
index 1c870675d6..0100d10827 100644
--- a/docs/_partials/has-warning.mdx
+++ b/docs/_partials/has-warning.mdx
@@ -1,2 +1,2 @@
> [!WARNING]
-> Using `has()` **on the server-side** to check permissions works only with **custom permissions**, as [system permissions](/docs/organizations/roles-permissions#system-permissions) aren't included in the session token claims. To check system permissions, verify the user's role instead.
+> Using `has()` **on the server-side** to check permissions works only with **custom permissions**, as [system permissions](/docs/guides/organizations/roles-and-permissions#system-permissions) aren't included in the session token claims. To check system permissions, verify the user's role instead.
diff --git a/docs/_partials/hooks/hook-list.mdx b/docs/_partials/hooks/hook-list.mdx
index 0a416ca1a1..7870a9e39f 100644
--- a/docs/_partials/hooks/hook-list.mdx
+++ b/docs/_partials/hooks/hook-list.mdx
@@ -1,17 +1,17 @@
-- [`useUser()`](/docs/hooks/use-user)
-- [`useClerk()`](/docs/hooks/use-clerk)
-- [`useAuth()`](/docs/hooks/use-auth)
-- [`useSignIn()`](/docs/hooks/use-sign-in)
-- [`useSignUp()`](/docs/hooks/use-sign-up)
-- [`useSession()`](/docs/hooks/use-session)
-- [`useSessionList()`](/docs/hooks/use-session-list)
-- [`useOrganization()`](/docs/hooks/use-organization)
-- [`useOrganizationList()`](/docs/hooks/use-organization-list)
-- [`useReverification()`](/docs/hooks/use-reverification)
-- [`useCheckout()`](/docs/hooks/use-checkout)
-- [`usePaymentElement()`](/docs/hooks/use-payment-element)
-- [`usePaymentMethods()`](/docs/hooks/use-payment-methods)
-- [`usePlans()`](/docs/hooks/use-plans)
-- [`useSubscription()`](/docs/hooks/use-subscription)
-- [`useStatements()`](/docs/hooks/use-statements)
-- [`usePaymentAttempts()`](/docs/hooks/use-payment-attempts)
+- [`useUser()`](/docs/reference/hooks/use-user)
+- [`useClerk()`](/docs/reference/hooks/use-clerk)
+- [`useAuth()`](/docs/reference/hooks/use-auth)
+- [`useSignIn()`](/docs/reference/hooks/use-sign-in)
+- [`useSignUp()`](/docs/reference/hooks/use-sign-up)
+- [`useSession()`](/docs/reference/hooks/use-session)
+- [`useSessionList()`](/docs/reference/hooks/use-session-list)
+- [`useOrganization()`](/docs/reference/hooks/use-organization)
+- [`useOrganizationList()`](/docs/reference/hooks/use-organization-list)
+- [`useReverification()`](/docs/reference/hooks/use-reverification)
+- [`useCheckout()`](/docs/reference/hooks/use-checkout)
+- [`usePaymentElement()`](/docs/reference/hooks/use-payment-element)
+- [`usePaymentMethods()`](/docs/reference/hooks/use-payment-methods)
+- [`usePlans()`](/docs/reference/hooks/use-plans)
+- [`useSubscription()`](/docs/reference/hooks/use-subscription)
+- [`useStatements()`](/docs/reference/hooks/use-statements)
+- [`usePaymentAttempts()`](/docs/reference/hooks/use-payment-attempts)
diff --git a/docs/hooks/overview.mdx b/docs/_partials/hooks/hooks-explanation.mdx
similarity index 62%
rename from docs/hooks/overview.mdx
rename to docs/_partials/hooks/hooks-explanation.mdx
index f4ec09ce5c..f3272c47e6 100644
--- a/docs/hooks/overview.mdx
+++ b/docs/_partials/hooks/hooks-explanation.mdx
@@ -1,12 +1 @@
----
-title: Hooks Reference
-description: A list of Clerk's comprehensive suite of hooks for managing authentication, sessions, sign-in and sign-up flows, organizations, and reverification.
----
-
Clerk offers a comprehensive suite of hooks that expose low-level access to authentication, session management, and multi-tenancy. With Clerk hooks, you can access and manage user data, handle sign-in and sign-up flows, control session management, and implement advanced flows like session reverification for sensitive actions. By using these hooks, you can extend or replace Clerk's built-in components and customize how authentication behaves in your application.
-
-## Hooks
-
-
-
-
diff --git a/docs/_partials/hooks/paginated-resources.mdx b/docs/_partials/hooks/paginated-resources.mdx
index 4052ef74c7..75affc164d 100644
--- a/docs/_partials/hooks/paginated-resources.mdx
+++ b/docs/_partials/hooks/paginated-resources.mdx
@@ -2,7 +2,7 @@
- `data`
- `T[]`
- An array that contains the fetched data. For example, for the `memberships` attribute, `data` will be an array of [`OrganizationMembership`](/docs/references/javascript/types/organization-membership) objects.
+ An array that contains the fetched data. For example, for the `memberships` attribute, `data` will be an array of [`OrganizationMembership`](/docs/reference/javascript/types/organization-membership) objects.
---
diff --git a/docs/_partials/hooks/use-auth.mdx b/docs/_partials/hooks/use-auth.mdx
index 87d4f00299..0dda9f142f 100644
--- a/docs/_partials/hooks/use-auth.mdx
+++ b/docs/_partials/hooks/use-auth.mdx
@@ -1,4 +1,6 @@
-The following example uses the [`useAuth()`](/docs/hooks/use-auth) hook to access the current auth state, as well as helper methods to manage the current active session.
+{/* TODO: Keep in sync with /tanstack-react-start/read-session-data and /expo/read-session-user-data */}
+
+The following example uses the [`useAuth()`](/docs/reference/hooks/use-auth) hook to access the current auth state, as well as helper methods to manage the current active session. The following example demonstrates how to use the available properties of the `useAuth()` hook.
```tsx {{ filename: 'example.tsx' }}
export default function Example() {
@@ -36,5 +38,3 @@ export default function Example() {
)
}
```
-
-{/* TODO: Keep in sync with /tanstack-react-start/read-session-data and /expo/read-session-user-data */}
diff --git a/docs/_partials/hooks/use-user.mdx b/docs/_partials/hooks/use-user.mdx
index 6b30136b55..b24d2e597e 100644
--- a/docs/_partials/hooks/use-user.mdx
+++ b/docs/_partials/hooks/use-user.mdx
@@ -1,19 +1,22 @@
-The following example uses the [`useUser()`](/docs/hooks/use-user) hook to access the [`User`](/docs/references/javascript/user) object, which contains the current user's data such as their full name. The `isLoaded` and `isSignedIn` properties are used to handle the loading state and to check if the user is signed in, respectively.
+{/* TODO: Keep in sync with /reference/tanstack-react-start/read-session-data and /reference/expo/read-session-user-data */}
+
+The following example uses the [`useUser()`](/docs/reference/hooks/use-user) hook to access the [`User`](/docs/reference/javascript/user) object, which contains the current user's data such as their full name. The following example demonstrates how to use `useUser()` to check if the user is signed in and display their first name.
```tsx {{ filename: 'src/Example.tsx' }}
export default function Example() {
const { isSignedIn, user, isLoaded } = useUser()
+ // Use `isLoaded` to check if Clerk is loaded
if (!isLoaded) {
return Loading...
}
+ // Use `isSignedIn` to protect the content
if (!isSignedIn) {
return Sign in to view this page
}
+ // Use `user` to access the current user's data
return Hello {user.firstName}!
}
```
-
-{/* TODO: Keep in sync with /references/tanstack-react-start/read-session-data and /references/expo/read-session-user-data */}
diff --git a/docs/_partials/ios/customization.mdx b/docs/_partials/ios/customization.mdx
index c020469cd3..b1dfe39c35 100644
--- a/docs/_partials/ios/customization.mdx
+++ b/docs/_partials/ios/customization.mdx
@@ -1,3 +1,3 @@
-To learn how to customize Clerk iOS components, see the [dedicated guide](/docs/references/ios/clerk-theme).
+To learn how to customize Clerk iOS components, see the [dedicated guide](/docs/reference/ios/clerk-theme).
-If Clerk's prebuilt components don't meet your specific needs or if you require more control over the logic, you can rebuild the existing Clerk flows using the Clerk API. For more information, see the [custom flow guides](/docs/custom-flows/overview).
+If Clerk's prebuilt components don't meet your specific needs or if you require more control over the logic, you can rebuild the existing Clerk flows using the Clerk API. For more information, see the [custom flow guides](/docs/guides/development/custom-flows/overview).
diff --git a/docs/_partials/metadata-callout.mdx b/docs/_partials/metadata-callout.mdx
index 2ba2fc44cf..4fc2eea58d 100644
--- a/docs/_partials/metadata-callout.mdx
+++ b/docs/_partials/metadata-callout.mdx
@@ -1,4 +1,4 @@
> [!WARNING]
-> Metadata is limited to **8KB** maximum. If you're storing metadata as a custom claim in the session token, it's highly recommended to keep it under **1.2KB**. [Learn more about the session token size limitations](/docs/backend-requests/resources/session-tokens#size-limitations).
+> Metadata is limited to **8KB** maximum. If you're storing metadata as a custom claim in the session token, it's highly recommended to keep it under **1.2KB**. [Learn more about the session token size limitations](/docs/guides/sessions/session-tokens#size-limitations).
>
-> If you use Clerk metadata and modify it server-side, the changes won't appear in the session token until the next refresh. To avoid race conditions, either [force a JWT refresh](/docs/guides/force-token-refresh) after metadata changes or handle the delay in your application logic.
+> If you use Clerk metadata and modify it server-side, the changes won't appear in the session token until the next refresh. To avoid race conditions, either [force a JWT refresh](/docs/guides/sessions/force-token-refresh) after metadata changes or handle the delay in your application logic.
diff --git a/docs/_partials/nextjs/build-clerk-props.mdx b/docs/_partials/nextjs/build-clerk-props.mdx
index a964abcb54..0a663f6961 100644
--- a/docs/_partials/nextjs/build-clerk-props.mdx
+++ b/docs/_partials/nextjs/build-clerk-props.mdx
@@ -18,7 +18,7 @@ export const getServerSideProps: GetServerSideProps = async (ctx) => {
}
}
- // Initialize the Backend SDK
+ // Initialize the JS Backend SDK
const client = await clerkClient()
// Get the user's full `Backend User` object
diff --git a/docs/_partials/nextjs/get-auth.mdx b/docs/_partials/nextjs/get-auth.mdx
index 5ac27a3dd3..d916408ae2 100644
--- a/docs/_partials/nextjs/get-auth.mdx
+++ b/docs/_partials/nextjs/get-auth.mdx
@@ -11,7 +11,7 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
return res.status(401).json({ error: 'Unauthorized' })
}
- // Initialize the Backend SDK
+ // Initialize the JS Backend SDK
const client = await clerkClient()
// Get the user's full Backend User object
diff --git a/docs/_partials/nextjs/next-steps.mdx b/docs/_partials/nextjs/next-steps.mdx
index e741ac119f..4094dfdff3 100644
--- a/docs/_partials/nextjs/next-steps.mdx
+++ b/docs/_partials/nextjs/next-steps.mdx
@@ -1,29 +1,29 @@
- - [Create a custom sign-in or sign-up page](/docs/references/nextjs/custom-sign-in-or-up-page)
+ - [Create a custom sign-in or sign-up page](/docs/nextjs/guides/development/custom-sign-in-or-up-page)
- This tutorial gets you started with Clerk's `` component, which uses the Account Portal. If you don't want to use the Account Portal, read this guide about creating a custom authentication page.
---
- - [Add custom onboarding to your authentication flow](/docs/references/nextjs/add-onboarding-flow)
+ - [Add custom onboarding to your authentication flow](/docs/guides/development/add-onboarding-flow)
- If you need to collect additional information about users that Clerk's Account Portal or prebuilt components don't collect, read this guide about adding a custom onboarding flow to your authentication flow.
---
- - [Protect specific routes](/docs/references/nextjs/clerk-middleware)
+ - [Protect specific routes](/docs/reference/nextjs/clerk-middleware)
- This tutorial taught you that by default, `clerkMiddleware()` will not protect any routes. Read this reference doc to learn how to protect specific routes from unauthenticated users.
---
- - [Read user and session data](/docs/references/nextjs/read-session-data)
+ - [Read user and session data](/docs/nextjs/guides/users/reading)
- Learn how to use Clerk's hooks and helpers to access the active session and user data in your Next.js app.
---
- - [Next.js SDK Reference](/docs/references/nextjs/overview)
+ - [Next.js SDK Reference](/docs/reference/nextjs/overview)
- Learn more about the Clerk Next.js SDK and how to use it.
---
- - [Deploy to Production](/docs/deployments/overview)
+ - [Deploy to Production](/docs/guides/development/deployment/production)
- Learn how to deploy your Clerk app to production.
diff --git a/docs/_partials/remix/maintenance-mode.mdx b/docs/_partials/remix/maintenance-mode.mdx
index ebed5f9ec8..1cd608ebe6 100644
--- a/docs/_partials/remix/maintenance-mode.mdx
+++ b/docs/_partials/remix/maintenance-mode.mdx
@@ -1,2 +1,2 @@
> [!WARNING]
-> The Remix SDK is in maintenance mode and will only receive security updates. Please migrate to the [React Router SDK](/docs/quickstarts/react-router) for continued development and new features.
+> The Remix SDK is in maintenance mode and will only receive security updates. Please migrate to the [React Router SDK](/docs/react-router/getting-started/quickstart) for continued development and new features.
diff --git a/docs/_partials/root-auth-loader.mdx b/docs/_partials/root-auth-loader.mdx
index bb59ce270c..c449ac391a 100644
--- a/docs/_partials/root-auth-loader.mdx
+++ b/docs/_partials/root-auth-loader.mdx
@@ -32,7 +32,7 @@ The `rootAuthLoader()` function accepts an optional object. The following option
- `jwtKey`
- `string`
- Used to verify the session token in a networkless manner. Supply the **JWKS Public Key** from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) instead.** For more information, refer to [Manual JWT verification](/docs/backend-requests/manual-jwt).
+ Used to verify the session token in a networkless manner. Supply the **JWKS Public Key** from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#api-and-sdk-configuration) instead.** For more information, refer to [Manual JWT verification](/docs/guides/sessions/manual-jwt-verification).
---
@@ -46,54 +46,54 @@ The `rootAuthLoader()` function accepts an optional object. The following option
- `publishableKey`
- `string`
- The Clerk Publishable Key for your instance. This can be found in the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show Publishable Key** section in the Clerk Dashboard. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#clerk-publishable-and-secret-keys) instead.
+ The Clerk Publishable Key for your instance. This can be found in the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show Publishable Key** section in the Clerk Dashboard. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#clerk-publishable-and-secret-keys) instead.
---
- `secretKey?`
- `string`
- The Clerk Secret Key for your instance. This can be found on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#clerk-publishable-and-secret-keys) instead.
+ The Clerk Secret Key for your instance. This can be found on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#clerk-publishable-and-secret-keys) instead.
---
- `signInUrl`
- `string`
- This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances. **It is required to be set for a satellite application in a development instance.** It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+ This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances. **It is required to be set for a satellite application in a development instance.** It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
---
- `signUpUrl`
- `string`
- This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances but **must be set for a satellite application in a development instance.** It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+ This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances but **must be set for a satellite application in a development instance.** It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
---
- `signInFallbackRedirectUrl?`
- `string`
- The fallback URL to redirect to after the user signs in, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+ The fallback URL to redirect to after the user signs in, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
---
- `signUpFallbackRedirectUrl?`
- `string`
- The fallback URL to redirect to after the user signs up, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+ The fallback URL to redirect to after the user signs up, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
---
- `signInForceRedirectUrl?`
- `string`
- If provided, this URL will always be redirected to after the user signs in. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+ If provided, this URL will always be redirected to after the user signs in. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
---
- `signUpForceRedirectUrl?`
- `string`
- If provided, this URL will always be redirected to after the user signs up. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+ If provided, this URL will always be redirected to after the user signs up. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
diff --git a/docs/_partials/ruby/configuration.mdx b/docs/_partials/ruby/configuration.mdx
index ab8abead43..8efa60c413 100644
--- a/docs/_partials/ruby/configuration.mdx
+++ b/docs/_partials/ruby/configuration.mdx
@@ -1,4 +1,4 @@
-The configuration object provides a flexible way to configure the SDK. When a configuration value is not explicitly provided, it will fall back to checking the corresponding [environment variable](/docs/references/ruby/overview#available-environment-variables). You must provide your Clerk Secret Key, which can be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard.
+The configuration object provides a flexible way to configure the SDK. When a configuration value is not explicitly provided, it will fall back to checking the corresponding [environment variable](/docs/reference/ruby/overview#available-environment-variables). You must provide your Clerk Secret Key, which can be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard.
The following example shows how to set up your configuration object:
diff --git a/docs/_partials/ruby/installation.mdx b/docs/_partials/ruby/installation.mdx
index 811bf2da7e..bfd556cec2 100644
--- a/docs/_partials/ruby/installation.mdx
+++ b/docs/_partials/ruby/installation.mdx
@@ -1,4 +1,4 @@
-The [Clerk Ruby SDK](/docs/references/ruby/overview) provides a range of backend utilities to simplify user authentication and management in your application.
+The [Clerk Ruby SDK](/docs/reference/ruby/overview) provides a range of backend utilities to simplify user authentication and management in your application.
1. Add the following code to your application's `Gemfile`.
```ruby {{ filename: 'Gemfile' }}
diff --git a/docs/_partials/token-size-callout.mdx b/docs/_partials/token-size-callout.mdx
index fe1e7ba780..d5c5d31412 100644
--- a/docs/_partials/token-size-callout.mdx
+++ b/docs/_partials/token-size-callout.mdx
@@ -1,2 +1,2 @@
> [!CAUTION]
-> Clerk stores the session token in a cookie, and most browsers cap cookie size at [**4KB**](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). After accounting for the size of Clerk's default claims, the cookie can support **up to 1.2KB** of custom claims. Exceeding this limit will cause the cookie to not be set, which will break your app as Clerk depends on cookies to work properly. [Learn more](/docs/backend-requests/resources/session-tokens#size-limitations).
+> Clerk stores the session token in a cookie, and most browsers cap cookie size at [**4KB**](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). After accounting for the size of Clerk's default claims, the cookie can support **up to 1.2KB** of custom claims. Exceeding this limit will cause the cookie to not be set, which will break your app as Clerk depends on cookies to work properly. [Learn more](/docs/guides/sessions/session-tokens#size-limitations).
diff --git a/docs/_partials/update-clerk-options-properties.mdx b/docs/_partials/update-clerk-options-properties.mdx
index 06a820ea40..46f9edcd64 100644
--- a/docs/_partials/update-clerk-options-properties.mdx
+++ b/docs/_partials/update-clerk-options-properties.mdx
@@ -1,17 +1,17 @@
- `appearance`
- - [Appearance](/docs/customization/overview) | undefined
+ - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined
Optional object to style your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages.
---
- `localization`
- - [Localization](/docs/customization/localization) | undefined
+ - [Localization](/docs/guides/customizing-clerk/localization) | undefined
Optional object to localize your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages.
-[components-ref]: /docs/components/overview
+[components-ref]: /docs/reference/components/overview
-[ap-ref]: /docs/account-portal/overview
+[ap-ref]: /docs/guides/customizing-clerk/account-portal
diff --git a/docs/_partials/upgrade-node-express.mdx b/docs/_partials/upgrade-node-express.mdx
index bdf222083b..fbe2a068cf 100644
--- a/docs/_partials/upgrade-node-express.mdx
+++ b/docs/_partials/upgrade-node-express.mdx
@@ -1,2 +1,2 @@
> [!IMPORTANT]
-> The Node SDK is no longer supported. [Upgrade to the Express SDK](/docs/upgrade-guides/node-to-express).
+> The Node SDK is no longer supported. [Upgrade to the Express SDK](/docs/guides/development/upgrading/upgrade-guides/node-to-express).
diff --git a/docs/_partials/user-object.mdx b/docs/_partials/user-object.mdx
index b6d538e364..156f8df1c4 100644
--- a/docs/_partials/user-object.mdx
+++ b/docs/_partials/user-object.mdx
@@ -1,5 +1,5 @@
The `User` object holds all of the information for a single user of your application and provides a set of methods to manage their account. Each `User` has at least one authentication identifier, which might be their email address, phone number, or a username.
-A user can be contacted at their primary email address or primary phone number. They can have more than one registered email address, but only one of them will be their primary email address. This goes for phone numbers as well; a user can have more than one, but only one phone number will be their primary. At the same time, a user can also have one or more external accounts by connecting to [social providers](/docs/authentication/social-connections/oauth) such as Google, Apple, Facebook, and many more.
+A user can be contacted at their primary email address or primary phone number. They can have more than one registered email address, but only one of them will be their primary email address (`User.primaryEmailAddress`). This goes for phone numbers as well; a user can have more than one, but only one phone number will be their primary (`User.primaryPhoneNumber`). At the same time, a user can also have one or more external accounts by connecting to [social providers](/docs/guides/configure/auth-strategies/social-connections/all-providers) such as Google, Apple, Facebook, and many more (`User.externalAccounts`).
-Finally, a `User` object holds profile data like the user's name, profile picture, and a set of [metadata](/docs/users/metadata) that can be used internally to store arbitrary information. The metadata are split into `publicMetadata` and `privateMetadata`. Both types are set from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but public metadata can also be accessed from the [Frontend API](/docs/reference/frontend-api){{ target: '_blank' }}.
+Finally, a `User` object holds profile data like the user's name, profile picture, and a set of [metadata](/docs/guides/users/extending) that can be used internally to store arbitrary information. The metadata are split into `publicMetadata` and `privateMetadata`. Both types are set from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but public metadata can also be accessed from the [Frontend API](/docs/reference/frontend-api){{ target: '_blank' }}.
diff --git a/docs/_partials/vue-nuxt/composables.mdx b/docs/_partials/vue-nuxt/composables.mdx
index 5b454d6c23..7649866a0a 100644
--- a/docs/_partials/vue-nuxt/composables.mdx
+++ b/docs/_partials/vue-nuxt/composables.mdx
@@ -1,8 +1,8 @@
-- [`useUser()`](/docs/references/vue/use-user)
-- [`useClerk()`](/docs/references/vue/use-clerk)
-- [`useAuth()`](/docs/references/vue/use-auth)
-- [`useSignIn()`](/docs/references/vue/use-sign-in)
-- [`useSignUp()`](/docs/references/vue/use-sign-up)
-- [`useSession()`](/docs/references/vue/use-session)
-- [`useSessionList()`](/docs/references/vue/use-session-list)
-- [`useOrganization()`](/docs/references/vue/use-organization)
+- [`useUser()`](/docs/reference/composables/use-user)
+- [`useClerk()`](/docs/reference/composables/use-clerk)
+- [`useAuth()`](/docs/reference/composables/use-auth)
+- [`useSignIn()`](/docs/reference/composables/use-sign-in)
+- [`useSignUp()`](/docs/reference/composables/use-sign-up)
+- [`useSession()`](/docs/reference/composables/use-session)
+- [`useSessionList()`](/docs/reference/composables/use-session-list)
+- [`useOrganization()`](/docs/reference/composables/use-organization)
diff --git a/docs/account-portal/direct-links.mdx b/docs/account-portal/direct-links.mdx
deleted file mode 100644
index 4bc03f778f..0000000000
--- a/docs/account-portal/direct-links.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-title: Linking to the Account Portal
-description: Learn how to share direct links to your Account Portal pages, and how to set up fallback redirects.
----
-
-## Redirect URL
-
-If a user accesses an Account Portal page _directly_, the `redirect_url` query param will not be present, so the user cannot be redirected back to your application once they are finished with their Account Portal flow. To prevent this, it is recommend that you always specify the redirect in the link when sharing it.
-
-You can use the following format for your direct links:
-
-`https://accounts./?redirect_url=`
-
-**Example**
-
-`https://accounts.myapp.com/sign-in?redirect_url=https://myapp.com/dashboard`
-
-The domain is `myapp.com`, the user is being linked to the sign-in Account Portal page at `http://accounts.myapp.com/sign-in` and they will be redirected to `https://myapp.com/dashboard` after they are signed in.
-
-## Fallback redirects
-
-In the case that a user _does_ visit an Account Portal page directly without the query param, you can set up fallback redirects to ensure that the user is redirected back to your application after they are finished with their Account Portal flow.
-
-### Sign-in and sign-up
-
-Set the appropriate [environment variables](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) to configure the fallback redirects for sign-in and sign-up.
-
-### Sign out
-
-Set the post-sign-out redirect by passing the `afterSignOutUrl` prop to the `` component. See the [reference doc](/docs/components/clerk-provider) for more information.
-
-### Organization redirects
-
-Both the `` and `` components accept an `afterLeaveOrganizationUrl` prop for setting the redirect after leaving an organization.
-
-The `` component accepts an `afterSelectOrganizationUrl` prop for setting the redirect after selecting an organization, and an `afterCreateOrganizationUrl` prop for setting the redirect after creating an organization.
-
-## Prefill sign in and sign up fields
-
-In the case of direct links, the values to be used for prefilling the fields for sign-in or sign-up can be specified via the following query parameters:
-
-- `email_address`
-- `phone_number`
-- `username`
-- `first_name`
-- `last_name`
-
-For example, visiting `https://accounts.example.com/sign-in?username=nick` will result in the username field being prefilled with the value `nick`.
diff --git a/docs/account-portal/disable-account-portal.mdx b/docs/account-portal/disable-account-portal.mdx
deleted file mode 100644
index 26b9aa1ed8..0000000000
--- a/docs/account-portal/disable-account-portal.mdx
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: Disabling the Account Portal
-description: Learn how to disable the Account Portal.
----
-
-> [!CAUTION]
-> We recommend leaving the Account Portal enabled, even if you do choose to set up your own authentication flow. This helps with testing as well as providing an alternative path for users when needed.
-
-To disable the Account Portal:
-
-1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page.
-1. Select **Disable Account Portal** on the right-side. You will not be able to select this button until you have [set up an authentication flow for your users](#customize-your-sign-up-sign-in-flow), as applying this setting will immediately result in a 404 for all Account Portal pages.
-
-## Customize your sign-up/sign-in flow
-
-Once you have disabled the Account Portal, you are fully responsible for providing your own flows, such as sign-up and sign-in. Clerk provides a set of [prebuilt components](/docs/components/overview) that you can use. If prebuilt components don't meet your specific needs or if you require more control over the logic, you can rebuild the existing Clerk flows using the Clerk API. See the [custom flows](/docs/custom-flows/overview) guides for more information. **It's highly recommended that even if you use either of these options, you keep the Account Portal enabled for testing purposes and as a fallback for users.**
diff --git a/docs/account-portal/getting-started.mdx b/docs/account-portal/getting-started.mdx
deleted file mode 100644
index b695c7cb86..0000000000
--- a/docs/account-portal/getting-started.mdx
+++ /dev/null
@@ -1,28 +0,0 @@
----
-title: Getting started with the Account Portal
-description: The Account Portal offers a comprehensive solution for managing user authentication and profile management in your web application and is the fastest way to add Clerk's authentication to your application with minimal code required.
----
-
-To integrate the Account Portal into your application, simply follow one of the [quickstart guides](/docs/quickstarts/overview). Once your application is set up, all you have to do is run it. Clerk will automatically redirect your users to the Account Portal sign-up/sign-in pages. After successful authentication, users will be redirected back to your application with an active session.
-
-You can also integrate the Account Portal into your application using prebuilt components. For example, the [``](/docs/components/unstyled/sign-up-button) and [``](/docs/components/unstyled/sign-in-button) components will redirect users to the Account Portal sign-up and sign-in pages if no props or [environment variables](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) are configured to override this behavior.
-
-> [!NOTE]
-> **Dynamic Development Host Detection**
->
-> For development environments, the development host (e.g. [http://localhost:3000](http://localhost:3000)) is dynamically detected by Clerk at runtime and tied to your client browser. We store this as the ‘home origin’ for your application and it is equivalent to your application domain in production environments.
-
-## Accessing your pages
-
-For development environments, Clerk will issue you a randomly generated domain on "accounts.dev". In production, by default, the URLs for your Account Portal are the following:
-
-```sh
-https://accounts..com/sign-in
-https://accounts..com/sign-up
-https://accounts..com/user
-https://accounts..com/unauthorized-sign-in
-https://accounts..com/organization
-https://accounts..com/create-organization
-```
-
-To access these links, in the Clerk Dashboard, go to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page and then open the **Pages** tab.
diff --git a/docs/account-portal/overview.mdx b/docs/account-portal/overview.mdx
deleted file mode 100644
index d9d897e353..0000000000
--- a/docs/account-portal/overview.mdx
+++ /dev/null
@@ -1,83 +0,0 @@
----
-title: Account Portal overview
-description: The Account Portal offers a comprehensive solution for managing user authentication and profile management in your web application and is the fastest way to add Clerk's authentication to your application with minimal code required.
----
-
-The Account Portal in Clerk is a powerful feature that allows you to streamline the sign-in, sign-up, and profile management experience for your users, without having to build your own components or host your own pages. **To integrate the Account Portal with your application, see the [setup guide](/docs/account-portal/getting-started).**
-
-
-
-## Why use the Account Portal?
-
-The Account Portal provides the pages necessary for your users to sign-up, sign-in, and manage their accounts, all while maintaining seamless integration with your application. These pages are hosted on Clerk servers for you and they require minimal setup to get started. If you're looking for the fastest way to add authentication and user management to your application, then this is a great choice.
-
-However, if you require more precise customization or prefer having your application self-contained, then you can use Clerk's fully customizable [prebuilt components](/docs/components/overview), or you can build your own [custom user interface using the Clerk API](/docs/custom-flows/overview).
-
-## How the Account Portal works
-
-The Account Portal uses Clerk's [prebuilt components](/docs/components/overview), which are embedded into dedicated pages hosted on Clerk servers.
-
-
-
-After a user has finished their flow in an Account Portal page, Clerk automatically redirects them back to your application along with the required authentication context. This way, users are automatically redirected to and from your application for a seamless experience.
-
-For each application environment, Clerk provides pages for sign-up, sign-in, user profile, organization profile, and organization creation flow. **To integrate the Account Portal with your application, see the [setup guide](/docs/account-portal/getting-started).**
-
-> [!IMPORTANT]
-> These pages cannot be customized beyond the options provided in the [Clerk Dashboard](https://dashboard.clerk.com). If you need more customization such as [localization](/docs/customization/localization), consider using [prebuilt components](/docs/components/overview) or building your own [custom user interface](/docs/custom-flows/overview).
-
-## Hosted pages
-
-### Sign-in
-
-The sign-in page hosts the prebuilt [``](/docs/components/authentication/sign-in) component, which renders a UI for signing in users. The functionality of the `` component is controlled by the instance settings you specify in the [Clerk Dashboard](https://dashboard.clerk.com), such as [sign-up and sign-in options](/docs/authentication/configuration/sign-up-sign-in-options) and [social connections](/docs/authentication/social-connections/oauth).
-
-
-
-Redirect users to the sign-in page using the [``](/docs/components/control/redirect-to-signin) control component.
-
-### Sign-up
-
-The sign-up page hosts the prebuilt [``](/docs/components/authentication/sign-up) component, which renders a UI for signing up users. The functionality of the `` component is controlled by the instance settings you specify in the [Clerk Dashboard](https://dashboard.clerk.com), such as [sign-up and sign-in options](/docs/authentication/configuration/sign-up-sign-in-options) and [social connections](/docs/authentication/social-connections/oauth).
-
-
-
-Redirect users to the sign-up page using the [``](/docs/components/control/redirect-to-signup) control component.
-
-### User profile
-
-The user profile page hosts the prebuilt [``](/docs/components/user/user-profile) component, which renders a beautiful, full-featured account management UI that allows users to manage their profile and security settings.
-
-
-
-Redirect your authenticated users to their user profile page using the [``](/docs/components/control/redirect-to-userprofile) control component.
-
-### Unauthorized sign-in
-
-The unauthorized sign-in page doesn't host any prebuilt Clerk component. It displays a UI confirming that a session from an unrecognized device was successfully revoked. For more information, see the [Unauthorized sign-in](/docs/security/unauthorized-sign-in) feature.
-
-The unauthorized sign-in page displays a UI confirming that a session from an unrecognized device was successfully revoked. For more information, refer to [the reference.](/docs/security/unauthorized-sign-in)
-
-
-
-### Create organization
-
-The create organization page hosts the prebuilt [``](/docs/components/organization/create-organization) component, which provides a streamlined interface for users to create new organizations within your application.
-
-
-
-Redirect your authenticated users to the create organization page using the [``](/docs/components/control/redirect-to-createorganization) control component.
-
-### Organization profile
-
-The user profile page hosts the prebuilt [``](/docs/components/organization/organization-profile) component, which renders a beautiful, full-featured organization management UI that allows users to manage their organization profile and security settings.
-
-
-
-Redirect your authenticated users to their organization profile page using the [``](/docs/components/control/redirect-to-organizationprofile) control component.
-
-### Waitlist
-
-The waitlist page hosts the prebuilt [``](/docs/components/waitlist) component which renders a form that allows users to join for early access to your app.
-
-
diff --git a/docs/ai-prompts/nextjs.mdx b/docs/ai-prompts/nextjs.mdx
deleted file mode 100644
index d00f671623..0000000000
--- a/docs/ai-prompts/nextjs.mdx
+++ /dev/null
@@ -1,18 +0,0 @@
----
-title: Next.js App Router Authentication
-description: Comprehensive AI prompt for implementing Clerk authentication in Next.js 14+ applications using App Router
----
-
-This prompt helps AI assistants guide you through implementing Clerk authentication in a Next.js application using the App Router.
-
-## How to use this prompt
-
-These prompts can be copied into your AI-powered IDE or development tool, or pasted into your chat with an AI assistant. Here are some examples of how to use them:
-
-- In Cursor, add the prompt to your [project rules](https://docs.cursor.com/context/rules).
-- In GitHub Copilot, save the prompt to a file in your project and reference it using `#`.
-- In Claude Code, include the prompt in your `CLAUDE.md` file.
-
-## Prompt
-
-
diff --git a/docs/ai-prompts/react.mdx b/docs/ai-prompts/react.mdx
deleted file mode 100644
index 94c957bd2c..0000000000
--- a/docs/ai-prompts/react.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: React Authentication
-description: Complete AI prompt for integrating Clerk authentication into React applications
----
-
-This prompt helps AI assistants guide you through implementing Clerk authentication in React applications, including SPAs and client-side rendered apps.
-
-## How to use this prompt
-
-These prompts can be copied into your AI-powered IDE or development tool, or pasted into your chat with an AI assistant. Here are some examples of how to use them:
-
-- In Cursor, add the prompt to your [project rules](https://docs.cursor.com/context/rules).
-- In GitHub Copilot, save the prompt to a file in your project and reference it using `#`.
-- In Claude Code, include the prompt in your `CLAUDE.md` file.
-
-## Prompt
-
-
diff --git a/docs/authentication/overview.mdx b/docs/authentication/overview.mdx
deleted file mode 100644
index ad8b3ebeec..0000000000
--- a/docs/authentication/overview.mdx
+++ /dev/null
@@ -1,31 +0,0 @@
----
-title: Sign-up & sign-in overview
-description: Learn how to configure authentication and user management for your Clerk application.
----
-
-Clerk supports multiple authentication strategies so that you can implement the strategy that makes sense for _your_ users. You can use the [Account Portal](/docs/account-portal/overview), [prebuilt components](/docs/components/overview), or build your own [custom flows](/docs/custom-flows/overview).
-
-## Configuration
-
-Configuring your application is done through the [Clerk Dashboard](https://dashboard.clerk.com). The Clerk Dashboard is where you, as the application owner, can manage your application's settings, users, and organizations. For example, if you want to enable phone number authentication, multi-factor authentication, social providers like Google, delete users, or create organizations, you can do all of this and more in the Clerk Dashboard. You can even invite other users to join your [workspace](/docs/organizations/organization-workspaces) and help configure and manage your application with you.
-
-## SSO authentication
-
-SSO authentication allows users to sign in to your application using an existing account from an external identity provider (IdP), such as Google.
-
-Clerk supports the following SSO types:
-
-- [OAuth SSO, also known as social connections or social providers](/docs/authentication/social-connections/oauth)
-- [Enterprise SSO](/docs/authentication/enterprise-connections/overview)
- - SAML
- - OIDC
- - EASIE
-
-## Web3 authentication
-
-Clerk supports the following Web3 providers:
-
-- [Base](/docs/authentication/web3/base)
-- [Coinbase Wallet](/docs/authentication/web3/coinbase-wallet)
-- [Metamask](/docs/authentication/web3/metamask)
-- [OKX Wallet](/docs/authentication/web3/okx-wallet)
diff --git a/docs/backend-requests/overview.mdx b/docs/backend-requests/overview.mdx
deleted file mode 100644
index 81c2a10d1a..0000000000
--- a/docs/backend-requests/overview.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
----
-title: Request authentication
-description: Learn about various ways to make authenticated requests to the backend when using Clerk SDKs.
----
-
-A request is considered “authenticated” when the backend can securely identify the user and device that is making the request. Reasons for making authenticated requests to the backend include:
-
-- Associating the user with the action being performed
-- Ensuring the user has permission to make the request
-- Keeping an audit log of which device the user is performing actions from
-
-To authenticate requests when using a Clerk SDK, you must pass Clerk's short-lived [session token](/docs/backend-requests/resources/session-tokens) to your server. The session token contains cryptographically signed claims about the user's identity and authentication state. [Read more about making requests](/docs/backend-requests/making-requests).
-
-## Required headers
-
-The following headers are required for Clerk to authenticate a request. It contains information that Clerk uses to determine whether a request is in a signed in or signed out state, or if a [handshake](/docs/how-clerk-works/overview#the-handshake) must be performed.
-
-- [`Authorization`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization): This should include the user's session token as a Bearer token.
-- [`Accept`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept)
-- [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host)
-- [`Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin)
-- [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer)
-- [`Sec-Fetch-Dest`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Dest)
-- [`User-Agent`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)
-- [`X-Forwarded-Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host)
-- [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto)
- - Alternatively, you can use [`CloudFront-Forwarded-Proto`](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/adding-cloudfront-headers.html#cloudfront-headers-other)
diff --git a/docs/components/overview.mdx b/docs/components/overview.mdx
deleted file mode 100644
index 4dfbc96123..0000000000
--- a/docs/components/overview.mdx
+++ /dev/null
@@ -1,63 +0,0 @@
----
-title: Component Reference
-description: A list of Clerk's comprehensive suite of components designed to seamlessly integrate authentication and multi-tenancy into your application.
----
-
-Clerk offers a comprehensive suite of components designed to seamlessly integrate authentication and multi-tenancy into your application. With Clerk components, you can easily customize the appearance of authentication components and pages, manage the entire authentication flow to suit your specific needs, and even build robust SaaS applications.
-
-## UI components
-
-- [``](/docs/components/authentication/sign-in)
-- [``](/docs/components/authentication/sign-up)
-- [``](/docs/components/authentication/google-one-tap)
-- [``](/docs/components/user/user-button)
-- [``](/docs/components/user/user-profile)
-- [``](/docs/components/organization/create-organization)
-- [``](/docs/components/organization/organization-profile)
-- [``](/docs/components/organization/organization-switcher)
-- [``](/docs/components/organization/organization-list)
-- [``](/docs/components/waitlist)
-- [``](/docs/components/authentication/task-choose-organization)
-- [``](/docs/components/billing/pricing-table)
-
-## Control components
-
-Control components manage authentication-related behaviors in your application. They handle tasks such as controlling content visibility based on user authentication status, managing loading states during authentication processes, and redirecting users to appropriate pages. Control components render at `` and `` states for assertions on the [`Clerk` object](/docs/references/javascript/clerk). A common example is the [``](/docs/components/control/signed-in) component, which allows you to conditionally render content only when a user is authenticated.
-
-- [``](/docs/components/control/authenticate-with-callback)
-- [``](/docs/components/control/clerk-loaded)
-- [``](/docs/components/control/clerk-loading)
-- [``](/docs/components/protect)
-- [``](/docs/components/control/redirect-to-signin)
-- [``](/docs/components/control/redirect-to-signup)
-- [``](/docs/components/control/redirect-to-userprofile)
-- [``](/docs/components/control/redirect-to-organizationprofile)
-- [``](/docs/components/control/redirect-to-createorganization)
-- [``](/docs/components/control/signed-in)
-- [``](/docs/components/control/signed-out)
-
-## Unstyled components
-
-- [``](/docs/components/unstyled/sign-in-button)
-- [``](/docs/components/unstyled/sign-in-with-metamask)
-- [``](/docs/components/unstyled/sign-up-button)
-- [``](/docs/components/unstyled/sign-out-button)
-- [``](/docs/components/billing/checkout-button)
-- [``](/docs/components/billing/plan-details-button)
-- [``](/docs/components/billing/subscription-details-button)
-
-## Customization guides
-
-- [Customize components with the `appearance` prop](/docs/customization/overview)
-- [Localize components with the `localization` prop (experimental)](/docs/customization/localization)
-- [Add pages to the `` component](/docs/customization/user-profile)
-- [Add pages to the `` component](/docs/customization/organization-profile)
-
-## Secured by Clerk branding
-
-By default, Clerk displays a **Secured by Clerk** badge on Clerk components. You can remove this branding by following these steps:
-
-1. In the Clerk Dashboard, navigate to your application's [**Settings**](https://dashboard.clerk.com/last-active?path=settings).
-1. Under **Branding**, toggle on the **Remove "Secured by Clerk" branding** option. Please note that this setting requires a [paid plan](/pricing){{ target: '_blank' }} for production use, but all features are free to use in development mode so that you can try out what works for you. See the [pricing](/pricing){{ target: '_blank' }} page for more information.
-
-
diff --git a/docs/deployments/environments.mdx b/docs/deployments/environments.mdx
deleted file mode 100644
index feb23e52e9..0000000000
--- a/docs/deployments/environments.mdx
+++ /dev/null
@@ -1,52 +0,0 @@
----
-title: Instances / Environments
-description: An overview of the differences between development and production instances.
----
-
-When creating a new application within Clerk, you are provided with two instances: `Development` and `Production`. These instances vary slightly and should only be used appropriately.
-
-## Development instance
-
-A `Development` instance is Clerk's default instance type and has characteristics that allow it to be more useful for local development. To facilitate development and local authentication, `Development` instances have a more relaxed security posture and are not suitable for production workloads.
-
-Some notable examples of `Development`-only characteristics in a Clerk application are:
-
-- A `Development` banner is shown prominently in the Clerk Dashboard to make clear you're managing or configuring non-production data
-- Email and SMS templates are prefixed with the environment type to prevent against using `Development` instances for production purposes
-- Some social connections use shared credentials by default
-- [The Account Portal](/docs/account-portal/overview) will use a Clerk development domain that ends with `accounts.dev` instead of your app's production domain
-- OAuth consent screens will show the development domain that ends with `accounts.dev` instead of your production domain
-- Search engines will not be able to crawl and index your application
-- Development instances are capped at 100 users, and user data can not be transferred between instances
-- The architecture of Clerk's sessions management is different in development environments compared to production environments, due to the need to communicate cross-domain between `localhost` and `.accounts.dev`. The `__clerk_db_jwt` object is _only_ used in development environments. For more specific details on the differences between Clerk's session management architecture in development and production environments, see the [technical breakdown below](#session-architecture-differences).
-
-> [!NOTE]
-> All paid functionality is available in a `Development` instance. However, when you deploy your application to `Production`, you will be asked to upgrade to a `Pro` account if you are using paid features. See [our pricing page](/pricing) for full details.
-
-## Production instance
-
-A `Production` instance is the more robust option of Clerk's instance types. `Production` instances are meant to support high volumes of traffic and by default, have a more strict security posture.
-
-Some notable differences between `Production` and `Development` instances in a Clerk application are:
-
-- You must associate a production domain within the Clerk Dashboard
-- You are required to provision your own SSO credentials
-
-When deploying to production, you must first activate your `Production` environment. See the [Deploying to Production](/docs/deployments/overview) guide to learn about the process and avoid common pitfalls.
-
-## Staging environments
-
-Clerk does not currently support staging instances in Clerk applications. However, you can set up a "staging environment" by creating a separate Clerk application with a separate domain. For more information, see the [staging guide](/docs/deployments/set-up-staging).
-
-## Preview environments
-
-See [the preview environment guide](/docs/deployments/set-up-preview-environment) to learn how to use Clerk with your preview deployments.
-
-## Session architecture differences
-
-> [!TIP]
-> In order to understand this section, it's recommended to have a solid understanding of how Clerk's session management architecture works. For more information on this topic, check out the guide on [how Clerk works](/docs/how-clerk-works/overview).
-
-Clerk manages session state differently in production and development environments.
-
-
diff --git a/docs/deployments/exporting-users.mdx b/docs/deployments/exporting-users.mdx
deleted file mode 100644
index 6acd9c54e0..0000000000
--- a/docs/deployments/exporting-users.mdx
+++ /dev/null
@@ -1,20 +0,0 @@
----
-title: Export your user's data from Clerk
-description: Learn how to export user's data from your Clerk application.
----
-
-## Access user data in the backend
-
-By using the [`GetUserList`](/docs/reference/backend-api/tag/users/get/users){{ target: '_blank' }} Backend API endpoint, you can programmatically export your user's data safely.
-
-Additionally, the [`getUserList()`](/docs/references/backend/user/get-user-list) method in the [JavaScript Backend SDK](/docs/references/backend/overview) can also be used to retrieve a list of users.
-
-## Export your users' data from the Clerk Dashboard
-
-Users who are either admins or are in their [personal account](/docs/organizations/organization-workspaces) can export and download a CSV file containing a list of their application's users that _includes their hashed passwords_. Users can also view detailed export and download history logs. These logs offer a record of previous export actions, ensuring visibility and traceability of data exports.
-
-To export your users' data:
-
-1. In the Clerk Dashboard, navigate to the application's [**Settings**](https://dashboard.clerk.com/last-active?path=settings).
-1. In the **User Exports** section, select **Export all users**.
-1. A new entry in the export history will appear. Select the **Download** button to download the CSV file.
diff --git a/docs/deployments/migrate-overview.mdx b/docs/deployments/migrate-overview.mdx
deleted file mode 100644
index 744ad80853..0000000000
--- a/docs/deployments/migrate-overview.mdx
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: Migrate to Clerk from another platform
-description: Guides on how to move your user data from another authentication platform to Clerk.
----
-
-There are typically two main strategies for migrating your existing user management from a different platform into Clerk:
-
-- [Basic Export / Import](#basic-export-import)
-- [Trickle migration](#trickle-migration)
-
-Each of these have trade-offs you'll need to consider for your application and its users.
-
-## Basic export / import
-
-With basic export / import, you're taking an export from your previous tool and importing data into Clerk. The most common way to handle this is by making use of the [`CreateUser`](/docs/reference/backend-api/tag/users/post/users){{ target: '_blank' }} Backend API endpoint. It's important to note that the `CreateUser` endpoint is rate limited. For more information, see the [guide on rate limits](/docs/backend-requests/resources/rate-limits#backend-api-requests).
-
-You'll also need to provide your `password_hasher` value (The hashing algorithm used to generate the password digest) and in some instances Clerk will transparently upgrade your users' password hashes to the more secure Bcrypt hashing algorithm. More details on this topic are available in the [Backend API reference docs](/docs/reference/backend-api/tag/users/post/users.body.password_hasher){{ target: '_blank' }}.
-
-> [!NOTE]
-> If you are expecting to import 100k+ users, we recommend reaching out to [support@clerk.dev](mailto:support@clerk.dev) where we can coordinate increases to the rate limits and ensure a seamless import of your data.
-
-### Considerations
-
-When evaluating the Basic Import / Export workflow there are a few tradeoffs you'll need to consider.
-
-#### Data consistency
-
-Consider that any export of your data will be a snapshot in time. This means that there is a potential of your data being out of sync at the time of import. To work around this you might script and coordinate the export and import actions to be as close in time as possible, or you might schedule some kind of downtime or maintenance window to complete this action. Be sure to consider Clerk API rate-limits when evaluating a potentially time-sensitive migration approach.
-
-#### Active sessions / session management
-
-Another consideration is centered around how you handle session management. While most authentication providers don't provide session management out-of-the-box, Clerk does. This means that when you switch over to using Clerk you'll be changing the system that handles your users' active sessions. This will likely end any currently active sessions initiated by your previous session management service (unless you are able to gracefully handle this somehow within your architecture).
-
-#### Foreign keys
-
-In your previous system, you likely had some kind of ID / Foreign Key that you were using. As you migrate data into Clerk, you might want to continue referencing that previous ID alongside Clerk's provided user IDs. While each use case might have some variation, a common strategy is to store previous IDs as an `external_id`. You can then use Clerk's JWT customization to enrich a `userId` value with the `external_id` when present, or fallback to using Clerk's native ID when dealing with new users who don't have an `external_id` from your legacy system. You can configure this in the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page in the Clerk Dashboard. Under **Customize session token**, in the **Claims** editor, enter the following JSON and select **Save**. If you have already customized your session token, you may need to merge this with what you currently have.
-
-```json
-{
- "userId": "{{user.external_id || user.id}}"
-}
-```
-
-## Trickle migration
-
-With a trickle migration you are slowly migrating your users from your previous system into Clerk. Depending on your application's needs this can be a great way to accomplish migration in a gradual and more controlled way. With a trickle migration, you are keeping both systems running for some period of time, handling the transition between systems behind the scenes, and then eventually cutting over fully to Clerk as your user and session management system of record. By handling this transition gradually you'll maintain more control and put less pressure on a single coordinated event.
-
-### Considerations
-
-As with the Basic Import / Export workflow there are trade-offs you'll need to consider, to determine which strategy is best for your application.
-
-#### The cost and overhead of running two systems in parallel
-
-Because you'll need both systems available when doing a gradual migration, there is naturally additional short-term costs related to having both running systems at the same time.
-
-> [!NOTE]
-> It's important to note that Clerk only charges by _Monthly Active Users_ and never based on your total number of Users in the user table – so during this period you'll only be charged for users who create an active session within Clerk. Head to our [pricing page](/pricing) to get the full details on how Clerk charges.
-
-#### Determining the appropriate length of time
-
-As part of the trickle migration, you'll need to determine an appropriate length of time for the migration to take place. For some applications this might be a few weeks, but for others it might be more appropriate to run this for months. Your hard-costs, coordination costs, underlying complexity, and the amount of active users you expect in your migration time-window should guide your decision here.
-
-#### Dealing with inactive users
-
-A trickle migration is great for upgrading active users and sessions to take advantage of Clerk, but there will always be some users who won't create an active session within the migration window and will need to be migrated by other means, typically via [Basic Import / Export](#basic-export-import). A trickle migration lowers coordination risk because the remaining inactive users are fewer, so data de-synchronization risk drops, too.
-
-## Migration tools
-
-To aid in basic migrations, Clerk provides an open-source script that takes a JSON file as input, containing a list of users, and creates a user in Clerk using the Backend API. The script respects the [backend rate limits](/docs/backend-requests/resources/rate-limits#backend-api-requests) and gracefully handles errors. We suggest you customize the [Zod schema](https://github.com/clerk/migration-script/blob/main/index.ts#L25-L43){{ target: '_blank' }} to your application's needs.
-
-To use Clerk's migration script, clone the [repository](https://github.com/clerk/migration-script) and follow the instructions in the `README`.
-
-## Migration guides
-
-Clerk is hard at work writing up more specific migration guides and tools. If you're interested in specific guides, contact us at [https://feedback.clerk.com](https://feedback.clerk.com)
-
-
- - [Firebase](/docs/deployments/migrate-from-firebase)
- - Learn how to migrate from Firebase to Clerk quickly and easily.
-
diff --git a/docs/deployments/set-up-preview-environment.mdx b/docs/deployments/set-up-preview-environment.mdx
deleted file mode 100644
index fc049ede8b..0000000000
--- a/docs/deployments/set-up-preview-environment.mdx
+++ /dev/null
@@ -1,43 +0,0 @@
----
-title: Set up a preview environment with Clerk
-description: Learn how to set up a preview environment with Clerk authentication.
----
-
-Some popular hosting providers like Vercel and Netlify offer preview deployments, which enable you to view changes to your site in a live environment before merging and deploying them to production.
-
-There are two high-level approaches to using Clerk in a preview environment:
-
-1. Sharing production settings and user data
-1. Using independent settings and user data
-
-## Sharing production settings and user data
-
-To share production settings and user data with your preview environment, your preview environment must be hosted on the same root domain (but a separate subdomain) as your production application. The preview environment must also be configured to use the same API keys as your production environment.
-
-Generally, hosts have a special feature to host the preview environment on a subdomain of your root domain, for example:
-
-- **Vercel:** use the [Preview Deployment Suffix](https://vercel.com/docs/concepts/deployments/generated-urls#preview-deployment-suffix) feature. This feature is only available on Vercel's Pro and Enterprise plans.
-- **Netlify:** use the [Automatic Deploy Subdomain](https://docs.netlify.com/domains-https/custom-domains/automatic-deploy-subdomains/) feature.
-
-## Using independent settings and user data
-
-There are two approaches to creating a preview environment with independent settings and user data:
-
-1. **Easiest:** Use your host's provided preview domain, like \*.vercel.app or \*.netlify.app, with development API keys from Clerk.
-1. Acquire an additional root domain for your preview environment, completely separate from your production application's root domain.
-
-### Use your host's provided preview domain
-
-Configure the preview environment to use development API keys from Clerk. It is currently not possible to use Clerk production API keys with your host's provided preview domain.
-
-### Acquire an additional root domain
-
-> [!WARNING]
-> To use an independent environment, it is critical that you acquire an additional domain. An independent environment will not work if it is configured on the same domain as your production application, even if it is on a separate subdomain.
-
-To use an additional root domain, you must first configure your host to deploy preview environments to that domain:
-
-- **Vercel:** use the [Preview Deployment Suffix](https://vercel.com/docs/concepts/deployments/generated-urls#preview-deployment-suffix) feature. This feature is only available on Vercel's Pro and Enterprise plans.
-- **Netlify:** use the [Automatic Deploy Subdomain](https://docs.netlify.com/domains-https/custom-domains/automatic-deploy-subdomains/) feature.
-
-You can configure this environment with either your development API keys (recommended) or you can create an additional production instance and use those production API keys.
diff --git a/docs/deployments/set-up-staging.mdx b/docs/deployments/set-up-staging.mdx
deleted file mode 100644
index 2eafdbb04a..0000000000
--- a/docs/deployments/set-up-staging.mdx
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: Set up a staging environment with Clerk
-description: Learn how to set up a staging environment with Clerk authentication.
----
-
-Staging environments enable you to internally test and demo changes to your application or website before deploying them to production. Currently, Clerk only offers **Development** and **Production** instances. Official support for **Staging** instances is still on the [roadmap](https://feedback.clerk.com/roadmap/de417dd1-fa2e-4997-868f-4c9248027e7d). However, you can set up a "staging environment" by creating a subdomain for a separate Clerk application.
-
-Creating a separate Clerk application will prevent you from using live production environment data in your staging environment. If you are on a Pro, Enterprise, or Startup plan, **Clerk will fully upgrade your staging application for free.**
-
-It is important to note that when you use a separate Clerk application for your staging environment, changes to this application will not be automatically mirrored in your main application for your production environment. You must manually make these changes yourself if you want them to be reflected in both applications.
-
-## Set up a staging Clerk application
-
-The following steps will help you set up a new Clerk application with a staging-specific domain:
-
-1. **Set up a subdomain** - This will be your staging domain. For example, if your domain is `my-site.com`, you could use `staging.my-site.com`.
-1. **Create a new Clerk app** - Your staging environment will connect to this app instead of your main one. See [the Clerk quickstart guide](/docs/quickstarts/setup-clerk) to learn how to create a Clerk app.
-1. **Deploy and configure your staging app's production instance** - Using production API keys will make your staging app more secure. Follow the [Deploy to production](/docs/deployments/overview) guide to do so.
-1. **Contact Clerk support to upgrade your staging app for free** - If you are on a Pro, Enterprise, or Startup plan, Clerk will fully upgrade your staging app for free.
-
-## Alternatives
-
-### Preview environments
-
-While staging environments are typically long-lived, preview environments are typically generated on-demand for specific pull requests. See [the guide on using Clerk in a preview environment](/docs/deployments/set-up-preview-environment) to learn about your options.
-
-### Shared production credentials
-
-If you would like to share settings and data between your production and staging environments, see [the dedicated guide](/docs/deployments/staging-alternatives). This is not recommended because you will be sharing a user table between your production and staging environments.
diff --git a/docs/getting-started/core-concepts.mdx b/docs/getting-started/core-concepts.mdx
new file mode 100644
index 0000000000..63ab096c22
--- /dev/null
+++ b/docs/getting-started/core-concepts.mdx
@@ -0,0 +1,72 @@
+---
+title: Core concepts
+description: Learn about the main concepts and objects that drive Clerk's powerful authentication and user management system.
+---
+
+Before building your application, it's important to understand the core concepts and objects that drive Clerk's powerful authentication and user management system. This page walks through integration options, prebuilt components, configuration steps, and the key objects you'll use as you build your application.
+
+## Ways to implement Clerk
+
+Clerk provides three ways to integrate authentication into your application, depending on the level of control and customization you need:
+
+1. **[Account Portal](/docs/guides/customizing-clerk/account-portal) (default)**: Uses Clerk's prebuilt components on dedicated pages that are hosted on Clerk servers. Every Clerk application has this enabled by default, providing a complete user management interface out of the box.
+1. **[Prebuilt components](/docs/reference/components/overview)**: All-in-one UI components that can be integrated into your application. They are fully customizable to match your application's branding and design. This is the recommended approach for most use cases.
+1. **[Custom flows using the Clerk API](/docs/guides/development/custom-flows/overview)**: Build your own UI using the Clerk API. This option provides maximum flexibility and control over the user experience but requires more development effort.
+
+Clerk offers a comprehensive suite of prebuilt components designed to seamlessly integrate authentication and multi-tenancy into your application. Components, like ``, ``, and ``, are all-in-one solutions that handle the full lifecycle of the user experience, from sign-up/sign-in to user profile and organization management.
+
+The Account Portal uses these components on dedicated pages that are hosted on Clerk servers. These pages cannot be customized beyond the options provided in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=account-portal).
+
+For more control and customization, you can migrate away from the Account Portal and embed the prebuilt components directly into your own application pages. While they are [fully customizable](/docs/guides/customizing-clerk/appearance-prop/overview) to match your application's branding and design using CSS or special props, the HTML structure and the logic/ordering of the authentication flow remain fixed.
+
+If the prebuilt components don't meet your specific needs or if you need complete control over the logic, you can rebuild the existing Clerk flows using the Clerk API. However, this is more advanced and it's recommended to use the prebuilt components whenever possible.
+
+> [!TIP]
+> Most applications usually progress from the Account Portal to prebuilt components as they grow, with custom flows used for advanced cases.
+
+## Configuring your application
+
+Configuring your application is done through the [Clerk Dashboard](https://dashboard.clerk.com). The Clerk Dashboard is where you, as the application owner, can manage your application's settings, users, and organizations.
+
+For example, you can:
+
+- Enable phone number authentication or multi-factor authentication.
+- Add social providers like Google.
+- Delete users or create organizations.
+- Invite other users to your [workspace](/docs/guides/dashboard/overview#workspaces) to help configure and manage your application.
+
+To get started, see the [configuration docs](/docs/guides/configure/auth-strategies/sign-up-sign-in-options), which include dedicated guides for specific configuration options.
+
+## Building your application
+
+The Clerk JavaScript SDK, or ClerkJS, is where Clerk all started. It is the core SDK that powers all other JavaScript SDKs, including React and Next.js. The following sections will introduce you to the main objects that make up ClerkJS.
+
+### Clerk
+
+The [`Clerk`](/docs/reference/javascript/clerk) class is the main entry point for the Clerk JavaScript SDK. All other objects are accessible from the `Clerk` object. As you're building your application, you'll likely interact with these objects, either directly or through helpers provided by the other SDKs, like React hooks or Vue composables.
+
+### Client
+
+A client represents the current device or software accessing an application such as your web browser, native application, or Chrome Extension. It is represented by the [`Client`](/docs/reference/javascript/client) object.
+
+### Session
+
+A session is a secure representation of the authentication state of the current user. Each client can hold multiple sessions on the same device. It is represented by the [`Session`](/docs/reference/javascript/session) object.
+
+### User
+
+The [`User`](/docs/reference/javascript/user) object represents the current user of the session. It holds all the basic user information such as the user's name, email addresses, and phone numbers, and including their public, private, and unsafe metadata.
+
+### Organization
+
+Organizations are a flexible and scalable way to manage users and their access to resources within your Clerk application. With organizations, you can assign specific roles and permissions to users, making them useful for managing projects, coordinating teams, or facilitating partnerships.
+
+Users can belong to many organizations. One of them will be the ["active organization"](/docs/guides/organizations/overview#active-organization) of the session. It is represented by the [`Organization`](/docs/reference/javascript/organization) object. To learn about organizations, see the [dedicated guide](/docs/guides/organizations/overview).
+
+### Sign in
+
+The [`SignIn`](/docs/reference/javascript/sign-in) object holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. It is used to manage the sign-in lifecycle, including the first and second factor verification, and the creation of a new session.
+
+### Sign up
+
+The [`SignUp`](/docs/reference/javascript/sign-up) object holds the state of the current sign-up and provides helper methods to navigate and complete the sign-up process. Once a sign-up is complete, a new user is created.
diff --git a/docs/quickstarts/android.mdx b/docs/getting-started/quickstart.android.mdx
similarity index 97%
rename from docs/quickstarts/android.mdx
rename to docs/getting-started/quickstart.android.mdx
index 363853dc4f..f46ec6868a 100644
--- a/docs/quickstarts/android.mdx
+++ b/docs/getting-started/quickstart.android.mdx
@@ -31,7 +31,7 @@ sdk: android
1. In `app/build.gradle.kts`, add the following libraries to your `dependencies` block:
- - The [Clerk Android SDK](/docs/references/android/overview). Check the [GitHub release page](https://github.com/clerk/clerk-android/releases) for the latest version.
+ - The [Clerk Android SDK](/docs/reference/android/overview). Check the [GitHub release page](https://github.com/clerk/clerk-android/releases) for the latest version.
- [Android's Lifecycle ViewModel Compose library](https://developer.android.com/reference/kotlin/androidx/lifecycle/viewmodel/compose/package-summary).
```gradle
@@ -225,7 +225,7 @@ sdk: android
}
}
.onFailure {
- // See https://clerk.com/docs/custom-flows/error-handling
+ // See https://clerk.com/docs/guides/development/custom-flows/error-handling
// for more info on error handling
Log.e("SignUpViewModel", it.longErrorMessageOrNull, it.throwable)
}
@@ -238,7 +238,7 @@ sdk: android
inProgressSignUp.attemptVerification(SignUp.AttemptVerificationParams.EmailCode(code))
.onSuccess { _uiState.value = SignUpUiState.Success }
.onFailure {
- // See https://clerk.com/docs/custom-flows/error-handling
+ // See https://clerk.com/docs/guides/development/custom-flows/error-handling
// for more info on error handling
Log.e("SignUpViewModel", it.longErrorMessageOrNull, it.throwable)
}
@@ -525,7 +525,7 @@ sdk: android
Clerk.signOut()
.onSuccess { _uiState.value = MainUiState.SignedOut }
.onFailure {
- // See https://clerk.com/docs/custom-flows/error-handling
+ // See https://clerk.com/docs/guides/development/custom-flows/error-handling
// for more info on error handling
Log.e("MainViewModel", it.longErrorMessageOrNull, it.throwable)
}
diff --git a/docs/quickstarts/astro.mdx b/docs/getting-started/quickstart.astro.mdx
similarity index 75%
rename from docs/quickstarts/astro.mdx
rename to docs/getting-started/quickstart.astro.mdx
index 137839d8bc..77c482f268 100644
--- a/docs/quickstarts/astro.mdx
+++ b/docs/getting-started/quickstart.astro.mdx
@@ -28,7 +28,7 @@ sdk: astro
## Install `@clerk/astro`
- The [Clerk Astro SDK](/docs/references/astro/overview) provides a set of components, hooks, and stores that make it easy to build authentication and user management features in your Astro app.
+ The [Clerk Astro SDK](/docs/reference/astro/overview) provides a set of components, hooks, and stores that make it easy to build authentication and user management features in your Astro app.
Run the following command to install the SDK:
@@ -73,7 +73,7 @@ sdk: astro
To configure Clerk in your Astro app, you will need to update your `astro.config.mjs`.
- - Add the `clerk()` integration to the `integrations` list. For a list of available options, see the [integration reference](/docs/references/astro/integration).
+ - Add the `clerk()` integration to the `integrations` list. For a list of available options, see the [integration reference](/docs/reference/astro/integration).
- Install an [SSR adapter](https://docs.astro.build/en/guides/server-side-rendering/#official-adapters). This quickstart uses the [`@astrojs/node`](https://docs.astro.build/en/guides/integrations-guide/node/) adapter.
- Set `output` to `server`. This is required when deploying to a host supporting SSR.
@@ -91,7 +91,7 @@ sdk: astro
## Add `clerkMiddleware()` to your app
- [`clerkMiddleware()`](/docs/references/astro/clerk-middleware) grants you access to user authentication state throughout your app, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add `clerkMiddleware()` to your app, follow these steps:
+ [`clerkMiddleware()`](/docs/reference/astro/clerk-middleware) grants you access to user authentication state throughout your app, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add `clerkMiddleware()` to your app, follow these steps:
1. Create a `middleware.ts` file.
- If you're using the `/src` directory, create `middleware.ts` in the `/src` directory.
@@ -102,16 +102,16 @@ sdk: astro
export const onRequest = clerkMiddleware()
```
- 1. By default, `clerkMiddleware()` will not protect any routes. All routes are public and you must opt-in to protection for routes. See the [`clerkMiddleware()` reference](/docs/references/astro/clerk-middleware) to learn how to require authentication for specific routes.
+ 1. By default, `clerkMiddleware()` will not protect any routes. All routes are public and you must opt-in to protection for routes. See the [`clerkMiddleware()` reference](/docs/reference/astro/clerk-middleware) to learn how to require authentication for specific routes.
## Add Clerk components to your app
- You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/components/overview#control-components). Create a header using the following components:
+ You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/reference/components/overview#control-components). Create a header using the following components:
- - [``](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**.
- - [``](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**.
- - [``](/docs/components/user/user-button): Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.
- - [``](/docs/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page. In this example, since no props or [environment variables](/docs/deployments/clerk-environment-variables) are set for the sign-in URL, this component links to the [Account Portal sign-in page](/docs/account-portal/overview#sign-in).
+ - [``](/docs/reference/components/control/signed-in): Children of this component can only be seen while **signed in**.
+ - [``](/docs/reference/components/control/signed-out): Children of this component can only be seen while **signed out**.
+ - [``](/docs/reference/components/user/user-button): Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.
+ - [``](/docs/reference/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page. In this example, since no props or [environment variables](/docs/guides/development/clerk-environment-variables) are set for the sign-in URL, this component links to the [Account Portal sign-in page](/docs/guides/customizing-clerk/account-portal#sign-in).
```astro {{ filename: 'src/layouts/Layout.astro' }}
---
@@ -195,12 +195,12 @@ sdk: astro
## Next steps
- - [Protect routes using Clerk Middleware](/docs/references/astro/clerk-middleware)
+ - [Protect routes using Clerk Middleware](/docs/reference/astro/clerk-middleware)
- Learn how to protect specific routes from unauthenticated users.
---
- - [Read session and user data](/docs/references/astro/read-session-data)
+ - [Read session and user data](/docs/astro/guides/users/reading)
- Learn how to use Clerk's stores and helpers to access the active session and user data in your Astro app.
---
diff --git a/docs/quickstarts/chrome-extension.mdx b/docs/getting-started/quickstart.chrome-extension.mdx
similarity index 86%
rename from docs/quickstarts/chrome-extension.mdx
rename to docs/getting-started/quickstart.chrome-extension.mdx
index f3ffbd2138..3773957b9c 100644
--- a/docs/quickstarts/chrome-extension.mdx
+++ b/docs/getting-started/quickstart.chrome-extension.mdx
@@ -25,7 +25,7 @@ sdk: chrome-extension
## Configure your authentication options
- When creating your Clerk application in the Clerk Dashboard, your authentication options will depend on how you configure your Chrome Extension. Chrome Extensions can be used as a popup, a side panel, or in conjunction with a web app. Popups and side panels have limited authentication options. [Learn more about what options are available.](/docs/references/chrome-extension/overview#authentication-options)
+ When creating your Clerk application in the Clerk Dashboard, your authentication options will depend on how you configure your Chrome Extension. Chrome Extensions can be used as a popup, a side panel, or in conjunction with a web app. Popups and side panels have limited authentication options. [Learn more about what options are available.](/docs/reference/chrome-extension/overview#authentication-options)
This guide will use a popup.
@@ -44,7 +44,7 @@ sdk: chrome-extension
## Install `@clerk/chrome-extension`
- The [Clerk Chrome Extension SDK](/docs/references/chrome-extension/overview) gives you access to prebuilt components, React hooks, and helpers to make user authentication easier.
+ The [Clerk Chrome Extension SDK](/docs/reference/chrome-extension/overview) gives you access to prebuilt components, React hooks, and helpers to make user authentication easier.
Add the SDK to your project:
@@ -105,12 +105,12 @@ sdk: chrome-extension
## Create a header with Clerk components
- You can control what content signed in and signed out users can see with Clerk's [prebuilt components](/docs/components/overview). Create a header with the following Clerk components. (With Chrome Extensions, you can also add this logic to a footer).
+ You can control what content signed in and signed out users can see with Clerk's [prebuilt components](/docs/reference/components/overview). Create a header with the following Clerk components. (With Chrome Extensions, you can also add this logic to a footer).
- - [``](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**.
- - [``](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**.
- - [``](/docs/components/user/user-button): A prebuilt component that comes styled out-of-the-box to show the avatar from the account the user is signed in with.
- - [``](/docs/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page. For this example, because you have not specified any props or [environment variables](/docs/deployments/clerk-environment-variables) for the sign-in URL, the component will link to the [Account Portal sign-in page.](/docs/account-portal/overview)
+ - [``](/docs/reference/components/control/signed-in): Children of this component can only be seen while **signed in**.
+ - [``](/docs/reference/components/control/signed-out): Children of this component can only be seen while **signed out**.
+ - [``](/docs/reference/components/user/user-button): A prebuilt component that comes styled out-of-the-box to show the avatar from the account the user is signed in with.
+ - [``](/docs/reference/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page. For this example, because you have not specified any props or [environment variables](/docs/guides/development/clerk-environment-variables) for the sign-in URL, the component will link to the [Account Portal sign-in page](/docs/guides/customizing-clerk/account-portal#sign-in).
```tsx {{ filename: 'src/popup.tsx', mark: [[1, 7], [22, 29]] }}
import {
@@ -269,22 +269,22 @@ sdk: chrome-extension
> [!WARNING]
> After signing up or signing in, your popup may appear to crash. Closing and reopening the popup should restart the extension and you should be signed in.
>
- > Your extension does not yet have anything to handle routing, and by default, the Clerk components attempt to redirect the user. See [the guide on adding React Router to your Chrome Extension](/docs/references/chrome-extension/add-react-router) to add routing to your extension.
+ > Your extension does not yet have anything to handle routing, and by default, the Clerk components attempt to redirect the user. See [the guide on adding React Router to your Chrome Extension](/docs/guides/development/add-react-router) to add routing to your extension.
## Next steps
- - [Add React Router](/docs/references/chrome-extension/add-react-router)
+ - [Add React Router](/docs/guides/development/add-react-router)
- Learn how to add React Router to your Chrome Extension.
---
- - [Sync your Chrome Extension with your web app](/docs/references/chrome-extension/sync-host)
+ - [Sync your Chrome Extension with your web app](/docs/guides/sessions/sync-host)
- Learn how to configure your Chrome Extension to sync user authentication with your web application.
---
- - [createClerkClient()](/docs/references/chrome-extension/create-clerk-client)
+ - [createClerkClient()](/docs/reference/chrome-extension/create-clerk-client)
- For Chrome Extension's configured as popups, learn how to use Clerk's `createClerkClient()` function in a background service worker to ensure that the user's session is always fresh.
diff --git a/docs/quickstarts/expo.mdx b/docs/getting-started/quickstart.expo.mdx
similarity index 82%
rename from docs/quickstarts/expo.mdx
rename to docs/getting-started/quickstart.expo.mdx
index 29fc2c308d..988e55fd83 100644
--- a/docs/quickstarts/expo.mdx
+++ b/docs/getting-started/quickstart.expo.mdx
@@ -30,7 +30,7 @@ sdk: expo
## Install `@clerk/clerk-expo`
- The [Clerk Expo SDK](/docs/references/expo/overview) gives you access to prebuilt components, hooks, and helpers to make user authentication easier.
+ The [Clerk Expo SDK](/docs/reference/expo/overview) gives you access to prebuilt components, hooks, and helpers to make user authentication easier.
Run the following command to install the SDK:
@@ -136,18 +136,18 @@ sdk: expo
```
> [!TIP]
- > When you sign a user out with [`signOut()`](/docs/hooks/use-auth#returns), Clerk will remove the user's session JWT from the token cache.
+ > When you sign a user out with [`signOut()`](/docs/reference/hooks/use-auth#returns), Clerk will remove the user's session JWT from the token cache.
## Add sign-up and sign-in pages
- Clerk currently only supports [control components](/docs/components/overview#control-components) for Expo native. UI components are only available for Expo web. Instead, you must build [custom flows](/docs/custom-flows/overview) using Clerk's API. The following sections demonstrate how to build [custom email/password sign-up and sign-in flows](/docs/custom-flows/email-password). If you want to use different authentication methods, such as passwordless or OAuth, see the dedicated custom flow guides.
+ Clerk currently only supports [control components](/docs/reference/components/overview#control-components) for Expo native. UI components are only available for Expo web. Instead, you must build [custom flows](/docs/guides/development/custom-flows/overview) using Clerk's API. The following sections demonstrate how to build [custom email/password sign-up and sign-in flows](/docs/guides/development/custom-flows/authentication/email-password). If you want to use different authentication methods, such as passwordless or OAuth, see the dedicated custom flow guides.
### Layout page
First, protect your sign-up and sign-in pages.
1. Create an `(auth)` [route group](https://docs.expo.dev/router/advanced/shared-routes/). This will group your sign-up and sign-in pages.
- 1. In the `(auth)` group, create a `_layout.tsx` file with the following code. The [`useAuth()`](/docs/hooks/use-auth) hook is used to access the user's authentication state. If the user is already signed in, they will be redirected to the home page.
+ 1. In the `(auth)` group, create a `_layout.tsx` file with the following code. The [`useAuth()`](/docs/reference/hooks/use-auth) hook is used to access the user's authentication state. If the user is already signed in, they will be redirected to the home page.
```tsx {{ filename: 'app/(auth)/_layout.tsx' }}
import { Redirect, Stack } from 'expo-router'
@@ -166,7 +166,7 @@ sdk: expo
### Sign-up page
- In the `(auth)` group, create a `sign-up.tsx` file with the following code. The [`useSignUp()`](/docs/hooks/use-sign-up) hook is used to create a sign-up flow. The user can sign up using their email and password and will receive an email verification code to confirm their email.
+ In the `(auth)` group, create a `sign-up.tsx` file with the following code. The [`useSignUp()`](/docs/reference/hooks/use-sign-up) hook is used to create a sign-up flow. The user can sign up using their email and password and will receive an email verification code to confirm their email.
```tsx {{ filename: 'app/(auth)/sign-up.tsx', collapsible: true }}
import * as React from 'react'
@@ -203,7 +203,7 @@ sdk: expo
// and capture OTP code
setPendingVerification(true)
} catch (err) {
- // See https://clerk.com/docs/custom-flows/error-handling
+ // See https://clerk.com/docs/guides/development/custom-flows/error-handling
// for more info on error handling
console.error(JSON.stringify(err, null, 2))
}
@@ -230,7 +230,7 @@ sdk: expo
console.error(JSON.stringify(signUpAttempt, null, 2))
}
} catch (err) {
- // See https://clerk.com/docs/custom-flows/error-handling
+ // See https://clerk.com/docs/guides/development/custom-flows/error-handling
// for more info on error handling
console.error(JSON.stringify(err, null, 2))
}
@@ -285,7 +285,7 @@ sdk: expo
### Sign-in page
- In the `(auth)` group, create a `sign-in.tsx` file with the following code. The [`useSignIn()`](/docs/hooks/use-sign-in) hook is used to create a sign-in flow. The user can sign in using email address and password, or navigate to the sign-up page.
+ In the `(auth)` group, create a `sign-in.tsx` file with the following code. The [`useSignIn()`](/docs/reference/hooks/use-sign-in) hook is used to create a sign-in flow. The user can sign in using email address and password, or navigate to the sign-up page.
```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }}
import { useSignIn } from '@clerk/clerk-expo'
@@ -322,7 +322,7 @@ sdk: expo
console.error(JSON.stringify(signInAttempt, null, 2))
}
} catch (err) {
- // See https://clerk.com/docs/custom-flows/error-handling
+ // See https://clerk.com/docs/guides/development/custom-flows/error-handling
// for more info on error handling
console.error(JSON.stringify(err, null, 2))
}
@@ -357,22 +357,22 @@ sdk: expo
}
```
- For more information about building these custom flows, including guided comments in the code examples, see the [Build a custom email/password authentication flow](/docs/custom-flows/email-password) guide.
+ For more information about building these custom flows, including guided comments in the code examples, see the [Build a custom email/password authentication flow](/docs/guides/development/custom-flows/authentication/email-password) guide.
## Add a sign-out button
At this point, your users can sign up or in, but they need a way to sign out.
- In the `components/` folder, create a `SignOutButton.tsx` file with the following code. The [`useClerk()`](/docs/hooks/use-clerk) hook is used to access the `signOut()` function, which is called when the user clicks the "Sign out" button.
+ In the `components/` folder, create a `SignOutButton.tsx` file with the following code. The [`useClerk()`](/docs/reference/hooks/use-clerk) hook is used to access the `signOut()` function, which is called when the user clicks the "Sign out" button.
## Conditionally render content
- You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/components/overview#control-components). For this quickstart, you'll use:
+ You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/reference/components/overview#control-components). For this quickstart, you'll use:
- - [``](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**.
- - [``](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**.
+ - [``](/docs/reference/components/control/signed-in): Children of this component can only be seen while **signed in**.
+ - [``](/docs/reference/components/control/signed-out): Children of this component can only be seen while **signed out**.
To get started:
@@ -451,21 +451,21 @@ See the [`expo-updates`](https://docs.expo.dev/versions/latest/sdk/updates) libr
## Next steps
- - [OAuth with Expo](/docs/custom-flows/oauth-connections)
+ - [OAuth with Expo](/docs/guides/development/custom-flows/authentication/oauth-connections)
- Learn more how to build a custom OAuth flow with Expo.
---
- - [MFA with Expo](/docs/custom-flows/email-password-mfa)
+ - [MFA with Expo](/docs/guides/development/custom-flows/authentication/email-password-mfa)
- Learn more how to build a custom multi-factor authentication flow with Expo.
---
- - [Read session and user data](/docs/references/expo/read-session-user-data)
+ - [Read session and user data](/docs/expo/guides/users/reading)
- Learn how to read session and user data with Expo.
---
- - [Sign-up and sign-in flow](/docs/custom-flows/email-password)
+ - [Sign-up and sign-in flow](/docs/guides/development/custom-flows/authentication/email-password)
- Learn how to build a custom sign-up and sign-in authentication flow.
diff --git a/docs/quickstarts/express.mdx b/docs/getting-started/quickstart.expressjs.mdx
similarity index 79%
rename from docs/quickstarts/express.mdx
rename to docs/getting-started/quickstart.expressjs.mdx
index cf179f5fde..c2252b1491 100644
--- a/docs/quickstarts/express.mdx
+++ b/docs/getting-started/quickstart.expressjs.mdx
@@ -30,7 +30,7 @@ Learn how to integrate Clerk into your Express backend for secure user authentic
## Install `@clerk/express`
- The [Clerk Express SDK](/docs/references/express/overview) provides a range of backend utilities to simplify user authentication and management in your application.
+ The [Clerk Express SDK](/docs/reference/express/overview) provides a range of backend utilities to simplify user authentication and management in your application.
Run the following command to install the SDK:
@@ -93,7 +93,7 @@ Learn how to integrate Clerk into your Express backend for secure user authentic
## Add `clerkMiddleware()` to your app
- The [`clerkMiddleware()`](/docs/references/express/overview#clerk-middleware) function checks the request's cookies and headers for a session JWT and, if found, attaches the [`Auth`](/docs/references/backend/types/auth-object){{ target: '_blank' }} object to the `request` object under the `auth` key.
+ The [`clerkMiddleware()`](/docs/reference/express/overview#clerk-middleware) function checks the request's cookies and headers for a session JWT and, if found, attaches the [`Auth`](/docs/reference/backend/types/auth-object){{ target: '_blank' }} object to the `request` object under the `auth` key.
```ts {{ filename: 'index.ts', mark: [3, 8] }}
import 'dotenv/config'
@@ -113,9 +113,9 @@ Learn how to integrate Clerk into your Express backend for secure user authentic
## Protect your routes using `requireAuth()`
- To protect your routes, use the [`requireAuth()`](/docs/references/express/overview#require-auth) middleware. This middleware functions similarly to `clerkMiddleware()`, but also protects your routes by redirecting unauthenticated users to the sign-in page.
+ To protect your routes, use the [`requireAuth()`](/docs/reference/express/overview#require-auth) middleware. This middleware functions similarly to `clerkMiddleware()`, but also protects your routes by redirecting unauthenticated users to the sign-in page.
- In the following example, `requireAuth()` is used to protect the `/protected` route. If the user isn't authenticated, they're redirected to the homepage. If the user is authenticated, the [`getAuth()`](/docs/references/express/overview#get-auth) function is used to get the `userId`, which is passed to [`clerkClient.users.getUser()`](/docs/references/backend/user/get-user){{ target: '_blank' }} to fetch the current user's `User` object.
+ In the following example, `requireAuth()` is used to protect the `/protected` route. If the user isn't authenticated, they're redirected to the homepage. If the user is authenticated, the [`getAuth()`](/docs/reference/express/overview#get-auth) function is used to get the `userId`, which is passed to [`clerkClient.users.getUser()`](/docs/reference/backend/user/get-user){{ target: '_blank' }} to fetch the current user's `User` object.
```ts {{ filename: 'index.ts' }}
import 'dotenv/config'
@@ -131,7 +131,7 @@ Learn how to integrate Clerk into your Express backend for secure user authentic
// Use `getAuth()` to get the user's `userId`
const { userId } = getAuth(req)
- // Use Clerk's JavaScript Backend SDK to get the user's User object
+ // Use Clerk's JS Backend SDK to get the user's User object
const user = await clerkClient.users.getUser(userId)
return res.json({ user })
@@ -158,21 +158,21 @@ Learn how to integrate Clerk into your Express backend for secure user authentic
## Next steps
- - [Use middleware to protect routes](/docs/references/express/overview#require-auth)
+ - [Use middleware to protect routes](/docs/reference/express/overview#require-auth)
- Learn how to protect specific routes from unauthenticated users.
---
- - [Protect routes based on authorization status](/docs/references/express/overview#get-auth)
+ - [Protect routes based on authorization status](/docs/reference/express/overview#get-auth)
- Learn how to protect a route based on both authentication and authorization status.
---
- - [Express SDK reference](/docs/references/express/overview)
+ - [Express SDK reference](/docs/reference/express/overview)
- Learn more about additional Express SDK methods.
---
- - [Deploy to Production](/docs/deployments/overview)
+ - [Deploy to Production](/docs/guides/development/deployment/production)
- Learn how to deploy your Clerk app to production.
diff --git a/docs/quickstarts/fastify.mdx b/docs/getting-started/quickstart.fastify.mdx
similarity index 93%
rename from docs/quickstarts/fastify.mdx
rename to docs/getting-started/quickstart.fastify.mdx
index fd0d8a1f68..9c60e653a4 100644
--- a/docs/quickstarts/fastify.mdx
+++ b/docs/getting-started/quickstart.fastify.mdx
@@ -80,7 +80,7 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic
The `clerkPlugin()` function is a Fastify plugin provided by Clerk to integrate authentication into your Fastify application. To ensure that Clerk's authentication and user management features are applied across your Fastify application, configure the `clerkPlugin()` to handle all routes or limit it to specific ones.
- The following example registers the plugin for all routes. To register the plugin for specific routes, see the [reference docs](/docs/references/fastify/overview).
+ The following example registers the plugin for all routes. To register the plugin for specific routes, see the [reference docs](/docs/reference/fastify/overview).
> [!IMPORTANT]
> The `dotenv/config` module must be imported before any Clerk modules. This order is important because Clerk instances are created during the import process and rely on environment variables, such as API keys, to be initialized correctly. For more information, refer to the [Fastify docs](https://fastify.dev/docs/latest/Guides/Getting-Started/#loading-order-of-your-plugins).
@@ -108,7 +108,7 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic
## Protect your routes using `getAuth()`
- The [`getAuth()`](/docs/references/fastify/overview#get-auth) helper retrieves the current user's authentication state from the `request` object. It returns the [`Auth` object](/docs/references/backend/types/auth-object){{ target: '_blank' }}.
+ The [`getAuth()`](/docs/reference/fastify/overview#get-auth) helper retrieves the current user's authentication state from the `request` object. It returns the [`Auth` object](/docs/reference/backend/types/auth-object){{ target: '_blank' }}.
diff --git a/docs/references/go/overview.mdx b/docs/getting-started/quickstart.go.mdx
similarity index 63%
rename from docs/references/go/overview.mdx
rename to docs/getting-started/quickstart.go.mdx
index f33d08c931..01c5d78501 100644
--- a/docs/references/go/overview.mdx
+++ b/docs/getting-started/quickstart.go.mdx
@@ -4,7 +4,7 @@ description: Learn how to integrate Clerk into your Go application using the Cle
sdk: go
---
-The Clerk Go SDK is built on top of the [Clerk Backend API](/docs/reference/backend-api){{ target: '_blank' }}.
+The [Clerk Go SDK](/docs/reference/go/overview) is built on top of the [Clerk Backend API](/docs/reference/backend-api){{ target: '_blank' }}.
## Installation
@@ -92,11 +92,84 @@ func main() {
}
```
+#### Example
+
+The following example demonstrates how to use the Clerk Go SDK to execute [Clerk Backend API](/docs/reference/backend-api){{ target: '_blank' }} operations.
+
+By executing the code in the snippet below, you will:
+
+- Create an organization and update its slug.
+- Fetch all organization memberships and loop through them to get the first one.
+- Get more details about the organization's user.
+
+> [!NOTE]
+> Your Clerk Secret Key is required. If you're signed into the Clerk Dashboard, your Secret Key should become visible by selecting the eye icon. Otherwise, you can retrieve your Clerk Secret Key on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard.
+
+```go {{ filename: 'main.go' }}
+import (
+ "github.com/clerk/clerk-sdk-go/v2"
+ "github.com/clerk/clerk-sdk-go/v2/organization"
+ "github.com/clerk/clerk-sdk-go/v2/organizationmembership"
+ "github.com/clerk/clerk-sdk-go/v2/user"
+)
+
+func main() {
+ // Each API operation requires a context.Context as the first argument.
+ ctx := context.Background()
+
+ // Set the API key
+ clerk.SetKey("{{secret}}")
+
+ // Create an organization
+ org, err := organization.Create(ctx, &organization.CreateParams{
+ Name: clerk.String("Clerk Inc"),
+ })
+ if err != nil {
+ // You can get additional information on the error, if it can
+ // be type-cast to clerk.APIErrorResponse.
+ if apiErr, ok := err.(*clerk.APIErrorResponse); ok {
+ apiErr.TraceID
+ apiErr.Error()
+ apiErr.Response.RawJSON
+ }
+ // handle the error
+ panic(err)
+ }
+
+ // Update the organization
+ org, err = organization.Update(ctx, org.ID, &organization.UpdateParams{
+ Slug: clerk.String("clerk"),
+ })
+ if err != nil {
+ // handle the error
+ panic(err)
+ }
+
+ // List organization memberships
+ listParams := organizationmembership.ListParams{}
+ listParams.Limit = clerk.Int64(10)
+ memberships, err := organizationmembership.List(ctx, params)
+ if err != nil {
+ // handle the error
+ panic(err)
+ }
+ if memberships.TotalCount < 0 {
+ return
+ }
+ membership := memberships[0]
+
+ // Get a user
+ usr, err := user.Get(ctx, membership.UserID)
+ if err != nil {
+ // handle the error
+ panic(err)
+ }
+}
+```
+
### Usage with a client
-If you're working with multiple keys, it's recommended to use Clerk Go with a client. The API packages for each
-resource export a `Client`, which supports all the API's operations.
-This way, you can create as many clients as needed, each with their own API key, as shown in the following example:
+If you're working with multiple keys, it's recommended to use Clerk Go with a client. The API packages for each resource export a `Client`, which supports all the API's operations. This way, you can create as many clients as needed, each with their own API key, as shown in the following example:
```go {{ filename: 'main.go' }}
package main
@@ -145,5 +218,3 @@ func main() {
}
}
```
-
-For more usage details, see the [examples](/docs/references/go/other-examples) or the library's [README file](https://github.com/clerk/clerk-sdk-go/tree/v2).
diff --git a/docs/quickstarts/ios.mdx b/docs/getting-started/quickstart.ios.mdx
similarity index 90%
rename from docs/quickstarts/ios.mdx
rename to docs/getting-started/quickstart.ios.mdx
index 0bfdc5ecd4..d9ff42f7f6 100644
--- a/docs/quickstarts/ios.mdx
+++ b/docs/getting-started/quickstart.ios.mdx
@@ -137,9 +137,9 @@ icon: "clerk",
The updated `ContentView` uses two key Clerk components:
- - [`AuthView`](/docs/references/ios/auth-view): A comprehensive authentication view that handles sign-in and sign-up flows, including email verification, password reset, and multi-factor authentication. It's presented as a sheet when the user taps "Sign in".
+ - [`AuthView`](/docs/reference/ios/auth-view): A comprehensive authentication view that handles sign-in and sign-up flows, including email verification, password reset, and multi-factor authentication. It's presented as a sheet when the user taps "Sign in".
- - [`UserButton`](/docs/references/ios/user-button): A circular button that displays the user's profile image. When tapped, it automatically presents the [`UserProfileView`](/docs/references/ios/user-profile-view) where users can manage their account, update their profile, and sign out.
+ - [`UserButton`](/docs/reference/ios/user-button): A circular button that displays the user's profile image. When tapped, it automatically presents the [`UserProfileView`](/docs/reference/ios/user-profile-view) where users can manage their account, update their profile, and sign out.
## Create your first user
diff --git a/docs/references/backend/overview.mdx b/docs/getting-started/quickstart.js-backend.mdx
similarity index 77%
rename from docs/references/backend/overview.mdx
rename to docs/getting-started/quickstart.js-backend.mdx
index fa236863ff..4c7be4fd79 100644
--- a/docs/references/backend/overview.mdx
+++ b/docs/getting-started/quickstart.js-backend.mdx
@@ -4,15 +4,15 @@ description: The JavaScript Backend SDK exposes Clerk's Backend API resources an
sdk: js-backend
---
-Clerk's JavaScript Backend SDK exposes the [Backend API](/docs/reference/backend-api){{ target: '_blank' }} resources and low-level authentication utilities **for JavaScript environments**.
+[Clerk's JavaScript Backend SDK](/docs/reference/backend/overview) exposes the [Backend API](/docs/reference/backend-api){{ target: '_blank' }} resources and low-level authentication utilities **for JavaScript environments**.
-For example, if you wanted to get a list of all users in your application, instead of creating a fetch to [`https://api.clerk.com/v1/users`](/docs/reference/backend-api/tag/users/get/users){{ target: '_blank' }} endpoint, you can use the [`users.getUserList()`](/docs/references/backend/user/get-user-list) method provided by the JavaScript Backend SDK.
+For example, if you wanted to get a list of all users in your application, instead of creating a fetch to [`https://api.clerk.com/v1/users`](/docs/reference/backend-api/tag/users/get/users){{ target: '_blank' }} endpoint, you can use the [`users.getUserList()`](/docs/reference/backend/user/get-user-list) method provided by the JS Backend SDK.
## Installation
-
+
- If you are using the JavaScript Backend SDK on its own, you can install it using the following command:
+ If you are using the JS Backend SDK on its own, you can install it using the following command:
```bash {{ filename: 'terminal' }}
@@ -34,7 +34,7 @@ For example, if you wanted to get a list of all users in your application, inste
- Clerk SDKs expose an instance of the JavaScript Backend SDK for use in server environments, so there is no need to install it separately.
+ Clerk SDKs expose an instance of the JS Backend SDK for use in server environments, so there is no need to install it separately.
@@ -44,7 +44,7 @@ All resource operations are mounted as sub-APIs on the `clerkClient` object. For
To access a resource, you must first instantiate a `clerkClient` instance.
-
+
To instantiate a `clerkClient` instance, you must call `createClerkClient()` and pass in [`options`](#create-clerk-client-options).
@@ -63,7 +63,7 @@ To access a resource, you must first instantiate a `clerkClient` instance.
You can use the default instance of `clerkClient` provided by whichever SDK you are using, and skip the need to pass [configuration options](#create-clerk-client-options), unless you are using Remix. For Remix, see the following section.
- To use the default `clerkClient` instance, set your `CLERK_SECRET_KEY` [environment variable](/docs/deployments/clerk-environment-variables#clerk-publishable-and-secret-keys) and then import the `clerkClient` instance from the SDK as shown in the following example:
+ To use the default `clerkClient` instance, set your `CLERK_SECRET_KEY` [environment variable](/docs/guides/development/clerk-environment-variables#clerk-publishable-and-secret-keys) and then import the `clerkClient` instance from the SDK as shown in the following example:
@@ -103,7 +103,7 @@ To access a resource, you must first instantiate a `clerkClient` instance.
### Instantiate a custom `clerkClient` instance
- If you would like to customize the behavior of the JavaScript Backend SDK, you can instantiate a `clerkClient` instance yourself by calling `createClerkClient()` and passing in [`options`](#create-clerk-client-options).
+ If you would like to customize the behavior of the JS Backend SDK, you can instantiate a `clerkClient` instance yourself by calling `createClerkClient()` and passing in [`options`](#create-clerk-client-options).
@@ -125,7 +125,7 @@ To access a resource, you must first instantiate a `clerkClient` instance.
import { createClerkClient } from '@clerk/remix/api.server'
```
- Use the following tabs to see examples of how to use the Backend SDK in Remix Loader and Action functions.
+ Use the following tabs to see examples of how to use the JS Backend SDK in Remix Loader and Action functions.
@@ -170,16 +170,13 @@ To access a resource, you must first instantiate a `clerkClient` instance.
return redirect('/sign-in?redirect_url=' + args.request.url)
}
- // Prepare the data for the mutation
- const params = { firstName: 'John', lastName: 'Wicker' }
-
- // Initialize clerkClient and perform the mutations
- const updatedUser = await createClerkClient({
- secretKey: process.env.CLERK_SECRET_KEY,
- }).users.updateUser(userId, params)
-
- // Return the updated user
- return { serialisedUser: JSON.stringify(updatedUser) }
+ // Initialize clerkClient and perform the action,
+ // which in this case is to get the user
+ const user = await createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }).users.getUser(
+ userId,
+ )
+ // Return the user
+ return { serialisedUser: JSON.stringify(user) }
}
```
@@ -276,7 +273,7 @@ To access a resource, you must first instantiate a `clerkClient` instance.
## Error handling
-Backend SDK functions throw errors (`ClerkAPIResponseError`) when something goes wrong. You'll need to catch them in a `try/catch` block and handle them gracefully. For example:
+JS Backend SDK functions throw errors (`ClerkAPIResponseError`) when something goes wrong. You'll need to catch them in a `try/catch` block and handle them gracefully. For example:
```ts {{ filename: 'example.ts' }}
try {
@@ -288,7 +285,7 @@ try {
## `createClerkClient({ options })`
-The `createClerkClient()` function requires an `options` object. It is recommended to set these options as [environment variables](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
+The `createClerkClient()` function requires an `options` object. It is recommended to set these options as [environment variables](/docs/guides/development/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
The following options are available:
@@ -296,13 +293,13 @@ The following options are available:
## Get the `userId` and other properties
-The [`Auth`](/docs/references/backend/types/auth-object) object contains important information like the current user's session ID, user ID, and organization ID.
+The [`Auth`](/docs/reference/backend/types/auth-object) object contains important information like the current user's session ID, user ID, and organization ID.
-
+
- The following example demonstrates how to retrieve the authenticated user's ID using `request.auth` when you're not using a specific framework helper. It also shows how to use the Backend SDK's [`getUser()`](/docs/references/backend/user/get-user) method to get the [Backend `User` object](/docs/references/backend/types/backend-user).
+ The following example demonstrates how to retrieve the authenticated user's ID using `request.auth` when you're not using a specific framework helper. It also shows how to use the JS Backend SDK's [`getUser()`](/docs/reference/backend/user/get-user) method to get the [Backend `User` object](/docs/reference/backend/types/backend-user).
```js
import { createClerkClient } from '@clerk/backend'
@@ -318,7 +315,7 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
return null
}
- // Use the Backend SDK's `getUser()` method to get the Backend User object
+ // Use the JS Backend SDK's `getUser()` method to get the Backend User object
const user = await clerkClient.users.getUser(userId)
// Return the Backend User object
@@ -328,13 +325,13 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
- The following examples demonstrate how to retrieve the authenticated user's ID using framework-specific auth helpers and how to use the Backend SDK's [`getUser()`](/docs/references/backend/user/get-user) method to get the [Backend `User` object](/docs/references/backend/types/backend-user).
+ The following examples demonstrate how to retrieve the authenticated user's ID using framework-specific auth helpers and how to use the JS Backend SDK's [`getUser()`](/docs/reference/backend/user/get-user) method to get the [Backend `User` object](/docs/reference/backend/types/backend-user).
- {/* TODO: The following Tabs example is duplicated in the backend-requests/resources/session-tokens.mdx file. It cannot be a partial to be reused across both files because this example includes a partial and partials cannot include partials. Also, the text in each of these tabs is removed in the other file as its not relevant to that file's example. So keep these two Tabs examples in sync please. */}
+ {/* TODO: The following Tabs example is duplicated in the guides/how-clerk-works/session-tokens.mdx file. It cannot be a partial to be reused across both files because this example includes a partial and partials cannot include partials. Also, the text in each of these tabs is removed in the other file as its not relevant to that file's example. So keep these two Tabs examples in sync please. */}
- For Next.js, the `Auth` object is accessed using the `auth()` helper in App Router apps and the `getAuth()` function in Pages Router apps. [Learn more about using these helpers](/docs/references/nextjs/read-session-data#server-side).
+ For Next.js, the `Auth` object is accessed using the `auth()` helper in App Router apps and the `getAuth()` function in Pages Router apps. [Learn more about using these helpers](/docs/nextjs/guides/users/reading#server-side).
Use the following tabs to see examples of how to use these helpers to access the user's ID in your App Router or Pages Router app.
@@ -353,7 +350,7 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
const client = await clerkClient()
- // Use the Backend SDK's `getUser()` method to get the Backend User object
+ // Use the JS Backend SDK's `getUser()` method to get the Backend User object
const user = await client.users.getUser(userId)
// Return the Backend User object
@@ -366,7 +363,7 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
- For Astro, the `Auth` object is accessed using the `locals.auth()` function. [Learn more about using `locals.auth()`](/docs/references/astro/read-session-data#server-side).
+ For Astro, the `Auth` object is accessed using the `locals.auth()` function. [Learn more about using `locals.auth()`](/docs/astro/guides/users/reading#server-side).
```tsx {{ filename: 'src/api/example.ts' }}
import { clerkClient } from '@clerk/astro/server'
@@ -380,7 +377,7 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
return new Response('Unauthorized', { status: 401 })
}
- // Use the Backend SDK's `getUser()` method to get the Backend User object
+ // Use the JS Backend SDK's `getUser()` method to get the Backend User object
const user = await clerkClient(context).users.getUser(userId)
// Return the Backend User object
@@ -390,7 +387,7 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
- For Express, the `Auth` object is accessed using the `getAuth()` function. [Learn more about using `getAuth()`](/docs/references/express/overview#get-auth).
+ For Express, the `Auth` object is accessed using the `getAuth()` function. [Learn more about using `getAuth()`](/docs/reference/express/overview#get-auth).
```js {{ filename: 'index.js' }}
import { createClerkClient, getAuth } from '@clerk/express'
@@ -408,7 +405,7 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
res.status(401).json({ error: 'User not authenticated' })
}
- // Use the Backend SDK's `getUser()` method to get the Backend User object
+ // Use the JS Backend SDK's `getUser()` method to get the Backend User object
const user = await clerkClient.users.getUser(userId)
// Return the Backend User object
@@ -418,9 +415,9 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
- For React Router, the `Auth` object is accessed using the `getAuth()` function. [Learn more about using `getAuth()`](/docs/references/react-router/read-session-data#server-side).
+ For React Router, the `Auth` object is accessed using the `getAuth()` function. [Learn more about using `getAuth()`](/docs/react-router/guides/users/reading#server-side).
- ```tsx {{ filename: 'src/routes/profile.tsx' }}
+ ```tsx {{ filename: 'app/routes/profile.tsx' }}
import { redirect } from 'react-router'
import { getAuth } from '@clerk/react-router/ssr.server'
import { createClerkClient } from '@clerk/react-router/api.server'
@@ -435,7 +432,7 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
return redirect('/sign-in?redirect_url=' + args.request.url)
}
- // Use the Backend SDK's `getUser()` method to get the Backend User object
+ // Use the JS Backend SDK's `getUser()` method to get the Backend User object
const user = await createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }).users.getUser(
userId,
)
@@ -449,7 +446,7 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
- For Remix, the `Auth` object is accessed using the `getAuth()` function. [Learn more about using `getAuth()`](/docs/references/remix/read-session-data#get-auth). Use the following tabs to see examples of how to use the `getAuth()` helper to get the user's ID in Remix Loader and Action functions.
+ For Remix, the `Auth` object is accessed using the `getAuth()` function. [Learn more about using `getAuth()`](/docs/remix/guides/users/reading#get-auth). Use the following tabs to see examples of how to use the `getAuth()` helper to get the user's ID in Remix Loader and Action functions.
```tsx {{ filename: 'routes/profile.tsx' }}
@@ -461,12 +458,12 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
// Use `getAuth()` to access `isAuthenticated` and the user's ID
const { isAuthenticated, userId } = await getAuth(args)
- // Protect the route by checking if the user is signed in
+ // If there is no userId, then redirect to sign-in route
if (!isAuthenticated) {
return redirect('/sign-in?redirect_url=' + args.request.url)
}
- // Use the Backend SDK's `getUser()` method to get the Backend User object
+ // Use the JS Backend SDK's `getUser()` method to get the Backend User object
const user = await createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }).users.getUser(
userId,
)
@@ -485,28 +482,24 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
// Use `getAuth()` to access `isAuthenticated` and the user's ID
const { isAuthenticated, userId } = await getAuth(args)
- // Protect the route by checking if the user is signed in
+ // If there is no userId, then redirect to sign-in route
if (!isAuthenticated) {
return redirect('/sign-in?redirect_url=' + args.request.url)
}
- // Prepare the data for the mutation
- const params = { firstName: 'John', lastName: 'Wicker' }
-
- // // Use the Backend SDK's `updateUser()` method to update the Backend User object
- const updatedUser = await createClerkClient({
- secretKey: process.env.CLERK_SECRET_KEY,
- }).users.updateUser(userId, params)
+ const user = await createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }).users.getUser(
+ userId,
+ )
- // Return the updated user
- return { serialisedUser: JSON.stringify(updatedUser) }
+ // Return the user
+ return { serialisedUser: JSON.stringify(user) }
}
```
- For Tanstack React Start, the `Auth` object is accessed using the `getAuth()` function. [Learn more about using `getAuth()`](/docs/references/tanstack-react-start/read-session-data#server-side).
+ For Tanstack React Start, the `Auth` object is accessed using the `getAuth()` function. [Learn more about using `getAuth()`](/docs/tanstack-react-start/guides/users/reading#server-side).
```tsx {{ filename: 'app/routes/api/example.tsx' }}
import { createClerkClient } from '@clerk/backend'
@@ -524,10 +517,10 @@ The [`Auth`](/docs/references/backend/types/auth-object) object contains importa
return json({ error: 'Unauthorized' }, { status: 401 })
}
- // Instantiate the Backend SDK
+ // Instantiate the JS Backend SDK
const clerkClient = createClerkClient({ secretKey: import.meta.env.CLERK_SECRET_KEY })
- // Use the Backend SDK's `getUser()` method to get the Backend User object
+ // Use the JS Backend SDK's `getUser()` method to get the Backend User object
const user = await clerkClient.users.getUser(userId)
// Return the Backend User object
diff --git a/docs/quickstarts/javascript.mdx b/docs/getting-started/quickstart.js-frontend.mdx
similarity index 85%
rename from docs/quickstarts/javascript.mdx
rename to docs/getting-started/quickstart.js-frontend.mdx
index 01cdc96d5d..259fcf493a 100644
--- a/docs/quickstarts/javascript.mdx
+++ b/docs/getting-started/quickstart.js-frontend.mdx
@@ -21,7 +21,7 @@ sdk: js-frontend
]}
/>
-To add the [JavaScript SDK](/docs/references/javascript/overview) to your JavaScript app, you have two options:
+To add the [JavaScript SDK](/docs/reference/javascript/overview) to your JavaScript app, you have two options:
1. Install the package using a package manager, like `npm`.
1. Use the `