diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 28f2cb1698..7b1f6158d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to Clerk's documentation -Thanks for being willing to contribute to [Clerk's documentation](https://clerk.com/docs)! This document outlines how to effectively contribute to the documentation content located in this repository. Check out the [style guide](./styleguides/styleguide.md) for more information on our guidelines for writing content. +Thanks for being willing to contribute to [Clerk's documentation](https://clerk.com/docs)! This document outlines how to effectively contribute to the documentation content located in this repository. See the [style guide](./styleguides/styleguide.md) for more information on our guidelines for writing content. ## Written in MDX @@ -396,8 +396,8 @@ interface CodeBlockProps { You can use the following shortcodes within a code block to inject information from the user's current Clerk instance: -- `{{pub_key}}` – Publishable key -- `{{secret}}` – Secret key +- `{{pub_key}}` – Publishable Key +- `{{secret}}` – Secret Key - `{{fapi_url}}` – Frontend API URL ````mdx @@ -407,7 +407,7 @@ CLERK_SECRET_KEY={{secret}} ``` ```` -The video below shows what this example looks like once rendered. Notice the eye icon on the code block that once clicked on, reveals the user's secret key. +The video below shows what this example looks like once rendered. Notice the eye icon on the code block that once clicked on, reveals the user's Secret Key. https://github.com/clerk/clerk-docs/assets/2615508/c1f3fc23-5581-481c-a89c-10c6a04b8536 diff --git a/docs/_partials/authenticate-req.mdx b/docs/_partials/authenticate-req.mdx new file mode 100644 index 0000000000..b3135e8205 --- /dev/null +++ b/docs/_partials/authenticate-req.mdx @@ -0,0 +1,23 @@ +```tsx +import { createClerkClient } from '@clerk/backend' + +export async function GET(req: Request) { + const clerkClient = createClerkClient({ + secretKey: process.env.CLERK_SECRET_KEY, + publishableKey: process.env.CLERK_PUBLISHABLE_KEY, + }) + + const { isSignedIn } = await clerkClient.authenticateRequest(req, { + jwtKey: process.env.CLERK_JWT_KEY, + authorizedParties: ['https://example.com'], + }) + + if (!isSignedIn) { + return Response.json({ status: 401 }) + } + + // Add logic to perform protected actions + + return Response.json({ message: 'This is a reply' }) +} +``` diff --git a/docs/_partials/reverification-route-handler.mdx b/docs/_partials/reverification-route-handler.mdx new file mode 100644 index 0000000000..acdc4f0248 --- /dev/null +++ b/docs/_partials/reverification-route-handler.mdx @@ -0,0 +1,20 @@ +The following example uses the [`has()`](/docs/references/nextjs/auth-object#has) helper to check if the user has verified their credentials within a specific time period. The `strict` configuration sets the time period to 10 minutes. If the user hasn't verified their credentials within 10 minutes, the `reverificationErrorResponse` utility is used to return an error. + +```tsx {{ filename: 'app/api/reverification-example/route.ts' }} +import { auth, reverificationErrorResponse } from '@clerk/nextjs/server' + +export const POST = async (req: Request) => { + const { has } = await auth() + + // Check if the user has *not* verified their credentials within the past 10 minutes. + const shouldUserRevalidate = !has({ reverification: 'strict' }) + + // If the user hasn't reverified, return an error with the matching configuration (e.g., `strict`) + if (shouldUserRevalidate) { + return reverificationErrorResponse('strict') + } + + // If the user has verified credentials, return a successful response + return new Response({ success: true }) +} +``` diff --git a/docs/_partials/token-size-callout.mdx b/docs/_partials/token-size-callout.mdx new file mode 100644 index 0000000000..5511b0eeaf --- /dev/null +++ b/docs/_partials/token-size-callout.mdx @@ -0,0 +1,4 @@ +> [!CAUTION] +> The entire session token has a max size of 4kb. Exceeding this size can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications. +> It's recommended to move particularly large claims out of the JWT and fetch these using a separate API call from your backend. +> [Learn more](/docs/backend-requests/resources/session-tokens#size-limitations). diff --git a/docs/advanced-usage/clerk-idp.mdx b/docs/advanced-usage/clerk-idp.mdx index 890cd78d43..0adb7e166a 100644 --- a/docs/advanced-usage/clerk-idp.mdx +++ b/docs/advanced-usage/clerk-idp.mdx @@ -10,7 +10,7 @@ Clerk can be configured as an identity provider to facilitate Single Sign-On (SS ## When should you use Clerk as an OAuth provider? -You can use Clerk as an OAuth provider if you want your users to sign in to a third party site or a tool using their credentials from your application. **This is not the same as supporting an OAuth provider, such as Google, in your application. If you want your users to be able to sign in to your application with an OAuth provider, see [the dedicated guide](/docs/authentication/social-connections/oauth#configuration).** +You can use Clerk as an OAuth provider if you want your users to sign in to a third party site or a tool using their credentials from your application. **This is not the same as supporting an OAuth provider, such as Google, in your application. If you want your users to be able to sign in to your application with an OAuth provider, see the [dedicated guide](/docs/authentication/social-connections/oauth#configuration).** ## How it works diff --git a/docs/advanced-usage/satellite-domains.mdx b/docs/advanced-usage/satellite-domains.mdx index d451505ce4..9a22e430bf 100644 --- a/docs/advanced-usage/satellite-domains.mdx +++ b/docs/advanced-usage/satellite-domains.mdx @@ -41,9 +41,8 @@ To access authentication state from a satellite domain, users will be transparen To add a satellite domain: - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=domains) - 1. In the navigation sidebar, select **Domains**. - 1. Select the **Satellite** tab. + 1. In the Clerk Dashboard, navigate to the [**Domains**](https://dashboard.clerk.com/last-active?path=domains) page. + 1. Select the **Satellites** tab. 1. Select the **Add satellite domain** button and follow the instructions provided. For the purposes of this guide: @@ -65,11 +64,11 @@ To access authentication state from a satellite domain, users will be transparen You can configure your satellite application by setting the following environment variables: > [!NOTE] - > In development, your publishable and secret keys will start with `pk_test_` and `sk_test` respectively. + > In development, your Publishable and Secret Keys will start with `pk_test_` and `sk_test` respectively. - In the `.env` file associated with your primary domain: - + ```env {{ filename: '.env.local' }} NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} CLERK_SECRET_KEY={{secret}} @@ -85,7 +84,7 @@ To access authentication state from a satellite domain, users will be transparen - In the `.env` file associated with your other (satellite) domain: - + ```env {{ filename: '.env.local' }} NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} CLERK_SECRET_KEY={{secret}} @@ -93,7 +92,7 @@ To access authentication state from a satellite domain, users will be transparen # Production example: NEXT_PUBLIC_CLERK_DOMAIN=satellite.dev NEXT_PUBLIC_CLERK_SIGN_IN_URL=https://primary.dev/sign-in - NEXT_PUBLIC_CLERK_SIGN_UP_URL=https://primary.dev/sign-up + NEXT_PUBLIC_CLERK_SIGN_UP_URL=https://primary.dev/sign-up # Development example: # NEXT_PUBLIC_CLERK_DOMAIN=http://localhost:3001 @@ -153,7 +152,7 @@ To access authentication state from a satellite domain, users will be transparen You can configure your satellite application by setting the following properties: - `isSatellite` - Defines the app as a satellite app when `true`. - - `domain` - Sets the domain of the satellite application. This is required since we cannot figure this out by your publishable key, since it is the same for all of your multi-domain apps. + - `domain` - Sets the domain of the satellite application. This is required since we cannot figure this out by your Publishable Key, since it is the same for all of your multi-domain apps. - `signInUrl` - This url will be used when signing in on your satellite application and needs to point to your primary application. This option is optional for production instances and required for development instances. - `signUpUrl` - This url will be used for signing up on your satellite application and needs to point to your primary application. This option is optional for production instances and required for development instances. - `allowedRedirectOrigins` - This is a list of origins that are allowed to redirect back to from the primary domain. @@ -161,7 +160,7 @@ To access authentication state from a satellite domain, users will be transparen > [!TIP] > The `URL` parameter that can be passed to `isSatellite` and `domain` is the request url for server-side usage or the current location for client usage. - + In a Next.js application, you must set the properties in the [``](/docs/components/clerk-provider) component _and_ in your [`clerkMiddleware()`](/docs/references/nextjs/clerk-middleware#clerk-middleware). @@ -407,4 +406,4 @@ To access authentication state from a satellite domain, users will be transparen You can repeat this process and create as many satellite applications as you need. -If you have any questions about satellite domains, or you're having any trouble setting this up, please contact [support@clerk.com](mailto:support@clerk.com) +If you have any questions about satellite domains, or you're having any trouble setting this up, contact [support@clerk.com](mailto:support@clerk.com) diff --git a/docs/advanced-usage/using-proxies.mdx b/docs/advanced-usage/using-proxies.mdx index 4e24707c2c..44af0b488b 100644 --- a/docs/advanced-usage/using-proxies.mdx +++ b/docs/advanced-usage/using-proxies.mdx @@ -20,7 +20,7 @@ When using a proxy, all requests to the Frontend API will be made through your d To get started, you need to create an application from the [Clerk Dashboard](https://dashboard.clerk.com/). Once you create an instance via the Clerk Dashboard, you will be prompted to choose a domain. For the purposes of this guide, the domain will be `app.dev`. > [!NOTE] - > For more information on creating a Clerk application, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). + > For more information on creating a Clerk application, see the [setup guide](/docs/quickstarts/setup-clerk). ### Configure your proxy server @@ -35,7 +35,7 @@ When using a proxy, all requests to the Frontend API will be made through your d Three additional headers must be set - `Clerk-Proxy-Url`: Needs to have the full proxy URL. - - `Clerk-Secret-Key`: The secret key for your Clerk instance. + - `Clerk-Secret-Key`: The Secret Key for your Clerk instance. - `X-Forwarded-For`: The IP address of the original client making the request. #### Example configuration @@ -146,7 +146,7 @@ When using a proxy, all requests to the Frontend API will be made through your d > [!NOTE] - > Every proxy configuration will be different and we're here to help. Please [reach out](/contact/support){{ target: '_blank' }} if there's a specific use-case you're looking to solve. + > Every proxy configuration will be different and we're here to help. [Contact support](/contact/support){{ target: '_blank' }} if there's a specific use-case you're looking to solve. ### Enable proxying @@ -158,9 +158,8 @@ When using a proxy, all requests to the Frontend API will be made through your d - 1. In the Clerk Dashboard, go to the **[Domains](https://dashboard.clerk.com/last-active?path=domains)** page. - 1. Navigate to the **Frontend API** section. - 1. Select the **Advanced** drop down. + 1. In the Clerk Dashboard, navigate to the **[Domains](https://dashboard.clerk.com/last-active?path=domains)** page. + 1. In the **Frontend API** section, select the **Advanced** dropdown. 1. In the **Proxy URL** field, enter your proxy URL. The proxy URL must be a valid URL and resolve correctly. @@ -187,7 +186,7 @@ When using a proxy, all requests to the Frontend API will be made through your d To configure your proxy setup using environment variables, your `.env.local` file should look like this: - + ```env {{ filename: '.env.local' }} NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} @@ -220,39 +219,23 @@ When using a proxy, all requests to the Frontend API will be made through your d #### Properties in your application - + To configure your proxy setup using properties in your Next.js application, set the `proxyUrl` property on the [``](/docs/components/clerk-provider) component. - - ```tsx {{ filename: 'app/layout.tsx', mark: [5] }} - import { ClerkProvider } from '@clerk/nextjs' - - export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - - {children} - - - ) - } - ``` - - ```tsx {{ filename: '_app.tsx', mark: [6] }} - import { ClerkProvider } from '@clerk/nextjs' - import type { AppProps } from 'next/app' + ```tsx {{ filename: 'app/layout.tsx', mark: [5] }} + import { ClerkProvider } from '@clerk/nextjs' - function MyApp({ Component, pageProps }: AppProps) { - return ( - - - - ) - } - export default MyApp - ``` - + export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + {children} + + + ) + } + ``` @@ -288,7 +271,7 @@ When using a proxy, all requests to the Frontend API will be made through your d ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' - // Initialize Clerk with your Clerk publishable key + // Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -305,4 +288,4 @@ When using a proxy, all requests to the Frontend API will be made through your d Your application should now be able to access the Frontend API from your proxy! -If you have any questions about proxying, or you're having any trouble setting this up, please contact [support@clerk.com](mailto:support@clerk.com). +If you have any questions about proxying, or you're having any trouble setting this up, contact [support@clerk.com](mailto:support@clerk.com). diff --git a/docs/authentication/configuration/email-sms-templates.mdx b/docs/authentication/configuration/email-sms-templates.mdx index 5ce93cefb0..c54a4178dc 100644 --- a/docs/authentication/configuration/email-sms-templates.mdx +++ b/docs/authentication/configuration/email-sms-templates.mdx @@ -23,7 +23,7 @@ It will be useful to take a look at the following terms as they will reappear in ### Revolvapp WYSIWYG email editor plugin -The email editor uses the [Revolvapp](https://imperavi.com/redactor/legacy/revolvapp) email template editor plugin by Imperavi. To acquaint yourself with the template markup syntax, please consult the corresponding [documentation page](https://imperavi.com/redactor/legacy/revolvapp/docs/syntax/quick-start). +The email editor uses the [Revolvapp](https://imperavi.com/redactor/legacy/revolvapp) email template editor plugin by Imperavi. To acquaint yourself with the template markup syntax, consult [Imperavi's docs](https://imperavi.com/redactor/legacy/revolvapp/docs/syntax/quick-start). As you will see, the template markup is an HTML-like language and each type of node supports its own set of attributes which control its behavior. A lot of the attributes are borrowed from HTML itself. @@ -42,8 +42,7 @@ When editing a template in the Clerk Dashboard, you can insert variables at the To access the email templates: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=customization/email). -1. In the navigation sidebar, select **Customization > Emails**. +1. In the Clerk Dashboard, navigate to the [**Emails**](https://dashboard.clerk.com/last-active?path=customization/email) page. 1. Select a template to edit. 1. Once you have selected a template, you will be presented with [template operations](#template-operations), the [template settings](#email-template-settings), and [the WYSIWYG editor](#email-wysiwyg-editor). @@ -60,7 +59,7 @@ The following operations are available for an email template: The following settings can be changed per email template: -- **Delivered by Clerk**: Clerk will deliver your emails using its own Email Service Provider (ESP), which is currently [SendGrid](https://sendgrid.com/). However, if you wish to handle delivery of emails on your own, then you can toggle this setting off. This means that Clerk will no longer be sending this particular email and in order to deliver it yourself, you will need to listen to the `emails.created` [webhook](/docs/integrations/webhooks/overview) and extract the necessary info from the event payload. +- **Delivered by Clerk**: Clerk will deliver your emails using its own Email Service Provider (ESP), which is currently [SendGrid](https://sendgrid.com/). However, if you wish to handle delivery of emails on your own, then you can toggle this setting off. This means that Clerk will no longer be sending this particular email and in order to deliver it yourself, you will need to listen to the `emails.created` [webhook](/docs/webhooks/overview) and extract the necessary info from the event payload. - **Name**: a name for the template on the template listing page. It does not affect the outgoing email in any way. - **From**: the email address that will be used as the **From** address in the email header. The format is `@`. You can change the local part to a custom value. If no value is provided, it defaults `noreply`. - **Reply-To**: the email address that will be used as the **Reply-To** address in the email header. This is useful if you want to direct replies to a different email address than the one used in the **From** field. The format is `@`. You can change the local part to a custom value. If no value is provided, the **Reply-To** header will be omitted. @@ -104,8 +103,7 @@ The email WYSIWYG editor text area is intended mainly for authoring content. Tho To access the SMS templates: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=customization/sms). -1. In the navigation sidebar, select **Customization > SMS**. +1. In the Clerk Dashboard, navigate to the [**SMS**](https://dashboard.clerk.com/last-active?path=customization/sms) page. 1. Select a template to edit. You can also disable certain SMS notifications. 1. A modal will appear that shows you what the template looks like, plus options to toggle the [**Delivered by Clerk**](#delivered-by-clerk) setting or to [request a change to the template](#request-change). @@ -113,7 +111,7 @@ To access the SMS templates: Clerk will deliver your SMS messages using its own SMS Gateway. However, if you wish to handle SMS delivery on your own, then you can toggle **Delivered by Clerk** off. -This means that Clerk will no longer be sending this particular SMS and in order to deliver it yourself, you will need to listen to the `sms.created` [webhook](/docs/integrations/webhooks/overview) and extract the necessary info from the event payload. +This means that Clerk will no longer be sending this particular SMS and in order to deliver it yourself, you will need to listen to the `sms.created` [webhook](/docs/webhooks/overview) and extract the necessary info from the event payload. > [!NOTE] > Remember, this is a per-template setting and will not be applied to other templates. diff --git a/docs/authentication/configuration/restrictions.mdx b/docs/authentication/configuration/restrictions.mdx index 8035fb197e..a5746c538b 100644 --- a/docs/authentication/configuration/restrictions.mdx +++ b/docs/authentication/configuration/restrictions.mdx @@ -11,11 +11,11 @@ Clerk supports multiple sign-up modes, giving you flexibility in managing user a To configure sign-up modes: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions). -1. In the top navigation, select **Configure**. Then in the sidebar, select **Restrictions**. +1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page. 1. Under the **Sign-up modes** section, you can enable one of the following options: - **[Public](#public)** - **[Restricted](#restricted)** + - **[Waitlist](#waitlist)** ### Public @@ -31,6 +31,33 @@ Additional features available in **Restricted** mode: - The [``](/docs/components/authentication/sign-up) is accessible only to users who have been invited and have a valid invitation link. Users who don't have access will see a message indicating that they need an invitation to sign up. +### Waitlist + +![\ component](/docs/images/ui-components/waitlist.svg) + +> [!NOTE] +> If you're using Next.js, the`` component is available in `@clerk/nextjs@6.2.0` and above. + +In **Waitlist** mode, users can register their interest in your app by joining a waitlist. This mode is ideal for apps in early development stages or those wanting to generate interest before launch. + +Additional features available in **Waitlist** mode: + +- The [``](/docs/components/authentication/sign-in) component will only be accessible to users who have been approved from the waitlist. + +- The [``](/docs/components/authentication/sign-up) is accessible only to users who have been invited and have a valid invitation link. Users who don't have access will see a message indicating that they need an invitation to sign up. + +- The [``](/docs/components/waitlist) component provides a form where users can submit their details to join the waitlist. Once approved by admins, users will receive an email with access instructions. + +- If you're using the `` component, you must provide the `waitlistUrl` prop either in the [``](/docs/components/clerk-provider#properties) or [``](/docs/components/authentication/sign-in#properties) component to ensure proper functionality. + +#### Manage waitlist entries + +To manage a user on your waitlist: + +1. In the Clerk Dashboard, navigate to the [**Waitlist**](https://dashboard.clerk.com/last-active?path=waitlist) page. +1. On the right-side of the user's row, select the menu icon (...). +1. Select **Invite** to invite the user to your application. Select **Deny** to deny the user access to your application. + ## Allowlist > [!NOTE] @@ -42,8 +69,7 @@ After creating an account, users cannot change their identifier to bypass the al To enable this feature: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions). -1. In the top navigation, select **Configure**. Then in the sidebar, select **Restrictions**. +1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page. 1. In the **Allowlist** section, toggle on **Enable allowlist**. > [!CAUTION] @@ -58,8 +84,7 @@ By adding specific identifiers to the blocklist, users with those identifiers wi To enable this feature: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions). -1. In the top navigation, select **Configure**. Then in the sidebar, select **Restrictions**. +1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page. 1. In the **Blocklist** section, toggle on **Enable blocklist**. > [!WARNING] @@ -80,8 +105,7 @@ For example, if you add `john.doe@clerk.dev` as a blocked email address, it mean To enable this feature: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions). -1. In the top navigation, select **Configure**. Then in the sidebar, select **Restrictions**. +1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page. 1. In the **Restrictions** section, toggle on **Block email subaddresses**. ### Block sign-ups that use disposable email addresses @@ -90,6 +114,5 @@ To enable this feature: To enable this feature: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions). -1. In the top navigation, select **Configure**. Then in the sidebar, select **Restrictions**. +1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page. 1. In the **Restrictions** section, toggle on **Block sign-ups that use disposable email addresses**. diff --git a/docs/authentication/configuration/session-options.mdx b/docs/authentication/configuration/session-options.mdx index f488ac610e..65644e5cb4 100644 --- a/docs/authentication/configuration/session-options.mdx +++ b/docs/authentication/configuration/session-options.mdx @@ -24,8 +24,7 @@ A user is considered inactive when the application is closed, or when the app st By default, the inactivity timeout is set to 7 days. You can set a custom inactivity timeout by following these steps: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=sessions) and select your application. -1. In the navigation sidebar, select **Sessions**. +1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page. 1. Toggle on **Inactivity timeout**. 1. Set your desired duration. @@ -38,8 +37,7 @@ The duration after which a session will expire and the user will have to sign in By default, this setting is enabled with a default value of 7 days for all newly created instances. To find this setting and change the value: -1. Navigate to the the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=sessions) and select your application. -1. In the navigation sidebar, select **Sessions**. +1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page. 1. Toggle on **Maximum lifetime**. 1. Set your desired duration. @@ -66,10 +64,9 @@ A multi-session application is an application that allows multiple accounts to b To enable multi-session in your application, you need to configure it in the Clerk Dashboard. -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=sessions) and select your application. -1. In the navigation sidebar, select **Sessions**. +1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page. 1. Toggle on **Multi-session handling**. -1. Select **Save changes**. +1. Select **Save**. There are two main ways to add the multi-session feature to your application: @@ -80,4 +77,4 @@ There are two main ways to add the multi-session feature to your application: Session tokens are JWTs that contain a set of [default claims](/docs/backend-requests/resources/session-tokens) required by Clerk. You can customize these tokens by providing additional claims of your own. -To learn how to customize session tokens, check out our [Customize your session token](/docs/backend-requests/making/custom-session-token) guide. +To learn how to customize session tokens, see the [dedicated guide](/docs/backend-requests/making/custom-session-token). diff --git a/docs/authentication/configuration/sign-up-sign-in-options.mdx b/docs/authentication/configuration/sign-up-sign-in-options.mdx index 733ff2a0c3..6e4865727a 100644 --- a/docs/authentication/configuration/sign-up-sign-in-options.mdx +++ b/docs/authentication/configuration/sign-up-sign-in-options.mdx @@ -5,7 +5,7 @@ description: Clerk provides various options for configuring a sign-up and sign-i Clerk provides multiple options for configuring a sign-up and sign-in flow for your application, such as [identifiers](#identifiers) and [authentication strategies](#authentication-strategies). This guide will walk you through each option. -You can modify your authentication options after your application has been created by navigating to the [Clerk Dashboard](https://dashboard.clerk.com/) and selecting the **User & Authentication** dropdown in the navigation sidebar. +You can modify your authentication options after your application has been created by navigating to the [Clerk Dashboard](https://dashboard.clerk.com/) and selecting any of the options under **User & Authentication**. ## Identifiers @@ -31,8 +31,7 @@ Choosing **username** as the identifier enables users to sign up without requiri To update your identifiers after your application has been created: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) and select your application. -1. In the navigation sidebar, select **User & Authentication > Email, Phone, Username**. +1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. In the **Contact information** section, you can select **Email address** and **Phone number** as identifiers. In the **Username** section, you can select **Username** as an identifier. ## Authentication strategies @@ -56,8 +55,7 @@ The **passwordless** strategy provides a more secure and convenient sign-in meth To configure authentication strategies: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) and select your application. -1. In the navigation sidebar, select **User & Authentication > Email, Phone, Username**. +1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. In the **Authentication strategies** section, toggle on the authentication strategies you would like to enable. ### Passkeys @@ -112,8 +110,7 @@ SMS functionality, including SMS OTPs, is restricted to phone numbers from count Every instance starts off with a default set of enabled SMS country tiers. To tailor it to your needs: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=customization/sms). -1. In the navigation sidebar, select **Customization > SMS**. +1. In the Clerk Dashboard, navigate to the [**SMS**](https://dashboard.clerk.com/last-active?path=customization/sms) page. 1. Select the **Settings** tab. 1. Enable or disable countries as needed. @@ -142,8 +139,7 @@ These methods work similarly to their authentication strategy counterparts but a To configure verification methods: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) and select your application. -1. In the navigation sidebar, select **User & Authentication > Email, Phone, Username**. +1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. Select the settings icon next to the identifier, such as **Email address** or **Phone number**, to open the configuration settings. 1. Under the **Verification methods** section, toggle on the verification methods you would like to enable. 1. Select **Continue** to save your changes. @@ -160,8 +156,7 @@ Users can link multiple social providers to their account, depending on your app To enable social connections: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO connections**. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For all users**. 1. For development instances, simply select the social providers that you would like to enable. For production instances, you'll need to configure credentials for each social provider. See [the social provider's dedicated guide](/docs/authentication/social-connections/overview) to learn how to configure credentials. @@ -171,8 +166,7 @@ Clerk provides [Web3 authentication](/docs/users/web3) with either MetaMask or C To enable Web3 authentication: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/web3) and select your application. -1. In the navigation sidebar, select **User & Authentication > Web3**. +1. In the Clerk Dashboard, navigate to the [**Web3**](https://dashboard.clerk.com/last-active?path=user-authentication/web3) page. 1. Toggle on the Web3 provider. Currently, Clerk supports MetaMask and Coinbase Wallet. ## Multi-factor authentication @@ -181,8 +175,7 @@ Clerk supports multi-factor authentication (MFA), also known as two-factor authe MFA is not available on the new application screen, but it can be enabled in the Clerk Dashboard. -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor) and select your application. -1. In the navigation sidebar, select **User & Authentication > Multi-factor**. +1. In the Clerk Dashboard, navigate to the [**Multi-factor**](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor) page. 1. Toggle on the MFA strategies you would like to enable. The following MFA strategies are currently available: @@ -201,11 +194,10 @@ You can reset a user's MFA by deleting their MFA enrollments. This will remove a To reset a user's MFA: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor). -1. In the top navigation, select **Users**. +1. At the top of the [Clerk Dashboard](https://dashboard.clerk.com/), select **Users**. 1. Select the user from the list. 1. Select the **Reset MFA enrollments** button. ## Restrictions -Clerk provides a set of restriction options designed to provide you with enhanced control over who can gain access to your application. Restrictions can limit sign-ups or prevent accounts with specific identifiers, such as email addresses, phone numbers, and even entire domains, from accessing your application. [Learn more about restrictions.](/docs/authentication/configuration/restrictions) +Clerk provides a set of restriction options designed to provide you with enhanced control over who can gain access to your application. Restrictions can limit sign-ups or prevent accounts with specific identifiers, such as email addresses, phone numbers, and even entire domains, from accessing your application. [Learn more about restrictions](/docs/authentication/configuration/restrictions). diff --git a/docs/authentication/enterprise-connections/account-linking.mdx b/docs/authentication/enterprise-connections/account-linking.mdx new file mode 100644 index 0000000000..06e062cdea --- /dev/null +++ b/docs/authentication/enterprise-connections/account-linking.mdx @@ -0,0 +1,33 @@ +--- +title: Account linking +description: Learn how Clerk handles account linking during Enterprise SSO. +--- + +Account linking is the process of connecting multiple user accounts from different services or platforms, allowing users to access various services with a single set of credentials. It enables seamless sign-in using Enterprise SSO alongside other authentication methods like username/password. Clerk automatically attempts to link accounts that share the same email address, assuming a single owner for each email. + +## How it works + +When a user attempts to sign in or up, Clerk checks if the email address from the Identity Provider (IdP) matches an existing account and attempts to link them. Email addresses from IdPs are considered verified by default. + +The following sections explain the different scenarios that can occur during this process and how Clerk handles each one. + +![Flow chart of the SAML SSO account linking process in various scenarios.](/docs/images/authentication/account-linking-flow-saml.webp) + +### Email is verified in Clerk + +When a user signs into your app using an IdP that returns a matching verified email address, Clerk automatically links the Enterprise SSO account to the existing account and completes the sign-in process. This includes accounts protected by passwords, as the Enterprise SSO sign-in flow automatically bypasses password verification. + +### Email is not verified and verification isn't required + +By default, Clerk requires email verification at sign-up. For instances that have disabled this behavior, there's a possibility that an account may be created using an unverified email address. + +To configure email verification at sign-up: + +1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. +1. Next to **Email address**, select the settings icon and disable the **Verify at sign-up** toggle. + +When a user signs into your app using an IdP, Clerk automatically links the Enterprise SSO account to the existing account by **also verifying the existing email address** and signing the user in. This includes accounts protected by passwords, as the Enterprise SSO sign-in flow automatically bypasses password verification. + +### Email is not verified + +When a user signs into your app using an IdP that returns a matching unverified email address, Clerk doesn't link the Enterprise SSO account to the existing account, but instead signs the user up and creates a completely new account. diff --git a/docs/authentication/enterprise-connections/authentication-flows.mdx b/docs/authentication/enterprise-connections/authentication-flows.mdx new file mode 100644 index 0000000000..cda6ab5ae4 --- /dev/null +++ b/docs/authentication/enterprise-connections/authentication-flows.mdx @@ -0,0 +1,58 @@ +--- +title: Enterprise SSO authentication flows +description: Learn about the Enterprise SSO authentication flows. +--- + +There are two types of Enterprise SSO connections: [EASIE](#easie) and [SAML](#saml). + +## EASIE + +EASIE connections support the authentication flows described at [easie.dev](https://easie.dev). + +## SAML + +The SAML protocol supports two methods to start an SSO flow: [Service Provider-initiated (SP-initiated)](#service-provider-initiated-flow-recommended) and [Identity Provider-initiated (IdP-initiated)](#identity-provider-initiated-flow). + +For the best security practices, it's recommended to use the SP-initiated flow wherever possible. If you decide to enable IdP-initiated flows, ensure that proper [security measures](#clerks-security-measures), such as MFA and short validation periods, are in place to mitigate the associated risks. + +### Service Provider-initiated flow (recommended) + +In an SP-initiated flow: + +- The user starts the authentication process from your application (Service Provider, or SP), by providing their email address. +- The user is redirected to the SAML provider (Identity Provider, or IdP) where they must authenticate. +- After successful authentication, the user is redirected back to your app, gaining access to their account. + +### Identity Provider-initiated flow + +In an IdP-initiated flow: + +- The user starts the authentication flow from the SAML provider (IdP) by selecting which app (SP) they want to access. +- The user is redirected to the app of their choice, gaining access to their account. + +> [!NOTE] +> IdP-Initiated flow carries a [security risk](#risks-of-id-p-initiated-flow). It is recommended to use an SP-Initiated flow whenever possible. + +To allow IdP-initiated flows for your SAML connection: + +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. Select **Add connection** and select **For specific domains**. +1. Select your **Identity Provider**. Complete the fields and select **Add connection**. You'll be redirected to the SAML connection's configuration page. +1. Select the **Advanced** tab. +1. In **Advanced Settings**, enable **Allow IdP-Initiated flow**. A modal will open. Select **Enable** to confirm. +1. Select **Save**. + +#### Risks of IdP-initiated flow + +While IdP-initiated flows might offer convenience, they are also susceptible to security risks, such as [meddler-in-the-middle (MITM) attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). A bad actor might hijack the IdP response to gain access to a compromised account. + +When enabling an IdP-initiated flow, it's possible for Clerk to receive unsolicited authentication requests, which neither the SP nor IdP can verify were initiated by the specified user. Additionally, a bad actor could intercept the IdP response and replace it, performing a CSRF attack to sign in as the attacker. + +#### Clerk's security measures + +To mitigate the risks associated with IdP-initiated flows, Clerk implements several security measures: + +- **Unsolicited `InResponseTo` attribute**: Clerk ensures that unsolicited responses don't contain an `InResponseTo` attribute, in accordance with the [SAML 2.0 profiles specification](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf). This prevents bad actors from stealing a response used in an SP-initiated flow and using it in an IdP-initiated flow. +- **Replay detection**: Clerk consumes and remembers each response to prevent re-use. This ensures that bad actors cannot steal and reuse a response to gain access to a user's account. +- **Multi-factor authentication**: Clerk supports [multi-factor authentication (MFA)](/docs/authentication/configuration/sign-up-sign-in-options#multi-factor-authentication) for SAML IdP-initiated flows. MFA requires users to provide two or more forms of verification, which significantly enhances security by reducing the risk of unauthorized access. +- **Use small validation periods**: Each SAML response contains a timestamp indicating when it was issued and when it will expire. Since IdP-initiated flows are expected to be completed within seconds, validation periods must be as small as possible to prevent attacks. Common IdP providers such as Azure, Google, and Okta handle this by default. However, if you're using a custom IdP, you must ensure that the validation periods are set correctly. diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx new file mode 100644 index 0000000000..4e8ed5048f --- /dev/null +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -0,0 +1,75 @@ +--- +title: Add Google as an EASIE connection +description: Learn how to allow users to sign up and sign in to your Clerk app with their Google account using EASIE SSO. +--- + + + - Use Google to authenticate users with EASIE SSO. + + +Enabling EASIE SSO with Google allows your users to sign up and sign in to your Clerk application with their Google account. + +## Configure for your development instance + +For _development instances_, Clerk uses preconfigured shared credentials and redirect URIs—no other configuration is needed. + +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. Select **Add connection** and select **For specific domains**. +1. Under **EASIE**, select **Google** as the identity provider. +1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. +1. Select **Add connection**. + +## Configure for your production instance + +> [!WARNING] +> If you already [configured Google as a social provider](/docs/authentication/social-connections/google), you can skip this step. EASIE SSO will automatically use the credentials you configured for your social connection. + +For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Google Developer account. + +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). + + + ### Enable Google as an EASIE connection + + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. Select **Add connection** and select **For specific domains**. + 1. Below EASIE, select **Google** as the identity provider. + 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application. + 1. Ensure that **Use custom credentials** is toggled on. + 1. Save the **Redirect URI** somewhere secure. Keep this page open. + + ### Create a Google Developer project + + 1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/). + 1. Select a project or [create a new one](https://console.cloud.google.com/projectcreate). + 1. If the **APIs & Services** page isn't already open, open the menu on the left and select **APIs & Services**. + 1. In the menu on the left, select **Credentials**. + 1. Select **Create Credentials**. Then, select **OAuth client ID.** You may need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849?hl=en#userconsent\&zippy=%2Cuser-consent). + 1. Select the appropriate application type for your project. Most likely, you will choose **Web application**. + 1. In the **Authorized redirect URIs** setting, paste the **Redirect URI** value you saved from the Clerk Dashboard. + 1. Select **Create**. + + ### Set the Client ID and Client Secret in the Clerk Dashboard + + Once the OAuth client is created in the Google Cloud Console, a modal will open with your **Client ID** and **Client Secret**. Save these values somewhere secure. + + Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. Note that if you have any other Google EASIE connections or a [Google social connection](docs/authentication/social-connections/google), this will update the credentials for all of them. Select **Add connection**. + diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx new file mode 100644 index 0000000000..026abb0cf8 --- /dev/null +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -0,0 +1,123 @@ +--- +title: Add Microsoft as an EASIE connection +description: Learn how to allow users to sign up and sign in to your Clerk app with their Microsoft account using EASIE SSO. +--- + + + - Use Microsoft to authenticate users with EASIE SSO. + + +Enabling EASIE SSO with Microsoft (formerly [Active Directory](https://learn.microsoft.com/en-us/entra/fundamentals/new-name)) allows your users to sign up and sign in to your Clerk application with their Microsoft account. + +## Configure for your development instance + +For _development instances_, Clerk uses preconfigured shared credentials and redirect URIs—no other configuration is needed. + +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. Select the **Add connection** button, and select **For specific domains**. +1. Under **EASIE**, select **Microsoft** as the identity provider. +1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. +1. Select **Add connection**. + +## Configure for your production instance + +> [!WARNING] +> If you already [configured Microsoft as a social provider](/docs/authentication/social-connections/microsoft), you can skip this step. EASIE SSO will automatically use the credentials you configured for your social connection. + +For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Microsoft Entra ID account. + +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com). + + + ### Enable Microsoft as an EASIE connection + + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. Select **Add connection** and select **For specific domains**. + 1. Under **EASIE**, select **Microsoft** as the identity provider. + 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. + 1. Ensure that **Use custom credentials** is toggled on. + 1. Save the **Redirect URI** somewhere secure. Keep this page open. + + ### Create a Microsoft Entra ID app + + > [!TIP] + > If you already have a Microsoft Entra ID app you'd like to connect to Clerk, select your app from the [Microsoft Azure portal](https://portal.azure.com/#home) and skip to [the next step in this tutorial](#get-your-client-id-and-client-secret). + + 1. On the homepage of the [Microsoft Azure portal](https://portal.azure.com/#home), in the **Azure services** section, select **[Microsoft Entra ID](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)**. + 1. In the sidebar, open the **Manage** dropdown and select **[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)**. + 1. Select **New Registration**. You'll be redirected to the **Register an application** page. + 1. Complete the form as follows: + 1. Under **Name**, enter your app name. + 1. Under **Supported account types**, select **Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)**. + 1. Under **Redirect URI (Optional)**, select **Web**. + 1. Select **Register** to submit the form. + + ### Secure your app against the nOAuth vulnerability + + [nOAuth](https://www.descope.com/blog/post/noauth) is an exploit in Microsoft Entra ID OAuth apps that can lead to account takeovers via email address spoofing. Clerk mitigates this risk by enforcing stricter checks on verified email addresses. + + For further security, Microsoft offers an optional `xms_edov` claim, which provides additional context to determine whether the returned email is verified. + + This claim is mandatory for applications backing EASIE connections. To enable it, you must: + + 1. In the Microsoft Azure portal, navigate to your app. + 1. In the sidebar, select **Token configuration**. + 1. Select **Add optional claim**. + 1. For the **Token type**, select **ID**. Then, in the table that opens, enable the `email` and `xms_pdl` claims. + 1. At the bottom of the modal, select **Add**. A new modal will prompt you to turn on the Microsoft Graph email permission. Enable it, then select **Add** to complete the form. + > [!NOTE] + > At the time of writing, the `xms_edov` claim is still in preview and may not be available for all apps. We'll choose another claim and rename it in the manifest later. + 1. Repeat the previous steps for **Token type**, but select **Access** instead of **ID**. The **Optional claims** list should now show two claims for `email` and two for `xms_pdl`: one each for **ID** and **Access**. + 1. In the sidebar, go to **Manifest**. + 1. In the text editor, search for `"acceptMappedClaims"` and set its value from `null` to `true`. + 1. Search for `"optionalClaims"`, where you'll find the `idToken` and `accessToken` arrays. Each array has an object with the name `xms_pdl`. Change the name to `xms_edov`. + 1. At the top of the page, select **Save**. + 1. In the sidebar, navigate back to **Token configuration** and confirm that the **Optional claims** list includes two claims for `email` and two for `xms_edov`: one each for **ID** and **Access**. + + With these steps complete, Microsoft will send the `xms_edov` claim in the token, which Clerk will use to determine whether the email is verified, even when used with Microsoft Entra ID. + + ### Get your client ID and client secret + + Once your Microsoft Entra ID app is created, or once you select your app from the Microsoft Azure portal, you'll be redirected to its **Overview**. + + 1. From your app's overview, save the **Application (client) ID** somewhere secure. You'll need it to connect your Microsoft Entra ID app to your Clerk app. + 1. Under **Client credentials**, select **Add a certificate or secret** to generate a **Client Secret**. You'll be redirected to the **Certificate & secrets** page. + 1. Select **New client secret**. In the modal that opens, enter a description and set an expiration time for your secret. + > [!IMPORTANT] + > When your secret expires, your social connection will stop working until you generate a new client secret and add it to your Clerk app. + 1. Save the new client secret's **Value** somewhere secure. You'll add this and your client ID to your Clerk app later. Keep this page open. + + ### Set the Client ID and Client Secret in the Clerk Dashboard + + Go back to the Clerk Dashboard, where the modal should still be open, and paste the **Client ID** and **Client Secret** values into the respective fields. Note that if you have any other Microsoft EASIE connections or a [Microsoft social connection](docs/authentication/social-connections/microsoft), this will update the credentials for all of them. Select **Add connection**. + + ### Enable OpenID + + To connect your Clerk app to your Microsoft app, set the **Redirect URI** in your Microsoft Azure portal. + + 1. Navigate back to the Microsoft Azure portal. + 1. In the sidebar, open the **Manage** dropdown and select **Authentication**. + 1. Select **Add a platform**. + 1. Select **Web**. + 1. In the **Redirect URIs** field and the **Front-channel logout URL** field, paste the **Redirect URI** you copied from the Clerk Dashboard. + 1. Under **Implicit grant and hybrid flows**, check both **Access tokens** and **ID tokens**. + 1. Select **Configure** to save the changes. + diff --git a/docs/authentication/saml/jit-provisioning.mdx b/docs/authentication/enterprise-connections/jit-provisioning.mdx similarity index 83% rename from docs/authentication/saml/jit-provisioning.mdx rename to docs/authentication/enterprise-connections/jit-provisioning.mdx index 51e41eb0e0..0e0e71fc49 100644 --- a/docs/authentication/saml/jit-provisioning.mdx +++ b/docs/authentication/enterprise-connections/jit-provisioning.mdx @@ -7,7 +7,7 @@ Just-in-Time (JIT) Provisioning, or automatic account provisioning, is a process Using JIT Provisioning means your IT department won't have to manually create user accounts for each of the services or apps your employees use to get work done. -Clerk supports JIT account provisioning for all [supported SAML providers](/docs/authentication/saml/overview). +Clerk supports JIT account provisioning for all [supported SAML providers](/docs/authentication/enterprise-connections/overview). Check your preferred SAML provider's documentation to enable JIT account provisioning on their side. @@ -17,8 +17,7 @@ During SAML SSO and after a user has successfully authenticated, the IdP provide To disable this behavior: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the SAML connection you want to disable the sync for. 1. Select the **Advanced** tab. 1. Toggle off the **Sync user attributes during Sign in** option. diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx new file mode 100644 index 0000000000..a46326a5ab --- /dev/null +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -0,0 +1,80 @@ +--- +title: Enterprise SSO +description: Clerk provides Enterprise SSO to authenticate users via federated Identity Providers such such as Azure AD, Okta, Google Workspace and more. +--- + +With Enterprise SSO, users can sign in seamlessly using their Identity Provider's (IdP) credentials and have their user data synchronized with Clerk. You can learn more about the process in the guides on [authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [account linking](/docs/authentication/enterprise-connections/account-linking). + +## SAML + +Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an IdP. The following IdPs are supported: [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta). However, you can also [integrate with any other IdP](/docs/authentication/enterprise-connections/saml/custom-provider) that supports the SAML protocol. + +### Allow subdomains + +Authenticating via SAML SSO requires the user's email address domain to match the exact domain the SAML connection has been configured with. By default, subdomains are not supported. For example, a user with the email address `john@sales.example.com` wouldn't be able to use a SAML connection with the `example.com` domain to authenticate. + +To configure subdomains for a SAML connection: + +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. Select the SAML connection you want to allow subdomains for. +1. Select the **Advanced** tab. +1. Enable or disable the **Allow subdomains** option. +1. Select **Save**. + +> [!NOTE] +> To enable the **Allow subdomains** option, your SAML connection domain must be an [eTLD+1](https://developer.mozilla.org/en-US/docs/Glossary/eTLD). + +## EASIE + +[EASIE](https://easie.dev) SSO is a way for applications to provide enterprise-grade SSO through a multi-tenant OpenID provider. It is designed to be an easier alternative to SAML SSO. + +The following IdPs are supported: Google Workspace and Microsoft Entra ID. For _development instances_, Clerk uses preconfigured shared credentials and redirect URIs—no other configuration is needed. For _production instances_, you must provide custom credentials. Follow the steps outlined in the guides to complete the setup: + +- [Google](docs/authentication/social-connections/google) +- [Microsoft](docs/authentication/social-connections/azure) + +### Automatic deprovisioning + +Clerk prevents users linked to deprovisioned accounts in the OpenID provider from accessing the app. + +Within 10 minutes of a user being removed from the OpenID provider (e.g. [suspendeded](https://support.google.com/a/answer/33312?hl=en) or [deleted](https://support.google.com/a/answer/33314?hl=en) via Google Workspace, or [deleted](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-create-delete-users#delete-a-user) via Microsoft Entra), Clerk will recognize that the user has been deprovisioned and will revoke that user's existing sessions. + +It is ultimately the app's responsibility to handle this unauthenticated state and display something appropriate to the user. For example, Next.js apps using [`auth.protect()`](docs/references/nextjs/auth#auth-protect) will automatically redirect the user to the sign-in page. + +## SAML vs. EASIE + +The primary security difference between EASIE SSO and SAML SSO is that EASIE depends on a multi-tenant identity provider, while SAML depends on a single-tenant identity provider. Relying on a multi-tenant provider **increases** the risk that a user from one tenant will mistakenly be granted access to the resources of another tenant. While Clerk implements [measures to address this risk](https://easie.dev/#mitigating-tenant-crossover-vulnerabilities), apps that require single-tenant IdPs should opt for SAML. + +For more information, see the [EASIE docs](https://easie.dev#security). + +## Frequently asked questions (FAQ) + +### I've enabled other strategies but they don't work + +A Clerk app can have multiple authentication strategies, but a domain that enables Enterprise SSO can't. Once Enterprise SSO is enabled for a domain, there can be no other authentication methods for that specific domain. This is in line with an organization's intent to manage their users' identity from one place. This allows your Clerk app to enable Enterprise SSO connections for certain domains while others use non-Enterprise SSO methods depending on each organization's needs. + +### Will Enterprise SSO work for my existing users? + +Yes, Enterprise SSO will work for your existing users as well! If you enable SAML or EASIE, any existing users with an email address that matches the SAML or EASIE connection domain will have to authenticate on the IdP side and an Enterprise account will be linked to their existing account. + +### What happens if I have multi-factor enabled at Clerk? + +Once the user returns from the IdP, they will need to complete additional authentication factors. This is useful if you want to add extra factors beyond what your IdP supports or if your IdP doesn’t support them. This feature is optional and can be disabled if not needed. + +### What happens if I delete the Enterprise Connection? Will my users be deleted? + +The users will not be deleted, so your app will not break. However, they will need to use another [strategy](/docs/authentication/configuration/sign-up-sign-in-options#authentication-strategies) such as password or email to authenticate themselves moving forward. + +### Does Clerk support IdP-initiated SSO? + +Yes, for SAML only. Clerk supports both Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated) SSO flows. For more information, see the [authentication flows guide](/docs/authentication/enterprise-connections/authentication-flows). + +### How much does it cost? + +For development instances, Enterprise connections are always free but limited to a maximum of 25. + +Production instances require the Pro plan and the Enhanced Authentication Add-on. Please see [pricing](/pricing){{ target: '_blank' }} for more information. + +### Can I get a bulk discount? + +Yes, [contact support](/contact/support){{ target: '_blank' }} to work out a custom plan. diff --git a/docs/authentication/saml/azure.mdx b/docs/authentication/enterprise-connections/saml/azure.mdx similarity index 86% rename from docs/authentication/saml/azure.mdx rename to docs/authentication/enterprise-connections/saml/azure.mdx index d2228ef9ec..87a7039fc4 100644 --- a/docs/authentication/saml/azure.mdx +++ b/docs/authentication/enterprise-connections/saml/azure.mdx @@ -22,16 +22,16 @@ description: Learn how to allow users to sign up and sign in to your Clerk app w Enabling single sign-on (SSO) with **Microsoft Azure Entra ID** (formerly [Active Directory](https://learn.microsoft.com/en-us/entra/fundamentals/new-name)) allows your users to sign up and sign in to your Clerk application with their Microsoft account. -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com). +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com). ### Set up an enterprise connection in Clerk To create a SAML connection in Clerk: - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For specific domains**. - 1. In the modal that opens, select **Microsoft Entra ID (Formerly AD)** as the identity provider. + 1. Under **SAML**, select **Microsoft Entra ID (Formerly AD)** as the identity provider. 1. Add the **Name** of the connection. This is the name that will be displayed on the sign-in form. 1. Enter the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. 1. Select **Add connection**. You'll be redirected to the connection's configuration page. @@ -116,17 +116,6 @@ To make the setup process easier, it's recommended to keep two browser tabs open To make the connection available for your users to authenticate with: - 1. Navigate back to the Clerk Dashboard where you should still have the connection's configuration page open. If not, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. + 1. Navigate back to the Clerk Dashboard where you should still have the connection's configuration page open. If not, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. 1. At the top of the page, toggle on **Enable connection** and select **Save**. - - ### Test your OAuth - - The simplest way to test your OAuth is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box. - - 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. - 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: - - - **For development** – `https://your-domain.accounts.dev/sign-in` - - **For production** – `https://accounts.your-domain.com/sign-in` - 1. Sign in with your Microsoft account. diff --git a/docs/authentication/saml/custom-provider.mdx b/docs/authentication/enterprise-connections/saml/custom-provider.mdx similarity index 77% rename from docs/authentication/saml/custom-provider.mdx rename to docs/authentication/enterprise-connections/saml/custom-provider.mdx index cc64295782..b717cfa88e 100644 --- a/docs/authentication/saml/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/saml/custom-provider.mdx @@ -20,7 +20,7 @@ description: Learn how to integrate an Identity Provider with Clerk using SAML S - Use a custom IdP to enable single sign-on (SSO) via SAML for your Clerk application. -Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). Currently, Clerk offers direct integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/saml/google), and [Okta Workforce](/docs/authentication/saml/okta) as IdPs. However, you can also integrate with any other IdP that supports the SAML protocol. This guide will show you how to set up a SAML connection with a custom IdP in Clerk. +Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). Currently, Clerk offers direct integrations with [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also integrate with any other IdP that supports the SAML protocol. This guide will show you how to set up a SAML connection with a custom IdP in Clerk. ## Tutorial @@ -29,17 +29,16 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth To create a SAML connection in Clerk: - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. - 1. Select the **Add connection** button, and select **For specific domains**. - 1. Select **Custom SAML Provider**. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. Select **Add connection** and select **For specific domains**. + 1. Under **SAML**, select **Custom SAML Provider**. 1. Add the **Name** of the connection. This is the name that will be displayed in the sign-in form. 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application. 1. Select **Add connection**. You will be redirected to the connection's configuration page. ### Create a new enterprise application in your IdP - Create a new application in your IdP. In the next steps, you will configure your IdP with the settings provided by your Service Provider (Clerk), and you will configure Clerk with the settings provided by your IdP. So, you will need to keep both the IdP and Clerk dashboards open. + Create a new application in your IdP. In the next steps, you'll configure your IdP with the settings provided by your Service Provider (Clerk), and configure Clerk with the settings provided by your IdP. Keep both the IdP and Clerk Dashboard open. ### Configure your Identity Provider @@ -81,7 +80,7 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth 1. In your IdP dashboard, paste the values in the appropriate fields. > [!TIP] - > If you closed your connection's configuration page in the Clerk Dashboard, you can find it by navigating to the [SSO Connections](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and selecting the settings icon next to the connection you want to configure. + > If you closed the connection's configuration page in the Clerk Dashboard, you can find it by navigating to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and selecting the settings icon next to the connection you want to configure. ### Map your IdP's claims to Clerk fields @@ -101,18 +100,12 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth For example, say you were using Google as your IdP. Google users have the "Phone number" attribute. Clerk does not have a direct mapping for this attribute, as you can see in the Clerk Dashboard in the **Attribute mapping** section. Instead, in the Google dashboard, you would map Google's "Phone number" claim to `public_metadata_phone_number`. Then, in Clerk, the value for the user's phone number would be saved in the user's `User.publicMetadata` under the key `phone_number`. - [Learn more about how to access the metadata from our APIs.](/docs/users/metadata) + Learn more about [how to access the metadata from our APIs](/docs/users/metadata). - ### Activate your SAML connection - - Now that you have configured your SAML connection, you can activate it. + ### Enable the connection for Clerk To make the connection available for your users to authenticate with: - 1. In the Clerk Dashboard, you should still have the connection's configuration page open. If not, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. + 1. In the Clerk Dashboard, you should still have the connection's configuration page open. If not, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. 1. Toggle on **Enable connection** and select **Save**. - - ### Test your SAML connection - - Everything should be set up now for you to test authentication via SAML. Go to your Clerk application's sign-in page and add your email address in the input field. If it matches an active SAML connection, you will be redirected to your IdP where you will sign in with your credentials. diff --git a/docs/authentication/saml/google.mdx b/docs/authentication/enterprise-connections/saml/google.mdx similarity index 91% rename from docs/authentication/saml/google.mdx rename to docs/authentication/enterprise-connections/saml/google.mdx index 87357f6bbd..010d286a92 100644 --- a/docs/authentication/saml/google.mdx +++ b/docs/authentication/enterprise-connections/saml/google.mdx @@ -27,13 +27,12 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. To create a SAML connection in Clerk: - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. - 1. Select the **Add connection** button, and select **For specific domains**. - 1. Select **Google Workspace** as the identity provider. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. Select **Add connection** and select **For specific domains**. + 1. Under **SAML**, select **Google Workspace** as the identity provider. 1. Add the **Name** of the connection. This is the name that will be displayed in the sign-in form. 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application. - 1. Select **Add connection**. You will be redirected to the connection's configuration page. + 1. Select **Add connection**. You'll be redirected to the connection's configuration page. ### Create a new enterprise application in Google @@ -120,7 +119,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. The value for the user's phone number will be saved in the user's `User.publicMetadata` under the key `phone_number`. - [Learn more about how to access the metadata from our APIs.](/docs/users/metadata) + Learn more about [how to access the metadata from our APIs](/docs/users/metadata). ### Enable the connection on Google @@ -134,6 +133,6 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. To make the connection available for your users to authenticate with: - 1. In the Clerk Dashboard, you should still have the connection's configuration page open. If not, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. + 1. In the Clerk Dashboard, you should still have the connection's configuration page open. If not, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. 1. Toggle on **Enable connection** and select **Save**. diff --git a/docs/authentication/saml/okta.mdx b/docs/authentication/enterprise-connections/saml/okta.mdx similarity index 92% rename from docs/authentication/saml/okta.mdx rename to docs/authentication/enterprise-connections/saml/okta.mdx index d05ebe395b..f530a92eae 100644 --- a/docs/authentication/saml/okta.mdx +++ b/docs/authentication/enterprise-connections/saml/okta.mdx @@ -27,10 +27,9 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. To create a SAML connection in Clerk: - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. - 1. Select the **Add connection** button, and select **For specific domains**. - 1. Select **Okta Workforce** as the identity provider. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. Select **Add connection** and select **For specific domains**. + 1. Under **SAML**, select **Okta Workforce** as the identity provider. 1. Add the **Name** of the connection. This is the name that will be displayed in the sign-in form. 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application. 1. Select **Add connection**. You will be redirected to the connection's configuration page. @@ -108,6 +107,6 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. To make the connection available for your users to authenticate with: - 1. In the Clerk Dashboard, you should still have the connection's configuration page open. If not, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. + 1. In the Clerk Dashboard, you should still have the connection's configuration page open. If not, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. 1. Toggle on **Enable connection** and select **Save**. diff --git a/docs/authentication/overview.mdx b/docs/authentication/overview.mdx index ce6700cf48..751d726583 100644 --- a/docs/authentication/overview.mdx +++ b/docs/authentication/overview.mdx @@ -9,4 +9,4 @@ Clerk supports multiple authentication strategies so that you can implement the Clerk's configuration settings affect how the users of your application can [sign up and sign in](/docs/authentication/configuration/sign-up-sign-in-options) and which properties are editable via their user profile. You can also manage [user sessions](/docs/authentication/configuration/session-options), [control who gets access](/docs/authentication/configuration/restrictions) to your application, and [customize the email & SMS messages](/docs/authentication/configuration/email-sms-templates) that are sent by Clerk during authentication flows. All of these settings can be found under the **User & Authentication** section in the [Clerk Dashboard](https://dashboard.clerk.com/). -Check out our detailed guide for information on [how to set up your application](/docs/quickstarts/setup-clerk). +For more information on how to set up your application, see the [setup guide](/docs/quickstarts/setup-clerk). diff --git a/docs/authentication/saml/account-linking.mdx b/docs/authentication/saml/account-linking.mdx deleted file mode 100644 index 69bbce1b04..0000000000 --- a/docs/authentication/saml/account-linking.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Account Linking -description: Learn how Clerk handles account linking during SAML SSO. ---- - -Account Linking is a process that Clerk uses to ensure a smooth sign-in and sign-up experience using SAML SSO and other methods (e.g. username/password). By using the email address as the common identifier, Clerk automatically attempts to link accounts whenever possible. Account linking triggers when a SAML provider returns an email address that matches an existing account, assuming a single owner for each email address. - -## How it works - -When a user attempts to sign in or sign up, Clerk first checks the provided email address. Clerk will attempt to link the SAML account with any existing Clerk account that shares the same email address. - -In the following sections, we'll look at the different scenarios that can occur during this process and explain how Clerk handles each one. - -> [!NOTE] -> Email addresses from SAML providers are considered verified by default. - -![Flow chart of the SAML SSO account linking process in various scenarios.](/docs/images/authentication/account-linking-flow-saml.webp) - -### Email is verified in Clerk - -When a user signs into your app using a SAML provider that returns a matching verified email address, Clerk links the SAML account to the existing account and signs the user in. This even applies to password-protected accounts, as the SAML sign-in process automatically bypasses password verification. - -### Email is unverified and verification isn't required - -For instances that allow account creation without email verification at sign-up, there is a possibility that an account may be created using an unverified email address. - -To allow unverified email addresses for your instance: - -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) -1. In the navigation sidebar, select **Email, Phone, Username**. -1. Next to **Email address**, select the settings icon and uncheck the **Verify at sign-up** toggle. - -When a user signs into your app using a SAML provider, Clerk links the SAML account to the existing account by also verifying the existing email address and signs the user in. This even applies to password-protected accounts, as the SAML sign-in process automatically bypasses password verification. - -### Email is unverified - -When a user signs into your app using a SAML provider that returns a matching unverified email address, Clerk doesn't link the SAML account to the existing account, but instead signs the user up and creates a completely new account. diff --git a/docs/authentication/saml/authentication-flows.mdx b/docs/authentication/saml/authentication-flows.mdx deleted file mode 100644 index 78a6d58927..0000000000 --- a/docs/authentication/saml/authentication-flows.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: SAML SSO authentication flows -description: Learn about the SAML SSO authentication flows. ---- - -The SAML protocol supports two methods to start an SSO flow: Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated). - -## Service Provider-initiated flow (recommended) - -In an SP-initiated flow: - -- The user starts the authentication process from your application (Service Provider, or SP), by providing their email address. -- The user is redirected to the SAML provider (Identity Provider, or IdP) where they must authenticate. -- After successful authentication, the user is redirected back to your application, gaining access to their account. - -## Identity Provider-initiated flow - -In an IdP-initiated flow: - -- The user starts the authentication flow from the SAML provider (IdP) by selecting which application (SP) they want to access. -- The user is redirected to the application of their choice, gaining access to their account. - -> [!NOTE] -> IdP-Initiated flow carries a [security risk](#risks-of-id-p-initiated-flow). It is recommended to use an SP-Initiated flow whenever possible. - -To allow IdP-initiated flows for your SAML connection: - -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. -1. Select **Add connection** and select **For specific domains**. -1. Select your **Identity Provider**. Complete the fields and select **Add connection**. You'll be redirected to the SAML connection's configuration page. -1. Select the **Advanced** tab. -1. In **Advanced Settings**, enable **Allow IdP-Initiated flow**. A modal will open. Select **Enable** to confirm. -1. Select **Save**. - -### Risks of IdP-initiated flow - -While IdP-initiated flows might offer convenience, they are also susceptible to security risks, such as [meddler-in-the-middle (MITM) attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). A bad actor might hijack the IdP response to gain access to a compromised account. - -When enabling an IdP-initiated flow, it is possible for Clerk to receive unsolicited authentication requests, which neither the SP nor IdP can verify were initiated by the specified user. Additionally, a bad actor could intercept the IdP response and replace it, performing a CSRF attack to sign in as the attacker. - -### Clerk's security measures - -To mitigate the risks associated with IdP-initiated flows, Clerk implements several security measures: - -#### Unsolicited `InResponseTo` attribute - -Clerk ensures that unsolicited responses don't contain an `InResponseTo` attribute, in accordance with the [SAML 2.0 profiles specification](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf). This prevents bad actors from stealing a response used in an SP-initiated flow and using it in an IdP-initiated flow. - -#### Replay detection - -Clerk consumes and remembers each response to prevent re-use. This ensures that bad actors cannot steal and reuse a response to gain access to a user's account. - -#### Multi-factor authentication - -Clerk supports [multi-factor authentication (MFA)](/docs/authentication/configuration/sign-up-sign-in-options#multi-factor-authentication) for SAML IdP-initiated flows. MFA requires users to provide two or more forms of verification, which significantly enhances security by reducing the risk of unauthorized access. - -#### Use small validation periods - -Each SAML response contains a timestamp indicating when it was issued and when it will expire. Since IdP-initiated flows are expected to be completed within seconds, validation periods must be as small as possible to prevent attacks. Common IdP providers such as Azure, Google, and Okta handle this by default. However, if you are using a custom IdP, you must ensure that the validation periods are set correctly. - -### Conclusion - -For the best security practices, Clerk recommends using the SP-initiated flow wherever possible. If you decide to enable IdP-initiated flows, ensure that proper security measures—such as MFA, replay detection, and short validation periods—are in place to mitigate the associated risks. diff --git a/docs/authentication/saml/overview.mdx b/docs/authentication/saml/overview.mdx deleted file mode 100644 index 84d9ab5ead..0000000000 --- a/docs/authentication/saml/overview.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Enterprise SSO via SAML -description: Clerk supports Enterprise SSO via the SAML protocol so that you can create authentication strategies for Identity Providers, such as Okta. ---- - -Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [SAML SSO authentication flows](/docs/authentication/saml/authentication-flows) and [Account linking](/docs/authentication/saml/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. Currently, Clerk offers direct integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/saml/google), and [Okta Workforce](/docs/authentication/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/saml/custom-provider) that supports the SAML protocol. - -## Allow subdomains - -Authenticating via SAML SSO requires the user's email address domain to match the exact domain the SAML connection has been configured with. By default, subdomains are not supported. For example, a user with the email address `john@sales.example.com` would not be able to use a SAML connection with the `example.com` domain in order to authenticate. - -To support SAML SSO with subdomains, - -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. -1. Select the SAML connection you want to allow subdomains for. -1. Select the **Advanced** tab. -1. Toggle on the **Allow subdomains** option. - -> [!NOTE] -> To enable the **Allow subdomains** option, your SAML connection domain must be an eTLD+1. - -## Frequently asked questions (FAQ) - -### I've enabled other strategies but they don't work - -A Clerk application can have multiple authentication strategies, but a domain that enables Enterprise SSO can not. Once Enterprise SSO is enabled for a domain, there can be no other authentication methods for that specific domain. This is in line with an organization's intent to manage their users' identity from one place. This will allow your Clerk application to enable Enterprise SSO connections for certain domains while others use non-Enterprise SSO methods depending on each organization's needs. - -### Will SAML work for my existing users? - -Yes, SAML will work for your existing users as well! If you enable SAML, any existing users with an email address that matches the SAML Connection domain will have to authenticate on the IdP side and an Enterprise Account will be linked to their existing account. - -### What happens if I have multi-factor enabled at Clerk? - -This will work: Once the user comes back from the IdP, they will need to go through the extra factors of authentication. This is in case you need to add extra factors on top of what your IdP supports (or in case they don't). You can choose to not enable this feature if you wish. - -### What happens if I delete the SAML connection? Will my users be deleted? - -The users will not be deleted, so your application will not break. However, they will need to use another [strategy](/docs/authentication/configuration/sign-up-sign-in-options#authentication-strategies) such as password, email OTP, etc., to authenticate themselves moving forward. - -### Does Clerk support IdP-initiated SSO? - -Yes, Clerk supports both Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated) SSO flows. [Learn more](/docs/authentication/saml/authentication-flows). - -### How much does it cost? - -For production instances, each active connection costs $50 per month. SAML connections require the Pro plan and the Enhanced Authentication Add-on. Please see [pricing](/pricing){{ target: '_blank' }} for those costs, and the costs of other add-ons or features. - -For development instances, SAML connections will always be free, but capped to 5. - -### Can I get a bulk discount? - -Yes, [reach out to support](/contact/support){{ target: '_blank' }} to work out a custom plan. diff --git a/docs/authentication/social-connections/account-linking.mdx b/docs/authentication/social-connections/account-linking.mdx index d618b8d6b3..7242124da4 100644 --- a/docs/authentication/social-connections/account-linking.mdx +++ b/docs/authentication/social-connections/account-linking.mdx @@ -25,7 +25,7 @@ In this scenario, when a user with a verified email address at Clerk signs in us For instances that allow account creation without email verification at sign-up, there is a possibility that an account may be created using an unverified email address, either through OAuth or other methods like username/password. -To allow unverified email addresses for your instance, navigate to the [Email, Phone, Username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page in the Clerk Dashboard. Click on the settings icon next to "Email address" and uncheck the "Verify at sign-up" toggle. +To allow unverified email addresses for your instance, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page in the Clerk Dashboard. Click on the settings icon next to "Email address" and uncheck the "Verify at sign-up" toggle. ![Verify at sign-up toggle in the Clerk Dashboard](/docs/images/authentication/account-linking-verify-at-sign-up.webp) diff --git a/docs/authentication/social-connections/apple.mdx b/docs/authentication/social-connections/apple.mdx index e7f69e4475..da76b6f2d9 100644 --- a/docs/authentication/social-connections/apple.mdx +++ b/docs/authentication/social-connections/apple.mdx @@ -28,8 +28,7 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a To configure your development instance, follow these steps: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For all users**. 1. In the **Choose provider** dropdown, select **Apple**. 1. Then, @@ -49,10 +48,9 @@ To configure your production instance, follow these steps: ### Enable Apple as a social connection - To get started, you must enable Apple as a social connection in your Clerk Dashboard. + To get started, you must enable Apple as a social connection in the Clerk Dashboard. - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For all users**. 1. In the **Choose provider** dropdown, select **Apple**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. @@ -163,7 +161,7 @@ To configure your production instance, follow these steps: Connect your Apple app to your Clerk app by adding these values to the Clerk Dashboard. - 1. Navigate back to the tab where your Clerk Dashboard and your Apple configuration modal is open. + 1. Navigate back to the tab where the Clerk Dashboard and your Apple configuration modal is open. 1. Add all the corresponding fields depending on your desired flow. For the **Apple Private Key** file, open it with a text editor and just copy/paste the contents. 1. Select **Add connection**. @@ -171,7 +169,7 @@ To configure your production instance, follow these steps: The simplest way to test your OAuth is to visit your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk applications out-of-the-box. - 1. In the top navigation of the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=account-portal), select **Configure.** Then in the sidebar, select **Account Portal** + 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: - **For development** – `https://your-domain.accounts.dev/sign-in` - **For production** – `https://accounts.your-domain.com/sign-in` diff --git a/docs/authentication/social-connections/atlassian.mdx b/docs/authentication/social-connections/atlassian.mdx index 4817c83d1f..c145d1b1ad 100644 --- a/docs/authentication/social-connections/atlassian.mdx +++ b/docs/authentication/social-connections/atlassian.mdx @@ -18,7 +18,7 @@ For production instances, you will need to generate your own Client ID and Clien ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a Atlassian developer account. To create one, [click here](https://developer.atlassian.com/). ## Configuring an Atlassian OAuth 2.0 Integration diff --git a/docs/authentication/social-connections/bitbucket.mdx b/docs/authentication/social-connections/bitbucket.mdx index 5b364d165e..4f9425d4d6 100644 --- a/docs/authentication/social-connections/bitbucket.mdx +++ b/docs/authentication/social-connections/bitbucket.mdx @@ -18,7 +18,7 @@ For production instances, you will need to generate your own Consumer Key and Co ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a Bitbucket account. To create one, [click here](https://bitbucket.org/account/signup). ## Configuring Bitbucket social connection diff --git a/docs/authentication/social-connections/box.mdx b/docs/authentication/social-connections/box.mdx index c5d0893370..e9daba389a 100644 --- a/docs/authentication/social-connections/box.mdx +++ b/docs/authentication/social-connections/box.mdx @@ -18,7 +18,7 @@ For production instances, you will need to generate your own Client ID and Clien ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a Box developer account. To create one, [click here](https://developer.box.com/). ## Configuring Box social connection @@ -29,8 +29,8 @@ You need to choose an app name and then click **Create application**. ![Adding a name and creating the application](/docs/images/authentication-providers/box/adding-name-and-creating-application.jpg) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Box**. Toggle on **Use custom credentials** and copy **Redirect URIs**. +In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Box**. Toggle on **Use custom credentials** and copy **Redirect URIs**. Copy the **Client ID** and **Client secret** as shown in the above image. Go back to the Clerk Dashboard and paste them into the respective fields. -Don't forget to click **Apply** in the Clerk dashboard. Congratulations! Social connection with Box is now configured for your instance. +Don't forget to click **Apply** in the Clerk Dashboard. Congratulations! Social connection with Box is now configured for your instance. diff --git a/docs/authentication/social-connections/coinbase.mdx b/docs/authentication/social-connections/coinbase.mdx index 49db7c2bae..923735e4b7 100644 --- a/docs/authentication/social-connections/coinbase.mdx +++ b/docs/authentication/social-connections/coinbase.mdx @@ -26,7 +26,7 @@ Enabling OAuth with [Coinbase](https://docs.cdp.coinbase.com/coinbase-app/docs/c For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Coinbase**. 1. Select **Add connection**. @@ -35,12 +35,12 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your Coinbase account. -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Coinbase's Developer Platform](https://portal.cdp.coinbase.com). +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Coinbase's Developer Platform](https://portal.cdp.coinbase.com). ### Enable Coinbase as a social connection in Clerk - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Coinbase**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. @@ -51,18 +51,18 @@ To make the setup process easier, it's recommended to keep two browser tabs open > [!NOTE] > Coinbase automatically creates a default project for you named `Project 1`. Select the icon next to the project name to rename it. - 1. In your [Coinbase Developer Platform project dashboard](https://portal.cdp.coinbase.com/projects), navigate to the **API Keys** tab. + 1. In your [Coinbase Developer Platform project dashboard](https://portal.cdp.coinbase.com/projects), navigate to the **API keys** tab. 1. Select **OAuth**, then select **Create client**. 1. Complete the required fields. In **Redirect URIs**, paste the **Redirect URI** you saved from the Clerk Dashboard. 1. Select **Create client**. The page will refresh and you should see the **Client ID** and **Client Secret** in the **OAuth** section. Save both values somewhere secure. - ### Set the Client ID and Client Secret in your Clerk Dashboard + ### Set the Client ID and Client Secret in the Clerk Dashboard - 1. Navigate back to your Clerk Dashboard where the modal should still be open. Paste the **Client ID** and **Client Secret** values that you saved into the respective fields. + 1. Navigate back to the Clerk Dashboard where the modal should still be open. Paste the **Client ID** and **Client Secret** values that you saved into the respective fields. 1. Select **Add connection**. > [!NOTE] - > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Coinbase** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Coinbase** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth diff --git a/docs/authentication/social-connections/custom-provider.mdx b/docs/authentication/social-connections/custom-provider.mdx index 188cfcb5cb..b032a407e3 100644 --- a/docs/authentication/social-connections/custom-provider.mdx +++ b/docs/authentication/social-connections/custom-provider.mdx @@ -24,8 +24,7 @@ Clerk allows you to configure custom OpenID Connect (OIDC) compatible authentica ## Configuration -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For all users**. 1. At the top of the modal that opened, select **Custom provider**. 1. Fill in the following fields: diff --git a/docs/authentication/social-connections/discord.mdx b/docs/authentication/social-connections/discord.mdx index f7eb5d2366..2532860c1a 100644 --- a/docs/authentication/social-connections/discord.mdx +++ b/docs/authentication/social-connections/discord.mdx @@ -26,7 +26,7 @@ Enabling OAuth with [Discord](https://discord.com/developers/docs/topics/oauth2) For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Discord**. 1. Select **Add connection**. @@ -35,12 +35,12 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Discord account. -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Discord Developers Portal](https://discord.com/developers/applications). +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Discord Developers Portal](https://discord.com/developers/applications). ### Enable Discord as a social connection in Clerk - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Discord**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. @@ -55,14 +55,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Under **Redirects**, select **Add Redirect**. Paste the **Redirect URI** you saved from the Clerk Dashboard. 1. Select **Save Changes**. You may need to tap anywhere on the screen for the button to show. Keep this page open. - ### Set the Client ID and Client Secret in your Clerk Dashboard + ### Set the Client ID and Client Secret in the Clerk Dashboard 1. In your Discord Developers Portal, copy the **Client ID** and **Client Secret**. If you don't see the **Copy** button under the **Client Secret**, select **Reset Secret** to generate a new one. - 1. Navigate back to your Clerk Dashboard where the modal should still be open and paste these values into the respective fields. + 1. Navigate back to the Clerk Dashboard where the modal should still be open and paste these values into the respective fields. 1. Select **Add connection**. > [!NOTE] - > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Discord** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Discord** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth diff --git a/docs/authentication/social-connections/dropbox.mdx b/docs/authentication/social-connections/dropbox.mdx index 1de4dd325f..415e5a6183 100644 --- a/docs/authentication/social-connections/dropbox.mdx +++ b/docs/authentication/social-connections/dropbox.mdx @@ -18,7 +18,7 @@ For production instances, you will need to generate your own Client ID and Clien ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a Dropbox account. To create one, [click here](https://www.dropbox.com/lp/developers). ## Configuring Dropbox social connection @@ -29,7 +29,7 @@ First, you need to register a new OAuth Dropbox app at the [Dropbox App Console] First you need to choose the API type, the App's type of access and to set a name for your new application. You also need to add the **OAuth Redirect URLs.** -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Dropbox**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **OAuth Redirect URIs** input and click create. +In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Dropbox**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **OAuth Redirect URIs** input and click create. Once all the above are complete, copy the **Client ID** and **Client Secret.** Go back to the Clerk Dashboard and paste them into the respective fields. diff --git a/docs/authentication/social-connections/facebook.mdx b/docs/authentication/social-connections/facebook.mdx index ee49fd4692..e763e85bfb 100644 --- a/docs/authentication/social-connections/facebook.mdx +++ b/docs/authentication/social-connections/facebook.mdx @@ -18,7 +18,7 @@ For production instances, you will need to create your own developer account wit ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a Facebook Developer account. To create one, consult the [Register as a Facebook developer](https://developers.facebook.com/docs/development/register) page. ## Configuring Facebook social connection @@ -35,7 +35,7 @@ Once you have a OAuth client ID created, click on the newly created ID under **O ![Retrieving the App ID and App Secret](/docs/images/authentication-providers/facebook/33456604106d3478e0fd6b583bdde7c4f5563641-1467x969.png) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Facebook**. Toggle on **Use custom credentials** and paste the values you obtained during the previous step. +In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Facebook**. Toggle on **Use custom credentials** and paste the values you obtained during the previous step. ![Adding the valid OAuth Redirect URI](/docs/images/authentication-providers/facebook/c0be80ce8fed2b4d14d04fcbf56318b80295093d-1467x989.png) diff --git a/docs/authentication/social-connections/github.mdx b/docs/authentication/social-connections/github.mdx index 05144f92f3..cc5025f0de 100644 --- a/docs/authentication/social-connections/github.mdx +++ b/docs/authentication/social-connections/github.mdx @@ -27,7 +27,7 @@ Enabling OAuth with [GitHub](https://docs.github.com/en/developers/apps/building For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and choose **For all users**. 1. In the **Choose provider** dropdown, select **GitHub**. 1. Select **Add connection**. @@ -36,12 +36,12 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your GitHub account. -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [GitHub Developers](https://GitHub.com/developers/applications) page. +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [GitHub Developers](https://GitHub.com/developers/applications) page. ### Enable GitHub as a social connection in Clerk - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and choose **For all users**. 1. In the **Choose provider** dropdown, select **GitHub**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. @@ -55,14 +55,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In **Authorization callback URL**, paste the **Redirect URI** you saved from the Clerk Dashboard. 1. Select **Register application**. You'll be redirected to your GitHub app's **General** page. - ### Set the Client ID and Client Secret in your Clerk Dashboard + ### Set the Client ID and Client Secret in the Clerk Dashboard 1. In the GitHub app's **General** page, select **Generate a new client secret**. Save your **Client ID** and **Client secret** somewhere secure. - 1. Navigate back to your Clerk Dashboard where the modal should still be open and paste these values into the respective fields. + 1. Navigate back to the Clerk Dashboard where the modal should still be open and paste these values into the respective fields. 1. Select **Add connection**. > [!NOTE] - > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the GitHub connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the GitHub connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth diff --git a/docs/authentication/social-connections/gitlab.mdx b/docs/authentication/social-connections/gitlab.mdx index fbc32a433a..e4e146d8f6 100644 --- a/docs/authentication/social-connections/gitlab.mdx +++ b/docs/authentication/social-connections/gitlab.mdx @@ -26,7 +26,7 @@ Enabling OAuth with [GitLab](https://docs.gitlab.com/ee/integration/oauth_provid For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **GitLab**. 1. Select **Add connection**. @@ -35,12 +35,12 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your GitLab account. -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [GitLab](https://gitlab.com) account. +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [GitLab](https://gitlab.com) account. ### Enable GitLab as a social connection in Clerk - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **GitLab**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. @@ -55,13 +55,13 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select the **Scopes** needed for your app. To allow users to sign up and sign in with GitLab, you must at least select `read_user`. 1. Select **Save application**. You'll be redirected to your app's settings page. Save the **Application ID** and **Secret** somewhere secure. - ### Set the Client ID and Client Secret in your Clerk Dashboard + ### Set the Client ID and Client Secret in the Clerk Dashboard - 1. Navigate back to your Clerk Dashboard where the modal should still be open. Paste the **Application ID** and **Secret** values in the **Client ID** and **Client Secret** fields, respectively. + 1. Navigate back to the Clerk Dashboard where the modal should still be open. Paste the **Application ID** and **Secret** values in the **Client ID** and **Client Secret** fields, respectively. 1. Select **Add connection**. > [!NOTE] - > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **GitLab** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **GitLab** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth diff --git a/docs/authentication/social-connections/google.mdx b/docs/authentication/social-connections/google.mdx index cf3aac7cd3..cbf7aa5755 100644 --- a/docs/authentication/social-connections/google.mdx +++ b/docs/authentication/social-connections/google.mdx @@ -29,7 +29,7 @@ Enabling OAuth with Google allows your users to sign up and sign in to your Cler For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Google**. 1. Select **Add connection**. @@ -38,12 +38,12 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Google Developer account. -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). ### Enable Google as a social connection - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Google**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. @@ -60,14 +60,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In the **Authorized Redirect URIs** setting, paste the **Redirect URI** value you saved from the Clerk Dashboard. 1. Select **Create**. Keep this page open. - ### Set the Client ID and Client Secret in your Clerk Dashboard + ### Set the Client ID and Client Secret in the Clerk Dashboard Once the OAuth client is created in the Google Cloud Console, a modal will open with your **Client ID** and **Client Secret**. Save these values somewhere secure. Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. Then, select **Add connection**. > [!NOTE] - > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Google** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Google** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth @@ -101,7 +101,7 @@ For a Google organization with the domain `example.com`, blocking email subaddre To configure this setting: -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Google** connection. 1. Enable or disable **Block email subaddresses**. diff --git a/docs/authentication/social-connections/hubspot.mdx b/docs/authentication/social-connections/hubspot.mdx index dc810ef48c..ac325a68e7 100644 --- a/docs/authentication/social-connections/hubspot.mdx +++ b/docs/authentication/social-connections/hubspot.mdx @@ -18,7 +18,7 @@ For production instances, you will need to create your own developer account wit ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a HubSpot Developer account. To create one, [click here](https://app.hubspot.com/signup/developers/step/existing-user?_ga=2.145169076.1430980384.1628431607-741498900.1628431607). ## Configuring HubSpot social connection @@ -29,7 +29,7 @@ Once your app is created, click on the **Auth** tab and copy the **App Id** and ![Configuring a HubSpot app](/docs/images/authentication-providers/hubspot/02d8bf249b4a6debe85e66ea53b5f88817acdba0-1489x995.png) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **HubSpot**. Toggle on **Use custom credentials** and paste the values you obtained during the previous step. +In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **HubSpot**. Toggle on **Use custom credentials** and paste the values you obtained during the previous step. Before you close the modal, copy the **Redirect URI**. Go back to the HubSpot panel and paste it into the **Redirect URL** field and click **Save**. diff --git a/docs/authentication/social-connections/huggingface.mdx b/docs/authentication/social-connections/huggingface.mdx index 95a4202f4e..cf3e43e156 100644 --- a/docs/authentication/social-connections/huggingface.mdx +++ b/docs/authentication/social-connections/huggingface.mdx @@ -28,8 +28,7 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a To configure your development instance, follow these steps: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For all users**. 1. In the **Choose provider** dropdown, select **Hugging Face**. 1. Select **Add connection**. @@ -57,8 +56,7 @@ To configure your production instance, follow these steps: ### Get your Redirect URI from Clerk - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For all users**. 1. In the **Choose provider** dropdown, select **Hugging Face**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. Then, copy the **Redirect URI**. @@ -76,7 +74,7 @@ To configure your production instance, follow these steps: The simplest way to test your OAuth is to visit your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk applications out-of-the-box. - 1. In the navigation sidebar of the Clerk Dashboard, select [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal). + 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: - For development – [https://your-domain.accounts.dev/sign-in](https://your-domain.accounts.dev/sign-in) - For production – [https://accounts.your-domain.com/sign-in](https://accounts.your-domain.com/sign-in) diff --git a/docs/authentication/social-connections/line.mdx b/docs/authentication/social-connections/line.mdx index 515e099771..94231003fe 100644 --- a/docs/authentication/social-connections/line.mdx +++ b/docs/authentication/social-connections/line.mdx @@ -21,7 +21,7 @@ For production instances, you will need to generate your own Client ID and Clien ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a LINE developer account. To create one, [click here](https://developers.line.biz/en/). ## Configuring LINE social connection @@ -34,7 +34,7 @@ The next step is to create a new **LINE Login channel**. You will have to select In the next screen, after the app has been created, you will find the **Basic settings** of the application. If you want to also make email address available for your application, you will have to apply for **Email address permission** in the bottom of your app's **Basic settings**. -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **LINE**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **LINE login → Callback URL** input. +In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **LINE**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **LINE login → Callback URL** input. Once all the above are complete, copy the **Channel ID** and **Channel secret.** Go back to the Clerk Dashboard and paste them into the respective fields. diff --git a/docs/authentication/social-connections/linear.mdx b/docs/authentication/social-connections/linear.mdx index 85aed78cbf..2f61452f76 100644 --- a/docs/authentication/social-connections/linear.mdx +++ b/docs/authentication/social-connections/linear.mdx @@ -29,7 +29,7 @@ Enabling OAuth with [Linear](https://developers.linear.app/docs/oauth/authentica For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Linear**. 1. Select **Add connection**. @@ -38,12 +38,12 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your Linear account. -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Linear's API settings](https://linear.app/clerk/settings/api) page. +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Linear's API settings](https://linear.app/clerk/settings/api) page. ### Enable Linear as a social connection in Clerk - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Linear**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. @@ -56,13 +56,13 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Complete the required fields. In **Callback URLs**, paste the **Redirect URI** you saved from the Clerk Dashboard. 1. Select **Save**. The page will refresh and you should see the **Client ID** and **Client Secret** at the top. Save both values somewhere secure. - ### Set the Client ID and Client Secret in your Clerk Dashboard + ### Set the Client ID and Client Secret in the Clerk Dashboard - 1. Navigate back to your Clerk Dashboard where the modal should still be open. Paste the **Client ID** and **Client Secret** values that you saved into the respective fields. + 1. Navigate back to the Clerk Dashboard where the modal should still be open. Paste the **Client ID** and **Client Secret** values that you saved into the respective fields. 1. Select **Add connection**. > [!NOTE] - > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Linear** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Linear** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth diff --git a/docs/authentication/social-connections/linkedin-oidc.mdx b/docs/authentication/social-connections/linkedin-oidc.mdx index eeb2aee1c0..bd36d75b05 100644 --- a/docs/authentication/social-connections/linkedin-oidc.mdx +++ b/docs/authentication/social-connections/linkedin-oidc.mdx @@ -26,8 +26,7 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a To configure your development instance, follow these steps: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For all users**. 1. In the **Choose provider** dropdown, select **LinkedIn**. 1. Select **Add connection**. @@ -62,8 +61,7 @@ To configure your production instance, follow these steps: ### Connect your LinkedIn app and get your redirect URI - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For all users**. 1. In the **Choose provider** dropdown, select **LinkedIn**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. Then: @@ -90,7 +88,7 @@ To configure your production instance, follow these steps: The simplest way to test your OAuth is to visit your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk applications out-of-the-box. - 1. In the navigation sidebar of the Clerk Dashboard, select [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal). + 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: - For development – [https://your-domain.accounts.dev/sign-in](https://your-domain.accounts.dev/sign-in) - For production – [https://accounts.your-domain.com/sign-in](https://accounts.your-domain.com/sign-in) diff --git a/docs/authentication/social-connections/linkedin.mdx b/docs/authentication/social-connections/linkedin.mdx index c9d0a20c17..41645cba86 100644 --- a/docs/authentication/social-connections/linkedin.mdx +++ b/docs/authentication/social-connections/linkedin.mdx @@ -19,7 +19,7 @@ For production instances, you will need to generate your own Client ID and Clien ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a LinkedIn account. To create one, [click here](https://developer.linkedin.com/). ## Configuring LinkedIn social connection @@ -30,7 +30,7 @@ First, you need to create a new OAuth LinkedIn app. You need to set a name, associate a LinkedIn page with it, and upload a logo for your new application. -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **LinkedIn**. +In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **LinkedIn**. Toggle on **Use custom credentials** and copy **Authorized Redirect URI**. Paste the value into the **Redirect URL** of your LinkedIn app, as shown below. diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 0b0ed582e7..a76ccb904b 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -27,7 +27,7 @@ Enabling OAuth with Microsoft Azure Entra ID (formerly [Active Directory](https: For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Microsoft**. 1. Select **Add connection**. @@ -36,7 +36,7 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Microsoft Entra ID account. -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com). +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com). ### Create a Microsoft Entra ID app @@ -66,7 +66,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### Connect your Entra ID app and get your redirect URI - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Microsoft**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. Then: @@ -131,4 +131,4 @@ To make the setup process easier, it's recommended to keep two browser tabs open - Only credentials of type `secret` are supported (not the `certificate` type). > [!TIP] -> If you're using [SAML with Microsoft](/docs/authentication/saml/azure), the different tenant types _are_ supported, and you can disregard these limitations. +> If you're using [SAML with Microsoft](/docs/authentication/enterprise-connections/saml/azure), the different tenant types _are_ supported, and you can disregard these limitations. diff --git a/docs/authentication/social-connections/notion.mdx b/docs/authentication/social-connections/notion.mdx index 730a441ea3..f9c3c15e3f 100644 --- a/docs/authentication/social-connections/notion.mdx +++ b/docs/authentication/social-connections/notion.mdx @@ -18,7 +18,7 @@ For production instances, you will need to generate your own Client ID and Clien ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a Notion developer account. To create one, [click here](https://developers.notion.com/). ## Configuring Notion social connection @@ -31,7 +31,7 @@ You need to set a name, a logo, and associate a Notion workspace with it. Make s ![Configuring integration](/docs/images/authentication-providers/notion/configuring-integration.jpg) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Notion**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **Redirect URIs**, as shown below, after changing the integration type to **Public**. Fill any other information required from Notion and click Submit. +In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Notion**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **Redirect URIs**, as shown below, after changing the integration type to **Public**. Fill any other information required from Notion and click Submit. ![Copying values from the Notion dashboard](/docs/images/authentication-providers/notion/copying-values-from-notion-dashboard.jpg) diff --git a/docs/authentication/social-connections/oauth.mdx b/docs/authentication/social-connections/oauth.mdx index 80695dd1cd..daf2e7670a 100644 --- a/docs/authentication/social-connections/oauth.mdx +++ b/docs/authentication/social-connections/oauth.mdx @@ -8,12 +8,12 @@ Clerk makes it easy to add social connection capabilities to your application. W > [!NOTE] > When using social connections, the sign-up and sign-in flows are equivalent. If a user doesn't have an account and tries to sign in, an account will be made for them, and vice versa. -The easiest way to add social connections to your Clerk app is by using [prebuilt components](/docs/components/overview). If you prefer a more custom solution, check out how to [build a social connection flow using the Clerk API](/docs/custom-flows/oauth-connections). +The easiest way to add social connections to your Clerk app is by using [prebuilt components](/docs/components/overview). If you prefer a more custom solution, see the [build a social connection flow using the Clerk API guide](/docs/custom-flows/oauth-connections). ## Before you start -- You need to create a Clerk application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out the [Set up your application](/docs/quickstarts/setup-clerk) guide. -- You need to install the correct SDK for your application. You can find steps on how to do so through the [quickstart guides.](/docs/quickstarts/overview) +- You need to create a Clerk application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out the [setup guide](/docs/quickstarts/setup-clerk). +- You need to install the correct SDK for your application. For more information, see the [quickstart guides](/docs/quickstarts/overview). ## Enable a social connection @@ -21,8 +21,7 @@ For **development** instances, Clerk uses pre-configured shared OAuth credential To enable a social connection: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For all users**. 1. In the **Choose provider** dropdown, select the provider you want to use. 1. Select **Add connection**. @@ -97,7 +96,9 @@ export async function GET() { // Get the OAuth access token for the user const provider = 'oauth_notion' - const clerkResponse = await clerkClient().users.getUserOauthAccessToken(userId, provider) + const client = await clerkClient() + + const clerkResponse = await client.users.getUserOauthAccessToken(userId, provider) const accessToken = clerkResponse[0].token || '' @@ -132,8 +133,7 @@ For example, say your application wants to read a user's GitHub repository data To configure the option for users to sign up and sign in with a social provider: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the social provider you want to configure. 1. Enable or disable **Enable for sign-up and sign-in**. 1. Save the changes. @@ -142,20 +142,19 @@ To configure the option for users to sign up and sign in with a social provider: When signed in, a user can connect to further social providers. There is no need to perform another sign-up. -When using the [Account Portal](/docs/customization/account-portal/overview) pages, users can see which providers they have already connected to and which ones they can still connect to on their [user profile page.](/docs/customization/account-portal/overview#user-profile) +When using the [Account Portal](/docs/customization/account-portal/overview) pages, users can see which providers they have already connected to and which ones they can still connect to on their [user profile page](/docs/customization/account-portal/overview#user-profile). When using the [prebuilt components](/docs/components/overview), you can use the [``](/docs/components/user/user-profile) component to allow users to connect to further social providers. ## OAuth for native applications -Currently, the prebuilt components are not supported in native applications, but you can use the Clerk API to [build a custom flow for authenticating with social connections.](/docs/custom-flows/oauth-connections) +Currently, the prebuilt components are not supported in native applications, but you can use the Clerk API to [build a custom flow for authenticating with social connections](/docs/custom-flows/oauth-connections). Clerk ensures that security critical nonces are passed only to allowlisted URLs when the OAuth flow is completed in native browsers or webviews. For maximum security in your **production** instances, you need to allowlist your custom redirect URLs via the [Clerk Dashboard](https://dashboard.clerk.com/) or the [Clerk Backend API](/docs/references/backend/redirect-urls/create-redirect-url). To allowlist a redirect URL via the Clerk Dashboard: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Scroll to the **Allowlist for mobile OAuth redirect** section and add your redirect URLs. ## OAuth for Apple native applications @@ -164,4 +163,4 @@ You can use [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/ Instead of the typical OAuth flow that performs redirects in a browser context, you can utilize Apple's native authorization and provide the openID token and grant code to Clerk. Clerk ensures that the user will be verified in a secure and reliable way with the information that Apple has provided about the user. -See [the dedicated guide](/docs/authentication/social-connections/apple) for additional information on how to configure Apple as a social provider for your Clerk instance. +For additional information on how to configure Apple as a social provider for your Clerk instance, see the [dedicated guide](/docs/authentication/social-connections/apple). diff --git a/docs/authentication/social-connections/overview.mdx b/docs/authentication/social-connections/overview.mdx index a2502ae3a5..d97041a66e 100644 --- a/docs/authentication/social-connections/overview.mdx +++ b/docs/authentication/social-connections/overview.mdx @@ -157,4 +157,4 @@ Clerk provides a wide range of social providers to ease your user's sign-up and - ![](/docs/images/logos/auth_providers/huggingface.svg) -Don't see the provider you're looking for? You can [configure a custom OIDC-compatible provider](/docs/authentication/social-connections/custom-provider) or [request a new one.](https://feedback.clerk.com/roadmap/f9045ac8-0c8e-4f30-b84f-8d551b0767b9?_gl=1*1ywoqdy*_gcl_au*OTUwODgxMjg2LjE3MTI1OTEwNzMuMTczNjk0NTcxMC4xNzE1MTk4MTEyLjE3MTUxOTgxMTI.) +Don't see the provider you're looking for? You can [configure a custom OIDC-compatible provider](/docs/authentication/social-connections/custom-provider) or [request a new one](https://feedback.clerk.com/roadmap/f9045ac8-0c8e-4f30-b84f-8d551b0767b9?_gl=1*1ywoqdy*_gcl_au*OTUwODgxMjg2LjE3MTI1OTEwNzMuMTczNjk0NTcxMC4xNzE1MTk4MTEyLjE3MTUxOTgxMTI.). diff --git a/docs/authentication/social-connections/slack.mdx b/docs/authentication/social-connections/slack.mdx index 2e301137b7..2b57974f30 100644 --- a/docs/authentication/social-connections/slack.mdx +++ b/docs/authentication/social-connections/slack.mdx @@ -26,7 +26,7 @@ Enabling OAuth with [Slack](https://api.slack.com/authentication) allows your us For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Slack**. 1. Select **Add connection**. @@ -35,12 +35,12 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your Slack account. -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Slack's API Platform](https://api.slack.com/). +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Slack's API Platform](https://api.slack.com/). ### Enable Slack as a social connection in Clerk - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Slack**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. @@ -54,13 +54,13 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In the sidebar, navigate to the **OAuth & Permissions** page. 1. Scroll down to the **Redirect URLs** section and paste the **Redirect URI** you saved from the Clerk Dashboard. Select **Add**, then select **Save URLs**. - ### Set the Client ID and Client Secret in your Clerk Dashboard + ### Set the Client ID and Client Secret in the Clerk Dashboard - 1. Navigate back to your Clerk Dashboard where the modal should still be open. Paste the **Client ID** and **Client Secret** values that you saved into the respective fields. + 1. Navigate back to the Clerk Dashboard where the modal should still be open. Paste the **Client ID** and **Client Secret** values that you saved into the respective fields. 1. Select **Add connection**. > [!NOTE] - > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Slack** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Slack** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth diff --git a/docs/authentication/social-connections/spotify.mdx b/docs/authentication/social-connections/spotify.mdx index c424978abc..14bf02bde1 100644 --- a/docs/authentication/social-connections/spotify.mdx +++ b/docs/authentication/social-connections/spotify.mdx @@ -25,12 +25,12 @@ Enabling OAuth with [Spotify](https://developer.spotify.com/documentation/web-ap > [!CAUTION] > For **development** instances, [Spotify](https://developer.spotify.com/documentation/web-api/concepts/quota-modes) requires users to be added to the app's allowlist in order to use Spotify as a social provider in your Clerk app. If they are not allowlisted, any API requests made with an access token associated with that user and the Spotify app will receive a 403 status code. -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Spotify Developer Dashboard](https://developer.spotify.com/). +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Spotify Developer Dashboard](https://developer.spotify.com/). ### Enable Spotify as a social connection in Clerk - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Spotify**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. @@ -45,14 +45,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Save**. 1. On your app page, select **Settings**. Keep this page open. - ### Set the Client ID and Client Secret in your Clerk Dashboard + ### Set the Client ID and Client Secret in the Clerk Dashboard 1. In the Spotify app's settings page, save the **Client ID** and **Client secret** somewhere secure. To reveal the **Client secret**, you must select **View client secret**. - 1. Navigate back to your Clerk Dashboard where the modal should still be open and paste these values into the respective fields. + 1. Navigate back to the Clerk Dashboard where the modal should still be open and paste these values into the respective fields. 1. Select **Add connection**. > [!NOTE] - > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Spotify** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Spotify** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth diff --git a/docs/authentication/social-connections/tiktok.mdx b/docs/authentication/social-connections/tiktok.mdx index 22ebd030bf..bce2d59d5d 100644 --- a/docs/authentication/social-connections/tiktok.mdx +++ b/docs/authentication/social-connections/tiktok.mdx @@ -32,12 +32,12 @@ It is recommended to test this integration in a staging or preview environment, ## Configure for your production instance -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [TikTok Developer Portal](https://developers.tiktok.com/). +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [TikTok Developer Portal](https://developers.tiktok.com/). ### Enable TikTok as a social connection in Clerk - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **TikTok**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. Keep the modal and page open. @@ -60,14 +60,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open > [!NOTE] > Your app needs to be reviewed by TikTok before the registration completes. This process may take a few days. - ### Set the Client ID and Client Secret in your Clerk Dashboard + ### Set the Client ID and Client Secret in the Clerk Dashboard 1. In your TikTok app's **App details** page, select the icons next to the **Client key** and **Client secret** to reveal them. Copy these values. - 1. Navigate back to your Clerk Dashboard where the modal should still be open and paste these values into the respective fields. + 1. Navigate back to the Clerk Dashboard where the modal should still be open and paste these values into the respective fields. 1. Select **Add connection**. > [!NOTE] - > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **TikTok** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **TikTok** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth diff --git a/docs/authentication/social-connections/twitch.mdx b/docs/authentication/social-connections/twitch.mdx index d08bd2897a..c55d23cf14 100644 --- a/docs/authentication/social-connections/twitch.mdx +++ b/docs/authentication/social-connections/twitch.mdx @@ -18,7 +18,7 @@ For production instances, you will need to generate your own Client ID and Clien ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a Twitch account. To create one, [click here](https://www.twitch.tv/). ## Configuring Twitch social connection @@ -31,7 +31,7 @@ First, you need to register a new OAuth Twitch app at the [Twitch Developers Con Set a name and a category for your new application. You also need to add the **OAuth Redirect URLs.** -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Twitch**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **OAuth Redirect URLs** input and click create. +In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Twitch**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **OAuth Redirect URLs** input and click create. Once all the above are complete, copy the **Client ID** and **Client Secret.** Go back to the Clerk Dashboard and paste them into the respective fields. diff --git a/docs/authentication/social-connections/twitter.mdx b/docs/authentication/social-connections/twitter.mdx index 54449ced7b..4ef9177dfe 100644 --- a/docs/authentication/social-connections/twitter.mdx +++ b/docs/authentication/social-connections/twitter.mdx @@ -19,8 +19,8 @@ Clerk does not currently support preconfigured shared OAuth credentials for Twit ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). -- You need to have a Twitter Application set up so it can be used for Social connection. If you don't have a Twitter Application, click [here](https://developer.twitter.com/en/docs/apps/overview) for instructions on how to create one. If you already have one, please go to your [Twitter app settings](https://developer.twitter.com/en/portal/projects-and-apps) and ensure that the _"Allow this app to be used to Sign in with Twitter?_” option is enabled. +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). +- You need to have a Twitter Application set up so it can be used as a social connection. If you don't have a Twitter Application, click [here](https://developer.twitter.com/en/docs/apps/overview) for instructions on how to create one. If you already have one, go to your [Twitter app settings](https://developer.twitter.com/en/portal/projects-and-apps) and ensure that the _"Allow this app to be used to Sign in with Twitter?_” option is enabled. ## Configuring Twitter social connection @@ -31,7 +31,7 @@ To do so, go to "[Projects & Apps](https://developer.twitter.com/en/portal/proje > [!NOTE] > You will need your application to be approved for elevated status to be able to use it with Clerk. You can apply for the status in [Twitter developer dashboard](https://developer.twitter.com/en/portal/products/elevated) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Twitter**. Toggle on **Use custom credentials** and paste the **API Key** and **API Secret** values which you copied in the previous step. Then, copy the **Authorized Redirect URI**. +In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Twitter**. Toggle on **Use custom credentials** and paste the **API Key** and **API Secret** values which you copied in the previous step. Then, copy the **Authorized Redirect URI**. Navigate to your application settings screen and scroll down to the **User authentication settings** section and click **Set up**. diff --git a/docs/authentication/social-connections/x-twitter.mdx b/docs/authentication/social-connections/x-twitter.mdx index ed7aef095e..296986e1c3 100644 --- a/docs/authentication/social-connections/x-twitter.mdx +++ b/docs/authentication/social-connections/x-twitter.mdx @@ -6,7 +6,7 @@ description: Learn how to set up a social connection with X/Twitter v2 in your C ## Overview @@ -44,8 +44,7 @@ Clerk does not currently support preconfigured shared OAuth credentials for X/Tw To enable X/Twitter as a social connection for your Clerk application: - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For all users**. 1. In the **Choose provider** dropdown, select **X/Twitter**. 1. Toggle on **Use custom credentials** and copy **Redirect URI**. Keep this modal and page open. @@ -59,20 +58,20 @@ Clerk does not currently support preconfigured shared OAuth credentials for X/Tw 1. Under **App info**, in the **Callback URI / Redirect URL** input, paste the **Redirect URI** value you copied from the Clerk Dashboard. 1. Fill any other required fields, such as the **Website URL**, and select **Save**. - ### Set the Client ID and Client Secret in your Clerk Dashboard + ### Set the Client ID and Client Secret in the Clerk Dashboard After setting up your X/Twitter application, you should be able to copy your **Client ID** and **Client Secret**. Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. > [!NOTE] - > If the modal or page is not still open, navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Next to **X/Twitter**, select the settings icon. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, in the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Next to **X/Twitter**, select the settings icon. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth The simplest way to test your OAuth is to visit your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk applications out-of-the-box. - 1. In the navigation sidebar of the Clerk Dashboard, select [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal). + 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: - For development – [https://your-domain.accounts.dev/sign-in](https://your-domain.accounts.dev/sign-in) - For production – [https://accounts.your-domain.com/sign-in](https://accounts.your-domain.com/sign-in) diff --git a/docs/authentication/social-connections/xero.mdx b/docs/authentication/social-connections/xero.mdx index 385173ffdf..1a4f3fd0e1 100644 --- a/docs/authentication/social-connections/xero.mdx +++ b/docs/authentication/social-connections/xero.mdx @@ -18,7 +18,7 @@ For production instances, you will need to generate your own Client ID and Clien ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk). - You need to have a Xero developer account. To create one, [click here](https://developer.xero.com/). ## Configuring Xero social connection @@ -27,7 +27,7 @@ First, you need to create a new OAuth2 Xero app. Click New App and fill all the ![Creating a new application](/docs/images/authentication-providers/xero/creating-new-application.jpg) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Xero**. Toggle on **Use custom credentials** and copy **Redirect URI**. Make sure the value matches the **Redirect URIs**, as shown below. +In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Xero**. Toggle on **Use custom credentials** and copy **Redirect URI**. Make sure the value matches the **Redirect URIs**, as shown below. ![Copying values from the Xero dashboard](/docs/images/authentication-providers/xero/copying-values-from-xero-dashboard.jpg) diff --git a/docs/authentication/web3/coinbase-wallet.mdx b/docs/authentication/web3/coinbase-wallet.mdx index d7e5f26bcf..829b9f002e 100644 --- a/docs/authentication/web3/coinbase-wallet.mdx +++ b/docs/authentication/web3/coinbase-wallet.mdx @@ -18,19 +18,18 @@ description: Learn how to set up Web3 authentication with Coinbase Wallet. Enabling [Coinbase Wallet](https://www.coinbase.com/wallet) as a Web3 provider allows your users to sign in and sign up to your Clerk application with their Coinbase Wallet. Both [Smart Wallet](https://www.coinbase.com/wallet/smart-wallet) and the [Coinbase Wallet browser extension](https://www.coinbase.com/wallet/downloads) are supported. > [!WARNING] -> This guide is for using Coinbase Wallet for authentication. If you are looking to connect users via [Coinbase.com](https://www.coinbase.com/), see [the guide for enabling Coinbase as a social provider.](/docs/authentication/social-connections/coinbase) +> This guide is for using Coinbase Wallet for authentication. If you are looking to connect users via [Coinbase.com](https://www.coinbase.com/), see [the guide for enabling Coinbase as a social provider](/docs/authentication/social-connections/coinbase). ## Enable Coinbase Wallet as a Web3 provider -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/web3). -1. In the top navigation, select **Configure**. Then in the sidebar, select **Web3**. +1. In the Clerk Dashboard, navigate to the [**Web3**](https://dashboard.clerk.com/last-active?path=user-authentication/web3) page. 1. From the list of web3 providers, enable **Coinbase Wallet**. ## Test authentication The simplest way to test authentication is to visit your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk applications out-of-the-box. -1. In the sidebar of the Clerk Dashboard, select [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal). +1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: - **For development** – `https://your-domain.accounts.dev/sign-in` - **For production** – `https://accounts.your-domain.com/sign-in` @@ -42,8 +41,7 @@ Web3 applications typically utilize a hexadecimal wallet address to identify use To collect additional information about your user during sign-up: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/web3). -1. In the top navigation, select **Configure**. Then in the sidebar, select **[Email, phone, username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username)**. +1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. On this page, toggle on attributes you wish to collect from your user during sign up. Select the settings icon next to an attribute to set it as **Required**. When set as **Required**, Clerk automatically prompts the user for this information after they authenticate with Coinbase Wallet. ## Connect Coinbase Wallet to existing account diff --git a/docs/backend-requests/handling/go.mdx b/docs/backend-requests/handling/go.mdx index 72a6429039..3a2db118fe 100644 --- a/docs/backend-requests/handling/go.mdx +++ b/docs/backend-requests/handling/go.mdx @@ -7,7 +7,7 @@ description: Learn how to handle authenticated requests with Go middleware using The Clerk Go SDK provides an easy-to-use middleware that adds the active session to the request's context. -**Pro tip!** If you are signed into your Clerk Dashboard, your secret key should become visible by clicking on the eye icon. Otherwise, you can find your keys in the Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. +**Pro tip!** If you are signed into the Clerk Dashboard, your Secret Key should become visible by clicking on the eye icon. Otherwise, you can find your keys in the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. ```go {{ filename: 'main.go' }} package main diff --git a/docs/backend-requests/handling/manual-jwt.mdx b/docs/backend-requests/handling/manual-jwt.mdx index bdb780d2f4..26eb6ce46d 100644 --- a/docs/backend-requests/handling/manual-jwt.mdx +++ b/docs/backend-requests/handling/manual-jwt.mdx @@ -5,36 +5,93 @@ description: Learn how to manually verify Clerk-generated session tokens (JWTs). Your Clerk-generated [session tokens](/docs/backend-requests/resources/session-tokens) are essentially JWTs which are signed using your instance's private key and can be verified using your instance's public key. Depending on your architecture, these tokens will be in your backend requests either via a cookie named `__session` or via the Authorization header. -For every request, you must validate its token to make sure it hasn't expired and it is authentic (i.e. no malicious user tried to tamper with it). If these validations pass, then it means that the user is authenticated to your application and you should consider them signed in. +For every request, you must validate the token to ensure it hasn't expired or been tampered with (i.e., it's authentic and secure). If these validations succeed, then the user is authenticated to your application and should be considered signed in. The `authenticateRequest()` method from the JavaScript Backend SDK handles these validations for you. Alternatively, you can manually verify the token without using the SDK. See the following sections for more information. -The `authenticateRequest()` method from the JavaScript Backend SDK does all of this for you. It accepts the `request` object and authenticates the session token in it. See the [reference page](/docs/references/backend/authenticate-request) for more information. +## Use `authenticateRequest()` to verify a session token -## Networkless token verification +The [`authenticateRequest()`](/docs/references/backend/authenticate-request) method from the JavaScript Backend SDK accepts the `request` object and authenticates the session token in it. -{/* Note: this example is duped from /authenticate-request. Probably a good opportunity to use a partial here */} +The following example uses the `authenticateRequest()` method to verify the session token. It also performs networkless authentication by passing `jwtKey`. This verifies if the user is signed into the application. For more information, including usage with higher-level SDKs, see the [`authenticateRequest()` reference](/docs/references/backend/authenticate-request). -The following example uses the `authenticateRequest()` method with the [JavaScript Backend SDK](/docs/references/backend/overview) to verify the token passed by the frontend, and performs a networkless authentication by passing `jwtKey`. This will verify if the user is signed into the application or not. For more information, like using the method with higher-level SDK's, see the [`authenticateRequest()` reference](/docs/references/backend/authenticate-request). + -```tsx -import { createClerkClient } from '@clerk/backend' +## Manually verify a session token + + + ### Retrieve the session token + + Retrieve the session token from either `__session` cookie for a same-origin request or from the `Authorization` header for cross-origin requests. + + ### Get your instance's public key + + Use one of the three ways to obtain your public key: + + 1. Use the Backend API in JSON Web Key Set (JWKS) format at the following endpoint [https://api.clerk.com/v1/jwks](https://clerk.com/docs/reference/backend-api/tag/JWKS#operation/GetJWKS). + 1. Use your **Frontend API URL** in JWKS format, also known as **JWKS URL**. The format is `https:///.well-known/jwks.json`. To retrieve your **JWKS URL**, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard and select **Show JWT public key**. + 1. Use your **PEM Public Key**. To retrieve it, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard and select **Show JWT Public Key**. + + ### Verify the token signature + + To verify the token signature: + + 1. Use your instance's public key to verify the token's signature. + 1. Validate that the token isn't expired by checking the `exp` ([expiration time](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4)) and `nbf` ([not before](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5)) claims. + 1. Validate that the `azp` (authorized parties) claim equals any of your known origins permitted to generate those tokens. For better security, it's highly recommended to explicitly set the `authorizedParties` option when authorizing requests. The value should be a list of domains allowed to make requests to your application. Not setting this value can open your application to [CSRF attacks](https://owasp.org/www-community/attacks/csrf). For example, if you're permitting tokens retrieved from `http://localhost:3000`, then the `azp` claim should equal `http://localhost:3000`. You can also pass an array of strings, such as `['http://localhost:4003', 'https://clerk.dev']`. If the `azp` claim doesn't exist, you can skip this step. -export async function GET(req: Request) { - const clerkClient = createClerkClient({ - secretKey: process.env.CLERK_SECRET_KEY, - publishableKey: process.env.CLERK_PUBLISHABLE_KEY, - }) + ### Finished - const { isSignedIn } = await clerkClient.authenticateRequest(req, { - jwtKey: process.env.CLERK_JWT_KEY, - authorizedParties: ['https://example.com'], - }) + If the above process succeeds, the user is considered signed in to your application and authenticated. You can also retrieve the session ID and user ID from of the token's claims. + - if (!isSignedIn) { - return Response.json({ status: 401 }) +### Example + +The following example manually verifies a session token. + +```tsx +import Cookies from 'cookies' +import jwt from 'jsonwebtoken' + +export default async function (req: Request, res: Response) { + // Your public key should be set as an environment variable + const publicKey = process.env.CLERK_PEM_PUBLIC_KEY + // Retrieve session token from either `__session` cookie for a same-origin request + // or from the `Authorization` header for cross-origin requests + const cookies = new Cookies(req, res) + const tokenSameOrigin = cookies.get('__session') + const tokenCrossOrigin = req.headers.authorization + + if (!tokenSameOrigin && !tokenCrossOrigin) { + res.status(401).json({ error: 'Not signed in' }) + return } - // Add logic to perform protected actions + try { + let decoded + const options = { algorithms: ['RS256'] } // The algorithm used to sign the token. Optional. + const permittedOrigins = ['http://localhost:3000', 'https://example.com'] // Replace with your permitted origins - return Response.json({ message: 'This is a reply' }) + if (tokenSameOrigin) { + decoded = jwt.verify(tokenSameOrigin, publicKey, options) + } else { + decoded = jwt.verify(tokenCrossOrigin, publicKey, options) + } + + // Validate the token's expiration (exp) and not before (nbf) claims + const currentTime = Math.floor(Date.now() / 1000) + if (decoded.exp < currentTime || decoded.nbf > currentTime) { + throw new Error('Token is expired or not yet valid') + } + + // Validate the token's authorized party (azp) claim + if (decoded.azp && !permittedOrigins.includes(decoded.azp)) { + throw new Error("Invalid 'azp' claim") + } + + res.status(200).json({ sessionToken: decoded }) + } catch (error) { + res.status(400).json({ + error: error.message, + }) + } } ``` diff --git a/docs/backend-requests/handling/nodejs.mdx b/docs/backend-requests/handling/nodejs.mdx index 301b2cae3a..4c1e504b8c 100644 --- a/docs/backend-requests/handling/nodejs.mdx +++ b/docs/backend-requests/handling/nodejs.mdx @@ -4,7 +4,7 @@ description: Learn how to handle authenticated requests with Clerk's Node SDK. --- > [!CAUTION] -> On January 8, 2025, the Node SDK will no longer be available. [Upgrade to the Express SDK.](/docs/upgrade-guides/node-to-express) +> On January 8, 2025, the Node SDK will no longer be available. [Upgrade to the Express SDK](/docs/upgrade-guides/node-to-express). ## Node SDK Middleware @@ -14,7 +14,7 @@ The Clerk Node SDK offers two authentication middlewares specifically for [Expre `ClerkExpressWithAuth()` is a lax middleware that returns an empty auth object when an unauthenticated request is made. - + ```js import 'dotenv/config' // To read CLERK_SECRET_KEY and CLERK_PUBLISHABLE_KEY import { ClerkExpressWithAuth } from '@clerk/clerk-sdk-node' @@ -28,7 +28,7 @@ The Clerk Node SDK offers two authentication middlewares specifically for [Expre '/protected-endpoint', ClerkExpressWithAuth({ // Add options here - // See the Middleware options section for more details + // See the Middleware options section for more information }), (req, res) => { res.json(req.auth) @@ -60,7 +60,7 @@ The Clerk Node SDK offers two authentication middlewares specifically for [Expre '/protected-route', ClerkExpressWithAuth({ // Add options here - // See the Middleware options section for more details + // See the Middleware options section for more information }), (req: WithAuthProp, res: Response) => { res.json(req.auth) @@ -82,7 +82,7 @@ The Clerk Node SDK offers two authentication middlewares specifically for [Expre `ClerkExpressRequireAuth()` is a strict middleware that raises an error when an unauthenticated request is made. - + ```js import 'dotenv/config' // To read CLERK_SECRET_KEY and CLERK_PUBLISHABLE_KEY import { ClerkExpressRequireAuth } from '@clerk/clerk-sdk-node' @@ -96,7 +96,7 @@ The Clerk Node SDK offers two authentication middlewares specifically for [Expre '/protected-endpoint', ClerkExpressRequireAuth({ // Add options here - // See the Middleware options section for more details + // See the Middleware options section for more information }), (req, res) => { res.json(req.auth) @@ -132,7 +132,7 @@ The Clerk Node SDK offers two authentication middlewares specifically for [Expre '/protected-route', ClerkExpressRequireAuth({ // Add options here - // See the Middleware options section for more details + // See the Middleware options section for more information }), (req: RequireAuthProp, res) => { res.json(req.auth) @@ -180,7 +180,7 @@ These options can be used with both [`ClerkExpressWithAuth`](#clerk-express-with - `jwtKey` - `string` - Used to verify the session token in a networkless manner. Supply the PEM public key from the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section of the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt). + Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt). --- diff --git a/docs/backend-requests/making/custom-session-token.mdx b/docs/backend-requests/making/custom-session-token.mdx index 8c4a7f39ba..6a15fed211 100644 --- a/docs/backend-requests/making/custom-session-token.mdx +++ b/docs/backend-requests/making/custom-session-token.mdx @@ -9,17 +9,14 @@ By default, session tokens contain claims that are required for Clerk to functio This guide will show you how to customize a session token to include additional claims that you may need in your application. -> [!CAUTION] -> The entire session token has a max size of 4kb. Exceeding this size can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications. -> It's recommended to move particularly large claims out of the JWT and fetch these using a separate API call from your backend. + {/* TODO: Update the H3 to an H2 when the Steps component can accept headings other than H3. */} ### Add custom claims to your session token - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=sessions) and select your application. - 1. In the navigation sidebar, select **Sessions**. + 1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page. 1. In the **Customize your session token** section, click the **Edit** button. 1. In the modal that opens, you can add any claim to your session token that you need. @@ -35,7 +32,7 @@ This guide will show you how to customize a session token to include additional The following example demonstrates how to access the `fullName` and `primaryEmail` claims that were added to the session token in the last step. - + ```tsx {{ filename: 'app/page.tsx' }} import { auth } from '@clerk/nextjs/server' import { NextResponse } from 'next/server' diff --git a/docs/backend-requests/making/jwt-templates.mdx b/docs/backend-requests/making/jwt-templates.mdx index 1cb3e74226..4dce58e567 100644 --- a/docs/backend-requests/making/jwt-templates.mdx +++ b/docs/backend-requests/making/jwt-templates.mdx @@ -8,11 +8,13 @@ description: Learn how to create custom JWT templates to generate JSON Web Token Clerk offers the ability to generate [JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) (JWTs). Each JWT, or token, represents a user that is currently signed in to your application. -You can control the claims that will go into these tokens by creating custom **JWT Templates** that fit your needs. This enables you to integrate with any third-party services that support authentication with JWTs. An example use case is integrating with a third-party service that is able to consume JWTs, but requires them to be in a particular format. +You can control the claims that will go into these tokens by creating custom **JWT templates** that fit your needs. This enables you to integrate with any third-party services that support authentication with JWTs. An example use case is integrating with a third-party service that is able to consume JWTs, but requires them to be in a particular format. + + ## What is a JWT template? -**JWT Templates** are essentially JSON objects that specify claims to be included in the generated tokens, along with their respective values. +**JWT templates** are essentially JSON objects that specify claims to be included in the generated tokens, along with their respective values. Claim values can be either static or dynamic. @@ -165,10 +167,9 @@ A template consists of the following four properties: To create a JWT template: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). -1. In the navigation sidebar, select **JWT Templates**. +1. In the Clerk Dashboard, navigate to the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page. 1. Select **New template**. -1. You can either create a new template from scratch or use a provided template as a starting point. +1. You can either select a blank template or choose one of the provided templates. ## Generate a JWT @@ -176,7 +177,7 @@ To generate a token using a template, you can use the `getToken()` method. See t ## Complete example -The following example demonstrates the full capabilities of JWT Templates, including static claim values, dynamic claim values via shortcodes, and Clerk's "default claims". +The following example demonstrates the full capabilities of JWT templates, including static claim values, dynamic claim values via shortcodes, and Clerk's "default claims". Given the following user: diff --git a/docs/backend-requests/making/same-origin.mdx b/docs/backend-requests/making/same-origin.mdx index 11ff5a4bc5..1828554f37 100644 --- a/docs/backend-requests/making/same-origin.mdx +++ b/docs/backend-requests/making/same-origin.mdx @@ -17,7 +17,7 @@ fetch('/api/foo').then((res) => res.json()) If you are using React or Next.js and would like to use the [useSWR](https://swr.vercel.app/) hook, it’s as simple as supplying the API route with whichever fetcher function you are using. Because of the [automatic revalidation feature](https://swr.vercel.app/docs/revalidation) of SWR, you need to retrieve and set the session token in the Authorization header. Call the asynchronous `getToken` method from the [`useAuth()`](/docs/references/react/use-auth) hook and add it as a Bearer token. - + ```jsx import useSWR from 'swr' import { useAuth } from '@clerk/nextjs' diff --git a/docs/backend-requests/resources/session-tokens.mdx b/docs/backend-requests/resources/session-tokens.mdx index 1aacad3e1a..468659a991 100644 --- a/docs/backend-requests/resources/session-tokens.mdx +++ b/docs/backend-requests/resources/session-tokens.mdx @@ -5,6 +5,8 @@ description: Learn about session tokens and how to validate them in your backend When a user is authenticated in your application, Clerk generates a short-lived session token that you can use to authenticate requests to your backend. This token is a JSON Web Token (JWT) that contains information about the user and their session. +Learn more about how Clerk combines session token authentication and JWT authentication in the [blog post](https://clerk.com/blog/combining-the-benefits-of-session-tokens-and-jwts). + ## Default session claims Every generated token has default claims that cannot be overridden by templates. Clerk's default claims include: @@ -32,8 +34,24 @@ If you would like to add custom claims to your session token, you can [customize You can also create custom tokens using a [JWT template](/docs/backend-requests/making/jwt-templates). +## Size limitations + +The Clerk session token is stored in a cookie. All modern browsers [limit the maximum size of a cookie to 4kb](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). Exceeding this limit can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications. + +A session token with the [default session claims](#default-session-claims) won't run into this issue, as this configuration produces a cookie significantly smaller than 4kb. However, this limitation becomes relevant when implementing a [custom session token](/docs/backend-requests/making/custom-session-token) or creating a [custom JWT template](/docs/backend-requests/making/jwt-templates). In these cases, it's recommended to move particularly large claims out of the token and fetch these using a separate API call from your backend. + +Claims to monitor for size limits: + +- `user.organizations` +- `user.public_metadata` +- `user.unsafe_metadata` +- `org.public_metadata` +- `org_membership.public_metadata` + +If you include any of these claims in your token, use caution to ensure the stored data doesn't exceed the size limit. + ## Validate session tokens If you're using the middleware provided by our Clerk SDKs, this is all handled automatically in every request. If you're not using the middleware, you can still use the respective helpers provided by the SDKs to validate the tokens. -To learn how to manually verify a session token, please refer to the [dedicated guide](/docs/backend-requests/handling/manual-jwt). +To learn how to manually verify a session token, refer to the [dedicated guide](/docs/backend-requests/handling/manual-jwt). diff --git a/docs/backend-requests/versioning/available-versions.mdx b/docs/backend-requests/versioning/available-versions.mdx index 56eb20b1f6..726e69fd79 100644 --- a/docs/backend-requests/versioning/available-versions.mdx +++ b/docs/backend-requests/versioning/available-versions.mdx @@ -5,6 +5,14 @@ description: A list of the available API versions and their breaking changes. Below is a list of all the available API versions with their respective breaking changes. +### 2024-10-01 + +- Notification for new sign-ins to users' accounts feature becomes available. +- The response for sign-ins with an email address that matches a **SAML connection** is updated: + - Instead of responding with a status of `needs_identifier`, the API now returns a status of `needs_first_factor`. + - The email address that matched will be returned in the identifier field. + - The only strategy that will be included in supported first factors is `enterprise_sso`. + ### 2021-02-05 The initial API version was released on 2021-02-05 as part of the first Clerk release. It predates the versioning system. All changes made to it since then are backwards compatible. diff --git a/docs/components/authentication/google-one-tap.mdx b/docs/components/authentication/google-one-tap.mdx index 41509e3817..c6f746f335 100644 --- a/docs/components/authentication/google-one-tap.mdx +++ b/docs/components/authentication/google-one-tap.mdx @@ -54,7 +54,7 @@ The following example includes basic implementation of the `` co > [!NOTE] > `` does not render if the user is already signed into your Clerk application, so there's no need to manually check if a user is signed in yourself before rendering it. - + ```tsx {{ filename: 'app/layout.tsx', mark: [2, 11] }} import React from 'react' @@ -115,7 +115,7 @@ function openGoogleOneTap(params: GoogleOneTapProps): void ```js {{ filename: 'main.js', mark: [[9, 14]] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -142,7 +142,7 @@ function closeGoogleOneTap(): void ```js {{ filename: 'main.js', mark: [18] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -184,7 +184,7 @@ function authenticateWithGoogleOneTap( ```js {{ filename: 'main.js', mark: [[9, 17]] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) diff --git a/docs/components/authentication/sign-in.mdx b/docs/components/authentication/sign-in.mdx index b180e73ebb..6addc5bd39 100644 --- a/docs/components/authentication/sign-in.mdx +++ b/docs/components/authentication/sign-in.mdx @@ -3,9 +3,9 @@ title: '`` component' description: Clerk's component renders a UI for signing in users. --- -![The \ component renders a UI for signing in users.](/docs/images/ui-components/sign-in.svg) +![The \ component renders a UI for signing in users.](/docs/images/ui-components/sign-in.png){{ style: { maxWidth: '460px' } }} -The `` component renders a UI for signing in users. The functionality of the `` component is controlled by the instance settings you specify in your [Clerk Dashboard](https://dashboard.clerk.com), such as [sign-in and sign-up options](/docs/authentication/configuration/sign-up-sign-in-options) and [social connections](/docs/authentication/social-connections/overview). You can further customize your `` component by passing additional [properties](#properties) at the time of rendering. +The `` component 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-in and sign-up options](/docs/authentication/configuration/sign-up-sign-in-options) and [social connections](/docs/authentication/social-connections/overview). You can further customize your `` component by passing additional [properties](#properties) at the time of rendering. > [!NOTE] > The `` and `` components cannot render when a user is already signed in, unless the application allows multiple sessions. If a user is already signed in and the application only allows a single session, Clerk will redirect the user to the Home URL instead. @@ -81,18 +81,25 @@ All props are optional. - `transferable?` - `boolean` - Indicates whether or not sign in attempts are transferable to the sign up flow. Defaults to `true`. When set to `false`, prevents opaque sign ups when a user attempts to sign in via OAuth with an email that doesn't exist. See [OAuth account transfer flows](/docs/custom-flows/oauth-connections#o-auth-account-transfer-flows) for more details. + Indicates whether or not sign in attempts are transferable to the sign up flow. Defaults to `true`. When set to `false`, prevents opaque sign ups when a user attempts to sign in via OAuth with an email that doesn't exist. See [OAuth account transfer flows](/docs/custom-flows/oauth-connections#o-auth-account-transfer-flows) for more information. + + --- + + - `waitlistUrl?` + - `string` + + Full URL or path to the waitlist page. Use this property to provide the target of the 'Waitlist' link that's rendered. If `undefined`, will redirect to the [Account Portal waitlist page](/docs/customization/account-portal/overview#waitlist). If you've passed the `waitlistUrl` prop to the [``](/docs/components/clerk-provider) component, it will infer from that, and you can omit this prop. ## Usage with frameworks The following example includes basic implementation of the `` component. You can use this as a starting point for your own implementation. - + The following example demonstrates how you can use the `` component on a public page. - If you would like to create a dedicated `/sign-in` page in your Next.js application, check out the [dedicated guide.](/docs/references/nextjs/custom-signup-signin-pages). + If you would like to create a dedicated `/sign-in` page in your Next.js application, see the [dedicated guide](/docs/references/nextjs/custom-signup-signin-pages). ```tsx {{ filename: 'app/page.tsx' }} import { SignIn, useUser } from '@clerk/nextjs' @@ -185,7 +192,7 @@ function mountSignIn(node: HTMLDivElement, props?: SignInProps): void ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -222,7 +229,7 @@ function unmountSignIn(node: HTMLDivElement): void ```js {{ filename: 'index.js', mark: [19] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -263,7 +270,7 @@ function openSignIn(props?: SignInProps): void ```js {{ filename: 'main.js', mark: [9] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -285,7 +292,7 @@ function closeSignIn(): void ```js {{ filename: 'index.js', mark: [13] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) diff --git a/docs/components/authentication/sign-up.mdx b/docs/components/authentication/sign-up.mdx index f7f47eef2d..950fe34e60 100644 --- a/docs/components/authentication/sign-up.mdx +++ b/docs/components/authentication/sign-up.mdx @@ -3,9 +3,9 @@ title: '`` component' description: Clerk's component renders a UI for signing up users. --- -![The \ component renders a UI for signing up users.](/docs/images/ui-components/sign-up.svg) +![The \ component renders a UI for signing up users.](/docs/images/ui-components/sign-up.png){{ style: { maxWidth: '460px' } }} -The `` component renders a UI for signing up users. The functionality of the `` component is controlled by the instance settings you specify in your [Clerk Dashboard](https://dashboard.clerk.com), such as [sign-in and sign-up options](/docs/authentication/configuration/sign-up-sign-in-options) and [social connections](/docs/authentication/social-connections/overview). You can further customize your `` component by passing additional [properties](#properties) at the time of rendering. +The `` component 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-in and sign-up options](/docs/authentication/configuration/sign-up-sign-in-options) and [social connections](/docs/authentication/social-connections/overview). You can further customize your `` component by passing additional [properties](#properties) at the time of rendering. > [!NOTE] > The `` and `` components cannot render when a user is already signed in, unless the application allows multiple sessions. If a user is already signed in and the application only allows a single session, Clerk will redirect the user to the Home URL instead. @@ -75,17 +75,24 @@ All props are optional. - [`SignUpInitialValues`](/docs/references/javascript/types/sign-up-initial-values) The values used to prefill the sign-up fields with. + + --- + + - `unsafeMetadata` + - `{[string]: any} | null` + + An object containing key-value pairs for `unsafeMetadata` that will be saved after the user signs up. For example: `{ "company": "companyID1234" }`. ## Usage with frameworks The following example includes basic implementation of the `` component. You can use this as a starting point for your own implementation. - + The following example demonstrates how you can use the `` component on a public page. - If you would like to create a dedicated `/sign-up` page in your Next.js application, check out the [dedicated guide.](/docs/references/nextjs/custom-signup-signin-pages). + If you would like to create a dedicated `/sign-up` page in your Next.js application, see the [dedicated guide](/docs/references/nextjs/custom-signup-signin-pages). ```tsx {{ filename: 'app/page.tsx' }} import { SignUp, useUser } from '@clerk/nextjs' @@ -178,7 +185,7 @@ function mountSignUp(node: HTMLDivElement, props?: SignUpProps): void ```typescript {{ filename: 'main.ts', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -215,7 +222,7 @@ function unmountSignUp(node: HTMLDivElement): void ```typescript {{ filename: 'main.ts', mark: [19] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -256,7 +263,7 @@ function openSignUp(props?: SignUpProps): void ```js {{ filename: 'main.js', mark: [9] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -278,7 +285,7 @@ function closeSignUp(): void ```js {{ filename: 'main.js', mark: [13] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) diff --git a/docs/components/clerk-provider.mdx b/docs/components/clerk-provider.mdx index ecd5a10ecc..abe1e84ba0 100644 --- a/docs/components/clerk-provider.mdx +++ b/docs/components/clerk-provider.mdx @@ -9,23 +9,20 @@ The `` component wraps your React application to provide active s The `` component must be added to your React entrypoint. - + - + ```tsx {{ filename: 'app/layout.tsx' }} import React from 'react' import { ClerkProvider } from '@clerk/nextjs' export default function RootLayout({ children }: { children: React.ReactNode }) { return ( - - - Next.js 13 with Clerk - - + + {children} - - + + ) } ``` @@ -149,7 +146,7 @@ The `` component must be added to your React entrypoint. - `publishableKey` - `string` - The Clerk publishable key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. + The Clerk Publishable 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. --- @@ -223,6 +220,13 @@ The `` component must be added to your React entrypoint. --- + - `syncHost` + - `string` + + **Chrome Extension only** To enable, pass the URL of the web application that the extension will sync the authentication state from. See the [dedicated guide](/docs/references/chrome-extension/sync-host) for more information. + + --- + - `nonce?` - `string` @@ -254,7 +258,7 @@ The `` component must be added to your React entrypoint. - `touchSession?` - `boolean` - By default, [the Clerk Frontend API `touch` endpoint](https://clerk.com/docs/reference/frontend-api/tag/Sessions#operation/touchSession) is called during page focus to keep the last active session alive. This option allows you to disable this behavior. You don't need to set this value yourself unless you're [developing an SDK](/docs/references/sdk/overview). + By default, [the Clerk Frontend API `touch` endpoint](/docs/reference/frontend-api/tag/Sessions#operation/touchSession){{ target: '_blank' }} is called during page focus to keep the last active session alive. This option allows you to disable this behavior. You don't need to set this value yourself unless you're [developing an SDK](/docs/references/sdk/overview). --- @@ -269,6 +273,13 @@ The `` component must be added to your React entrypoint. - `boolean` (For Next.js only) Indicates whether or not Clerk should make dynamic auth data available based on the current request. Defaults to `false`. Opts the application into dynamic rendering when `true`. For more information, see [Next.js rendering modes and Clerk](/docs/references/nextjs/rendering-modes). + + --- + + - `waitlistUrl?` + - `string` + + Full URL or path to the waitlist page. If `undefined`, will redirect to the [Account Portal waitlist page](/docs/customization/account-portal/overview#waitlist). [components-ref]: /docs/components/overview diff --git a/docs/components/control/clerk-loaded.mdx b/docs/components/control/clerk-loaded.mdx index 73c0004e03..5e97fffbbe 100644 --- a/docs/components/control/clerk-loaded.mdx +++ b/docs/components/control/clerk-loaded.mdx @@ -7,9 +7,9 @@ The `` component guarantees that the Clerk object has loaded and wi ## Usage - + - + ```tsx {{ filename: 'app/layout.tsx' }} import { ClerkProvider, ClerkLoaded, ClerkLoading } from '@clerk/nextjs' diff --git a/docs/components/control/clerk-loading.mdx b/docs/components/control/clerk-loading.mdx index 37bf4faecc..cadfa2f3f6 100644 --- a/docs/components/control/clerk-loading.mdx +++ b/docs/components/control/clerk-loading.mdx @@ -7,9 +7,9 @@ The `` renders its children while Clerk is loading, and is helpful ## Usage - + - + ```tsx {{ filename: 'app/layout.tsx' }} import { ClerkProvider, ClerkLoaded, ClerkLoading } from '@clerk/nextjs' import './globals.css' diff --git a/docs/components/control/multi-session.mdx b/docs/components/control/multi-session.mdx index cceb7300e7..cdb5c47d62 100644 --- a/docs/components/control/multi-session.mdx +++ b/docs/components/control/multi-session.mdx @@ -7,7 +7,7 @@ The `` provides a wrapper for your React application tha ## Usage - + ```tsx {{ filename: 'pages/_app.tsx' }} import '@/styles/globals.css' diff --git a/docs/components/control/redirect-to-createorganization.mdx b/docs/components/control/redirect-to-createorganization.mdx index 33e8eb7e36..b7ae1cfa41 100644 --- a/docs/components/control/redirect-to-createorganization.mdx +++ b/docs/components/control/redirect-to-createorganization.mdx @@ -7,7 +7,7 @@ The `` component will navigate to the create org ## Usage - + ```tsx {{ filename: 'pages/_app.tsx' }} import { ClerkProvider, SignedIn, SignedOut, RedirectToCreateOrganization } from '@clerk/nextjs' @@ -19,7 +19,7 @@ The `` component will navigate to the create org - Please Sign In + Sign In ) } @@ -43,7 +43,7 @@ The `` component will navigate to the create org - Please Sign In + Sign In ) } @@ -61,7 +61,7 @@ The `` component will navigate to the create org -

Please sign in

+

Sign in

) diff --git a/docs/components/control/redirect-to-organizationprofile.mdx b/docs/components/control/redirect-to-organizationprofile.mdx index 055e1bc7e1..77fe1c9ff4 100644 --- a/docs/components/control/redirect-to-organizationprofile.mdx +++ b/docs/components/control/redirect-to-organizationprofile.mdx @@ -7,7 +7,7 @@ The `` component will navigate to the organizat ## Usage - + ```tsx {{ filename: 'pages/_app.tsx' }} import { ClerkProvider, SignedIn, SignedOut, RedirectToOrganizationProfile } from '@clerk/nextjs' @@ -19,7 +19,7 @@ The `` component will navigate to the organizat - Please Sign In + Sign In ) } @@ -43,7 +43,7 @@ The `` component will navigate to the organizat - Please Sign In + Sign In ) } @@ -61,7 +61,7 @@ The `` component will navigate to the organizat -

Please sign in

+

Sign in

) diff --git a/docs/components/control/redirect-to-signup.mdx b/docs/components/control/redirect-to-signup.mdx index 69baecb438..fb4ffed8b2 100644 --- a/docs/components/control/redirect-to-signup.mdx +++ b/docs/components/control/redirect-to-signup.mdx @@ -7,7 +7,7 @@ The `` component will navigate to the sign up URL which has ## Usage - + ```tsx {{ filename: 'app/layout.tsx' }} diff --git a/docs/components/control/redirect-to-userprofile.mdx b/docs/components/control/redirect-to-userprofile.mdx index 894d83a30c..2fc581b975 100644 --- a/docs/components/control/redirect-to-userprofile.mdx +++ b/docs/components/control/redirect-to-userprofile.mdx @@ -7,8 +7,7 @@ The `` component will navigate to the Account Portal Us To find your User Profile URL: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=account-portal). -1. In the navigation sidebar, select **Account Portal**. +1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. 1. Under **User profile**, select the **Visit** icon. ## Usage @@ -25,7 +24,7 @@ To find your User Profile URL: - Please Sign In + Sign In ) } @@ -44,7 +43,7 @@ To find your User Profile URL: - Please Sign In + Sign In ) } @@ -62,7 +61,7 @@ To find your User Profile URL: -

Please sign in

+

Sign in

) diff --git a/docs/components/control/signed-in.mdx b/docs/components/control/signed-in.mdx index b82dc24839..1f4ce5de05 100644 --- a/docs/components/control/signed-in.mdx +++ b/docs/components/control/signed-in.mdx @@ -9,7 +9,7 @@ The `` component offers authentication checks as a cross-cutting conce ## Usage - + ```tsx {{ filename: 'app.tsx' }} import '@/styles/globals.css' @@ -87,7 +87,7 @@ The `` component offers authentication checks as a cross-cutting conce Below is an example of how to use `` with React Router. The `` component can be used as a child of a `` component to render content only to signed in users. ```tsx {{ filename: 'app.tsx' }} -import { Routes, Route } from 'react-router-dom' +import { Routes, Route } from 'react-router' import { ClerkProvider, SignedIn } from '@clerk/clerk-react' function App() { diff --git a/docs/components/control/signed-out.mdx b/docs/components/control/signed-out.mdx index 91f93eb17f..13b17b0aa3 100644 --- a/docs/components/control/signed-out.mdx +++ b/docs/components/control/signed-out.mdx @@ -7,7 +7,7 @@ The `` component offers authentication checks as a cross-cutting conc ## Usage - + ```tsx {{ filename: 'app.tsx' }} import '@/styles/globals.css' @@ -52,7 +52,7 @@ The `` component offers authentication checks as a cross-cutting conc Below is an example of how to use `` with React Router. The `` component can be used as a child of a `` component to render content only to signed in users. ```tsx {{ filename: 'app.tsx' }} - import { Routes, Route } from 'react-router-dom' + import { Routes, Route } from 'react-router' import { ClerkProvider, SignedOut, RedirectToSignIn } from '@clerk/clerk-react' function App() { diff --git a/docs/components/organization/create-organization.mdx b/docs/components/organization/create-organization.mdx index 3454c910b0..b083ec1043 100644 --- a/docs/components/organization/create-organization.mdx +++ b/docs/components/organization/create-organization.mdx @@ -3,9 +3,9 @@ title: '`` component' description: Clerk's component is used to render an organization creation UI that allows users to create brand new organizations within your application. --- -![The \ component renders an organization creation UI that allows users to create brand new organizations within your application.](/docs/images/ui-components/create-organization.svg) +![The \ component renders an organization creation UI that allows users to create brand new organizations within your application.](/docs/images/ui-components/create-organization.png){{ style: { maxWidth: '492px' } }} -The `` component is used to render an organization creation UI that allows users to create brand new organizations within your application. +The `` component is used to render an organization creation UI that allows users to create brand new organizations in your application. ## Properties @@ -57,25 +57,15 @@ All props are optional. The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. - + - - ```jsx {{ filename: '/app/create-organization/[[...create-organization]]/page.tsx' }} - import { CreateOrganization } from '@clerk/nextjs' - - export default function CreateOrganizationPage() { - return - } - ``` - - ```jsx {{ filename: '/pages/create-organization/[[...index]].tsx' }} - import { CreateOrganization } from '@clerk/nextjs' - - export default function CreateOrganizationPage() { - return - } - ``` - + ```jsx {{ filename: '/app/create-organization/[[...create-organization]]/page.tsx' }} + import { CreateOrganization } from '@clerk/nextjs' + + export default function CreateOrganizationPage() { + return + } + ``` @@ -93,7 +83,7 @@ The following example includes a basic implementation of the ` + return } ``` @@ -149,7 +139,7 @@ function mountCreateOrganization(node: HTMLDivElement, props?: CreateOrganizatio ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -186,7 +176,7 @@ function unmountCreateOrganization(node: HTMLDivElement): void ```js {{ filename: 'main.js', mark: [19] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -227,7 +217,7 @@ function openCreateOrganization(props?: CreateOrganizationProps): void ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -255,7 +245,7 @@ function closeCreateOrganization(): void ```js {{ filename: 'main.js', mark: [19] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) diff --git a/docs/components/organization/organization-list.mdx b/docs/components/organization/organization-list.mdx index 23f333e359..c11dcfaf9b 100644 --- a/docs/components/organization/organization-list.mdx +++ b/docs/components/organization/organization-list.mdx @@ -3,7 +3,7 @@ title: '`` component' description: Clerk's component is used to display organization related memberships, invitations, and suggestions for the user. --- -![The \ component is used to display organization related memberships, invitations, and suggestions for the user.](/docs/images/ui-components/organization-list.svg) +![The \ component is used to display organization related memberships, invitations, and suggestions for the user.](/docs/images/ui-components/organization-list.png){{ style: { maxWidth: '460px' } }} The `` component is used to display organization related memberships, [invitations, and suggestions](/docs/organizations/overview#automatic-invitations-and-suggestions) for the user. @@ -62,37 +62,21 @@ All props are optional. ## Usage with frameworks - + - - ```jsx {{ filename: '/app/discover/page.tsx' }} - import { OrganizationList } from '@clerk/nextjs' - - export default function OrganizationListPage() { - return ( - - ) - } - ``` - - ```jsx {{ filename: '/pages/discover.tsx' }} - import { OrganizationList } from '@clerk/nextjs' - - export default function OrganizationListPage() { - return ( - `/organization/${org.slug}`} - afterSelectPersonalUrl={(user) => `/user/${user.id}`} - afterSelectOrganizationUrl={(org) => `/organization/${org.slug}`} - /> - ) - } - ``` - + ```jsx {{ filename: '/app/discover/page.tsx' }} + import { OrganizationList } from '@clerk/nextjs' + + export default function OrganizationListPage() { + return ( + + ) + } + ``` @@ -180,7 +164,7 @@ function mountOrganizationList(node: HTMLDivElement, props?: OrganizationListPro ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -217,7 +201,7 @@ function unmountOrganizationList(node: HTMLDivElement): void ```js {{ filename: 'main.js', mark: [19] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) diff --git a/docs/components/organization/organization-profile.mdx b/docs/components/organization/organization-profile.mdx index 06e8350605..54f9c09a80 100644 --- a/docs/components/organization/organization-profile.mdx +++ b/docs/components/organization/organization-profile.mdx @@ -3,7 +3,7 @@ title: '`` component' description: Clerks component is used to render a beautiful, full-featured organization management UI that allows users to manage their organization profile and security settings. --- -![The \ component renders a full-featured organization management UI that allows users to manage their organization profile and security settings.](/docs/images/ui-components/organization-profile.svg) +![The \ component renders a full-featured organization management UI that allows users to manage their organization profile and security settings.](/docs/images/ui-components/organization-profile.png) The `` component is used to render a beautiful, full-featured organization management UI that allows users to manage their organization profile and security settings. @@ -52,27 +52,17 @@ All props are optional. ## Usage with frameworks - + You can embed the `` component using the [Next.js optional catch-all route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-routes). This allows you to redirect the user inside your application. - - ```jsx {{ filename: '/app/organization-profile/[[...organization-profile]]/page.tsx' }} - import { OrganizationProfile } from '@clerk/nextjs' + ```jsx {{ filename: '/app/organization-profile/[[...organization-profile]]/page.tsx' }} + import { OrganizationProfile } from '@clerk/nextjs' - export default function OrganizationProfilePage() { - return - } - ``` - - ```jsx {{ filename: '/pages/organization-profile/[[...index]].tsx' }} - import { OrganizationProfile } from '@clerk/nextjs' - - export default function OrganizationProfilePage() { - return - } - ``` - + export default function OrganizationProfilePage() { + return + } + ``` @@ -90,7 +80,7 @@ All props are optional. import { OrganizationProfile } from '@clerk/remix' export default function OrganizationProfilePage() { - return + return } ``` @@ -146,7 +136,7 @@ function mountOrganizationProfile(node: HTMLDivElement, props?: OrganizationProf ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -183,7 +173,7 @@ function unmountOrganizationProfile(node: HTMLDivElement): void ```js {{ filename: 'main.js', mark: [19] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -224,7 +214,7 @@ function openOrganizationProfile(props?: OrganizationProfileProps): void ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -252,7 +242,7 @@ function closeOrganizationProfile(): void ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) diff --git a/docs/components/organization/organization-switcher.mdx b/docs/components/organization/organization-switcher.mdx index 4631c64094..734ae48d85 100644 --- a/docs/components/organization/organization-switcher.mdx +++ b/docs/components/organization/organization-switcher.mdx @@ -3,13 +3,13 @@ title: '`` component' description: Clerk's component is used to enable the ability to switch between available organizations the user may be part of in your application. --- -![The \ component is used to enable the ability to switch between available organizations the user may be part of in your application.](/docs/images/ui-components/organization-switcher.svg) +![The \ component is used to enable the ability to switch between available organizations the user may be part of in your application.](/docs/images/ui-components/organization-switcher.png){{ style: { maxWidth: '436px' } }} The `` component allows a user to switch between their account types - their personal account and their joined organizations. This component is useful for applications that have a multi-tenant architecture, where users can be part of multiple organizations. This component will show notifications to the user if they have organization [invitations](/docs/organizations/overview#organization-invitations) or [suggestions](/docs/organizations/overview#suggestions). Admins will be able to see notifications for [requests](/docs/organizations/overview#membership-requests) to join an organization. -If you would like to learn how to hide a user's personal account in order to enforce an organization-centric application, see the [dedicated guide.](/docs/guides/force-organizations) +If you would like to learn how to hide a user's personal account in order to enforce an organization-centric application, see the [dedicated guide](/docs/guides/force-organizations). ## `` properties @@ -103,31 +103,17 @@ All props below are optional. - - ```jsx {{ filename: '/app/organization-switcher/[[...organization-switcher]]/page.tsx' }} - import { OrganizationSwitcher } from '@clerk/nextjs' - - export default function OrganizationSwitcherPage() { - return ( -
- -
- ) - } - ``` - - ```jsx {{ filename: '/pages/organization-switcher/[[...index]].tsx' }} - import { OrganizationSwitcher } from '@clerk/nextjs' - - export default function OrganizationSwitcherPage() { - return ( -
- -
- ) - } - ``` - + ```jsx {{ filename: '/app/organization-switcher/[[...organization-switcher]]/page.tsx' }} + import { OrganizationSwitcher } from '@clerk/nextjs' + + export default function OrganizationSwitcherPage() { + return ( +
+ +
+ ) + } + ``` @@ -207,7 +193,7 @@ function mountOrganizationSwitcher(node: HTMLDivElement, props?: OrganizationSwi ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -244,7 +230,7 @@ function unmountOrganizationSwitcher(node: HTMLDivElement): void ```js {{ filename: 'main.js', mark: [19] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) diff --git a/docs/components/unstyled/sign-in-button.mdx b/docs/components/unstyled/sign-in-button.mdx index e0f28a4194..9bbcd55c30 100644 --- a/docs/components/unstyled/sign-in-button.mdx +++ b/docs/components/unstyled/sign-in-button.mdx @@ -54,6 +54,13 @@ The `` component is a button that links to the sign-in page or dis - `React.ReactNode` Children you want to wrap the `` in. + + --- + + - `initialValues` + - [`SignInInitialValues`](/docs/references/javascript/types/sign-in-initial-values) + + The values used to prefill the sign-in fields with. ## Usage @@ -104,7 +111,7 @@ The `` component is a button that links to the sign-in page or dis ### Custom usage -You can create a custom button by wrapping your own button, or button text, in the `` component. +You can create a custom button by wrapping your own button, or button text, in the `` component. diff --git a/docs/components/unstyled/sign-in-with-metamask.mdx b/docs/components/unstyled/sign-in-with-metamask.mdx index 7f502bdc40..1ac99a6564 100644 --- a/docs/components/unstyled/sign-in-with-metamask.mdx +++ b/docs/components/unstyled/sign-in-with-metamask.mdx @@ -9,7 +9,7 @@ The `` component is used to complete a one-click, cryp ### Basic usage - + ```jsx {{ filename: 'pages/index.js' }} import { SignInWithMetamaskButton } from '@clerk/nextjs' @@ -54,7 +54,7 @@ The `` component is used to complete a one-click, cryp In some cases, you will want to use your own button, or button text. You can do that by wrapping your button in the `` component. - + ```jsx {{ filename: 'pages/index.js' }} import { SignInWithMetamaskButton } from '@clerk/nextjs' diff --git a/docs/components/unstyled/sign-up-button.mdx b/docs/components/unstyled/sign-up-button.mdx index 981fe733ba..54b69d26f7 100644 --- a/docs/components/unstyled/sign-up-button.mdx +++ b/docs/components/unstyled/sign-up-button.mdx @@ -54,6 +54,13 @@ The `` component is a button that links to the sign-up page or dis - `React.ReactNode` Children you want to wrap the `` in. + + --- + + - `initialValues` + - [`SignUpInitialValues`](/docs/references/javascript/types/sign-up-initial-values) + + The values used to prefill the sign-up fields with. ## Usage diff --git a/docs/components/user/user-button.mdx b/docs/components/user/user-button.mdx index db405de874..3b7811ee1c 100644 --- a/docs/components/user/user-button.mdx +++ b/docs/components/user/user-button.mdx @@ -3,11 +3,11 @@ title: '`` component' description: Clerk's component is used to render the familiar user button UI popularized by Google. --- -![The \ component renders the familiar user button UI popularized by Google.](/docs/images/ui-components/user-button.svg) +![The \ component renders the familiar user button UI popularized by Google.](/docs/images/ui-components/user-button.png){{ style: { maxWidth: '436px' } }} The `` component is used to render the familiar user button UI popularized by Google. -Clerk is the only provider with multi-session support, allowing users to sign into multiple accounts at once and switch between them. For multi-session apps, the `` automatically supports instant account switching, without the need of a full page reload. For more information, you can check out the [Multi-session applications guide](/docs/custom-flows/multi-session-applications#overview). +Clerk is the only provider with multi-session support, allowing users to sign into multiple accounts at once and switch between them. For multi-session apps, the `` automatically supports instant account switching, without the need of a full page reload. For more information, see the [dedicated guide on multi-session apps](/docs/custom-flows/multi-session-applications#overview). ## Properties @@ -87,9 +87,9 @@ All props are optional. In the following example, `` is mounted inside a header component, which is a common pattern on many websites and applications. When the user is signed in, they will see their avatar and be able to open the popup menu. - + - + ```tsx {{ filename: 'layout.tsx' }} import { ClerkProvider, SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs' @@ -287,7 +287,7 @@ function mountUserButton(node: HTMLDivElement, props?: UserButtonProps): void ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -324,7 +324,7 @@ function unmountUserButton(node: HTMLDivElement): void ```js {{ filename: 'main.js', mark: [19] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -347,4 +347,4 @@ clerk.unmountUserButton(userButtonDiv) To learn about how to customize Clerk components, see the [customization documentation](/docs/customization/overview). -You can also [add custom actions and links to the `` menu.](/docs/customization/user-button) +You can also [add custom actions and links to the `` menu](/docs/customization/user-button). diff --git a/docs/components/user/user-profile.mdx b/docs/components/user/user-profile.mdx index 2a5609828e..e303ba5be1 100644 --- a/docs/components/user/user-profile.mdx +++ b/docs/components/user/user-profile.mdx @@ -3,7 +3,7 @@ title: '`` component' description: Clerk's component is used to render a beautiful, full-featured account management UI that allows users to manage their profile and security settings. --- -![The \ component renders a full-featured account management UI that allows users to manage their profile and security settings.](/docs/images/ui-components/user-profile.svg) +![The \ component renders a full-featured account management UI that allows users to manage their profile and security settings.](/docs/images/ui-components/user-profile.png){{ style: { maxWidth: '100%' } }} The `` component is used to render a beautiful, full-featured account management UI that allows users to manage their profile and security settings. @@ -48,7 +48,7 @@ All props are optional. ## Usage with frameworks - + You can embed the `` component using the [Next.js optional catch-all route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-routes). This allows you to redirect the user inside your application. @@ -142,7 +142,7 @@ function mountUserProfile(node: HTMLDivElement, props?: UserProfileProps): void ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -179,7 +179,7 @@ function unmountUserProfile(node: HTMLDivElement): void ```js {{ filename: 'main.js', mark: [19] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -220,7 +220,7 @@ function openUserProfile(props?: UserProfileProps): void ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) @@ -248,7 +248,7 @@ function closeUserProfile(): void ```js {{ filename: 'main.js', mark: [15] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(clerkPubKey) diff --git a/docs/components/waitlist.mdx b/docs/components/waitlist.mdx new file mode 100644 index 0000000000..ee5e0dafd2 --- /dev/null +++ b/docs/components/waitlist.mdx @@ -0,0 +1,235 @@ +--- +title: '`` component' +description: The component renders a waitlist form that allows users to join for early access to your application. +--- + +![The \ component renders a form that allows users to join for early access to your app.](/docs/images/ui-components/waitlist.png){{ style: { maxWidth: '460px' } }} + +In **Waitlist** mode, users can register their interest in your app by joining a waitlist. This mode is ideal for apps in early development stages or those wanting to generate interest before launch. [Learn more about additional features available in **Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist). + +The `` component renders a form that allows users to join for early access to your app. + +> [!NOTE] +> If you're using Next.js, the`` component is available in `@clerk/nextjs@6.2.0` and above. + +## Enable Waitlist mode + +Before using the `` component, you must enable **Waitlist** mode in the Clerk Dashboard: + +1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page. +1. Under the **Sign-up modes** section, enable **Waitlist**. + +## Properties + +All props are optional. + + + - `appearance` + - [Appearance](/docs/customization/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. + + --- + + - `afterJoinWaitlistUrl` + - `string` + + Full URL or path to navigate to after joining the waitlist. + + --- + + - `signInUrl` + - `string` + + Full URL or path to the sign in page. Use this property to provide the target of the 'Sign In' link that's rendered. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + +## Usage with frameworks + +> [!WARNING] +> Before using the `` component, you must provide the `waitlistUrl` prop either in the [``](/docs/components/clerk-provider#properties) or [``](/docs/components/authentication/sign-in#properties) component to ensure proper functionality. + +The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. + + + + ```jsx {{ filename: '/app/waitlist/[[...waitlist]]/page.tsx' }} + import { Waitlist } from '@clerk/nextjs' + + export default function WaitlistPage() { + return + } + ``` + + + + ```jsx {{ filename: '/waitlist.tsx' }} + import { Waitlist } from '@clerk/clerk-react' + + export default function WaitlistPage() { + return + } + ``` + + + +## Usage with JavaScript + +The following methods available on an instance of the [`Clerk`](/docs/references/javascript/clerk/clerk) class are used to render and control the `` component: + +- [`mountWaitlist()`](#mount-waitlist) +- [`unmountWaitlist()`](#unmount-waitlist) +- [`openWaitlist()`](#open-waitlist) +- [`closeWaitlist()`](#close-waitlist) + +The following examples assume that you followed the [quickstart](/docs/quickstarts/javascript) to add Clerk to your JavaScript app. + +### mountWaitlist() + +Render the `` component to an HTML `
` element. + +```typescript +function mountWaitlist(node: HTMLDivElement, props?: WaitlistProps): void +``` + +### mountWaitlist() params + + + - `node` + - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) + + The `
` element used to render in the `` component + + --- + + - `props?` + - [`WaitlistProps`](#properties) + + The properties to pass to the `` component + + +#### `mountWaitlist()` usage + +```js {{ filename: 'main.js', mark: [13] }} +import { Clerk } from '@clerk/clerk-js' + +// Initialize Clerk with your Clerk Publishable Key +const clerk = new Clerk('{{pub_key}}') +await clerk.load() + +document.getElementById('app').innerHTML = ` +
+` + +const waitlistDiv = document.getElementById('waitlist') + +clerk.mountWaitlist(waitlistDiv) +``` + +### unmountWaitlist() + +Unmount and run cleanup on an existing `` component instance. + +```typescript +function unmountWaitlist(node: HTMLDivElement): void +``` + +#### `unmountWaitlist()` params + + + - `node` + - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) + + The container `
` element with a rendered `` component instance + + +#### `unmountWaitlist()` usage + +```js {{ filename: 'main.js', mark: [17] }} +import { Clerk } from '@clerk/clerk-js' + +// Initialize Clerk with your Clerk Publishable Key +const clerk = new Clerk('{{pub_key}}') +await clerk.load() + +document.getElementById('app').innerHTML = ` +
+` + +const waitlistDiv = document.getElementById('waitlist') + +clerk.mountWaitlist(waitlistDiv) + +// ... + +clerk.unmountWaitlist(waitlistDiv) +``` + +### `openWaitlist()` + +Opens the `` component as an overlay at the root of your HTML `body` element. + +```typescript +function openWaitlist(props?: WaitlistProps): void +``` + +#### `openWaitlist()` params + + + - `props?` + - [`WaitlistProps`](#properties) + + The properties to pass to the `` component + + +#### `openWaitlist()` usage + +```js {{ filename: 'main.js', mark: [13] }} +import { Clerk } from '@clerk/clerk-js' + +// Initialize Clerk with your Clerk Publishable Key +const clerk = new Clerk('{{pub_key}}') +await clerk.load() + +document.getElementById('app').innerHTML = ` +
+` + +const waitlistDiv = document.getElementById('waitlist') + +clerk.openWaitlist(waitlistDiv) +``` + +### `closeWaitlist()` + +Closes the waitlist overlay. + +```typescript +function closeWaitlist(): void +``` + +#### `closeWaitlist()` usage + +```js {{ filename: 'main.js', mark: [17] }} +import { Clerk } from '@clerk/clerk-js' + +// Initialize Clerk with your Clerk Publishable Key +const clerk = new Clerk('{{pub_key}}') +await clerk.load() + +document.getElementById('app').innerHTML = ` +
+` + +const waitlistDiv = document.getElementById('waitlist') + +clerk.openWaitlist(waitlistDiv) + +// ... + +clerk.closeWaitlist(waitlistDiv) +``` + +## Customization + +To learn about how to customize Clerk components, see the [customization guide](/docs/customization/overview). diff --git a/docs/custom-flows/bot-sign-up-protection.mdx b/docs/custom-flows/bot-sign-up-protection.mdx index 28aa3b6209..20bf49b4cc 100644 --- a/docs/custom-flows/bot-sign-up-protection.mdx +++ b/docs/custom-flows/bot-sign-up-protection.mdx @@ -10,8 +10,7 @@ Clerk provides the ability to add a CAPTCHA widget to your sign-up flows to prot ### Enable bot sign-up protection - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/attack-protection). - 1. In the navigation sidebar, select **User & Authentication > Attack Protection**. + 1. In the Clerk Dashboard, navigate to the [**Attack protection**](https://dashboard.clerk.com/last-active?path=user-authentication/attack-protection) page. 1. In the **Bot sign-up protection** section, enable the feature and choose the **CAPTCHA type** you want to use. ### Add the CAPTCHA widget to your custom sign-up form diff --git a/docs/custom-flows/email-links.mdx b/docs/custom-flows/email-links.mdx index 56d5238fde..e57f654a0e 100644 --- a/docs/custom-flows/email-links.mdx +++ b/docs/custom-flows/email-links.mdx @@ -14,7 +14,7 @@ Email links are the default passwordless authentication strategy when using Cler Your users will still be able to choose an alternative authentication (or verification) method even after they've clicked the email link they received in their inbox. Email links are simply the default authentication method for email address-based, passwordless authentication in Clerk. > [!NOTE] -> Looking for one-time code (OTP) authentication? Check out our [one-time code authentication](/docs/custom-flows/email-sms-otp) guide. +> Looking for one-time code (OTP) authentication? See the [one-time code authentication guide](/docs/custom-flows/email-sms-otp). ## Email link flow @@ -37,12 +37,12 @@ We take care of the boring stuff, like efficient polling, secure session managem ## Before you start -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application](/docs/quickstarts/setup-clerk) guide. -- You need to install the correct SDK for your application. You can find steps on how to do so through the [quickstart guides.](/docs/quickstarts/overview) +- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out the [setup guide](/docs/quickstarts/setup-clerk). +- You need to install the correct SDK for your application. For more information, see the [quickstart guides](/docs/quickstarts/overview). ## Set up email link authentication in Your Clerk application -Email link authentication can be configured through the Clerk Dashboard. Go to **User & Authentication > [Email, Phone, and Username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username)**. In the **Authentication factors** section of this page, choose **Email verification link** as the authentication factor. +Email link authentication can be configured through the Clerk Dashboard. Go to **User & Authentication > [Email, phone, username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username)**. In the **Authentication factors** section of this page, choose **Email verification link** as the authentication factor. Don't forget that you also need to make sure you've configured your application instance to request the user's email address. Users can receive email links only via email messages. Make sure you toggle on **Email address** under the **Contact information** section. @@ -79,7 +79,7 @@ Let's see all the steps involved in more detail. Clerk provides a highly flexible API that allows you to hook into any of the above steps while abstracting away all the complexities of an email link-based sign-up flow. - + ```jsx import React from 'react' import { useRouter } from 'next/router' @@ -422,7 +422,7 @@ Let's see all the steps involved in more detail. Clerk provides a highly flexible API that allows you to hook into any of the above steps, while abstracting away all the complexities of an email link based sign-in flow. - + ```jsx import React from 'react' import { useRouter } from 'next/router' @@ -762,7 +762,7 @@ Email links can also provide a nice user experience for verifying email addresse Clerk provides a highly flexible API that allows you to hook into any of the above steps while abstracting away all the complexities of an email link-based email address verification. - + ```jsx import React from 'react' import { useUser, useEmailLink } from '@clerk/nextjs' diff --git a/docs/custom-flows/email-password-mfa.mdx b/docs/custom-flows/email-password-mfa.mdx index f62557fe21..35635ef407 100644 --- a/docs/custom-flows/email-password-mfa.mdx +++ b/docs/custom-flows/email-password-mfa.mdx @@ -18,8 +18,7 @@ This guide will walk you through how to build a custom email/password sign-in fl This example uses email and password authentication, however, you can modify this approach according to the needs of your application. To use email and password authentication, you first need to enable these authentication strategies in the Clerk Dashboard. - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username). - 1. In the navigation sidebar, select **User & Authentication > Email, Phone, and Username**. + 1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. Ensure that _only_ **Email address** is required. If **Phone number** and **Username** are enabled, ensure they are not required. Use the settings icon next to each user attribute to check if a setting is required or optional. If you want to require **Username**, you must collect the username and pass the data to the `create()` method in your custom flow. 1. In the **Authentication strategies** section of this page, ensure **Password** is enabled. @@ -27,8 +26,7 @@ This guide will walk you through how to build a custom email/password sign-in fl For your users to be able to enable MFA for their account, you need to enable MFA as an authentication strategy in your Clerk application. - 1. Navigate to your[Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor). - 1. In the navigation sidebar, select **User & Authentication > Multi-factor**. + 1. In the Clerk Dashboard, navigate to the [**Multi-factor**](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor) page. 1. For the purpose of this guide, toggle on both the **Authenticator application** and **Backup codes** strategies. ### Sign-in flow @@ -45,11 +43,11 @@ This guide will walk you through how to build a custom email/password sign-in fl 1. If the verification is successful, set the newly created session as the active session. > [!TIP] - > For this example to work, the user must have MFA enabled on their account. You need to add the ability for your users to manage their MFA settings. [Learn how to build a custom flow for managing multi-factor authentication.](/docs/custom-flows/email-password-mfa) + > For this example to work, the user must have MFA enabled on their account. You need to add the ability for your users to manage their MFA settings. See the [manage SMS-based MFA](/docs/custom-flows/manage-sms-based-mfa) or the [manage TOTP-based MFA](/docs/custom-flows/manage-totp-based-mfa) guide, depending on your needs. - + - ```tsx {{ filename: 'app/sign-in/[[...sign-in]].tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} 'use client' import * as React from 'react' diff --git a/docs/custom-flows/email-password.mdx b/docs/custom-flows/email-password.mdx index 2b751f5fac..8c916e2dd7 100644 --- a/docs/custom-flows/email-password.mdx +++ b/docs/custom-flows/email-password.mdx @@ -14,8 +14,7 @@ This guide will walk you through how to build a custom email/password sign-up an To use email and password authentication, you first need to enable these [authentication strategies](/docs/authentication/configuration/sign-up-sign-in-options#authentication-strategies) in the Clerk Dashboard. - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username). - 1. In the navigation sidebar, select **User & Authentication > Email, Phone, and Username**. + 1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. Ensure that _only_ **Email address** is required. If **Phone number** and **Username** are enabled, ensure they are not required. Use the settings icon next to each option to verify if a setting is required or optional. If you would like to require **Username**, you must collect the username and pass it to the `create()` method in your custom flow. 1. In the **Authentication strategies** section of this page, ensure **Password** is enabled. @@ -35,7 +34,7 @@ This guide will walk you through how to build a custom email/password sign-up an This example is written for Next.js App Router but it can be adapted for any React meta framework, such as Remix. - ```tsx {{ filename: '/app/sign-up/[[...sign-up]].tsx', collapsible: true }} + ```tsx {{ filename: '/app/sign-up/[[...sign-up]]/page.tsx', collapsible: true }} 'use client' import * as React from 'react' @@ -493,7 +492,7 @@ This guide will walk you through how to build a custom email/password sign-up an This example is written for Next.js App Router but it can be adapted for any React meta framework, such as Remix. - ```tsx {{ filename: '/app/sign-in/[[...sign-in]].tsx', collapsible: true }} + ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} 'use client' import * as React from 'react' diff --git a/docs/custom-flows/email-sms-otp.mdx b/docs/custom-flows/email-sms-otp.mdx index af644e1dcf..363d863d34 100644 --- a/docs/custom-flows/email-sms-otp.mdx +++ b/docs/custom-flows/email-sms-otp.mdx @@ -16,8 +16,7 @@ This guide will walk you through how to build a custom SMS OTP sign-up and sign- To use SMS OTP as an authentication strategy, you first need to enable it in the Clerk Dashboard. - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username). - 1. In the navigation sidebar, go to **User & Authentication > Email, Phone, Username**. + 1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. Ensure that _only_ **Phone number** is required. If **Email address** or **Username** are enabled, ensure they are not required. Use the settings icon to check if a setting is required or optional. If you would like to require **Username**, you must collect the username and pass it to the `create()` method in your custom flow. For this guide, if you would like to use email OTP instead, require the **Email address** option instead of the **Phone number** option. 1. In the **Authentication strategies** section of this page, ensure **SMS verification code** is enabled. Ensure **Password** is toggled off, as you are prioritizing passwordless, SMS OTP-only authentication in this guide. If you would like to use email OTP instead, enable the **Email verification code** strategy instead of the **SMS verification code** strategy. @@ -30,7 +29,7 @@ This guide will walk you through how to build a custom SMS OTP sign-up and sign- 1. Attempt to complete the verification with the code the user provides. 1. If the verification is successful, set the newly created session as the active session. - + This example is written for Next.js App Router but can be adapted to any React meta framework, such as Remix. @@ -316,7 +315,7 @@ This guide will walk you through how to build a custom SMS OTP sign-up and sign- 1. Attempt verification with the code the user provides. 1. If the attempt is successful, set the newly created session as the active session. - + This example is written for Next.js App Router but can be adapted to any React meta framework, such as Remix. diff --git a/docs/custom-flows/error-handling.mdx b/docs/custom-flows/error-handling.mdx index d402febe8b..93fff4fa07 100644 --- a/docs/custom-flows/error-handling.mdx +++ b/docs/custom-flows/error-handling.mdx @@ -223,14 +223,14 @@ The following example uses the [email & password sign-in custom flow](/docs/cust ### User locked -If you have [Account Lockout](/docs/security/user-lock-guide) enabled on your instance and the user reaches the maximum allowed attempts ([see list of relevant actions here](/docs/security/user-lock-guide#related-actions)), you will receive an HTTP status of `403 (Forbidden)` and the following error payload: +If you have [account lockout](/docs/security/user-lock-guide) enabled on your instance and the user reaches the maximum allowed attempts ([see list of relevant actions here](/docs/security/user-lock-guide#related-actions)), you will receive an HTTP status of `403 (Forbidden)` and the following error payload: ```json { "errors": [ { "message": "Account locked", - "long_message": "Your account is locked. You will be able to try again in 30 minutes. For more information, please contact support.", + "long_message": "Your account is locked. You will be able to try again in 30 minutes. For more information, contact support.", "code": "user_locked", "meta": { "lockout_expires_in_seconds": 1800 diff --git a/docs/custom-flows/forgot-password.mdx b/docs/custom-flows/forgot-password.mdx index 0e164a9fe4..3795f0b3cc 100644 --- a/docs/custom-flows/forgot-password.mdx +++ b/docs/custom-flows/forgot-password.mdx @@ -16,7 +16,7 @@ For the sake of this guide, this example is written for Next.js App Router but i {/* TODO: Add JavaScript example. */} - + ```tsx {{ filename: 'app/forgot-password.tsx', collapsible: true }} 'use client' import React, { useState } from 'react' @@ -113,7 +113,7 @@ For the sake of this guide, this example is written for Next.js App Router but i > {!successfulCreation && ( <> - + ### Enable Google as a social connection - To use Google One Tap with Clerk, follow the steps in [the dedicated guide](/docs/authentication/social-connections/google#configuring-google-social-connection) to configure Google as a social connection in the Clerk Dashboard using custom credentials. + To use Google One Tap with Clerk, follow the steps in the [dedicated guide](/docs/authentication/social-connections/google#configuring-google-social-connection) to configure Google as a social connection in the Clerk Dashboard using custom credentials. ### Create the Google One Tap authentication flow diff --git a/docs/custom-flows/manage-sms-based-mfa.mdx b/docs/custom-flows/manage-sms-based-mfa.mdx index a81e88b3f1..a3f45b5d15 100644 --- a/docs/custom-flows/manage-sms-based-mfa.mdx +++ b/docs/custom-flows/manage-sms-based-mfa.mdx @@ -17,8 +17,7 @@ One of the options that Clerk supports for MFA is **SMS verification codes**. Th For your users to be able to enable MFA for their account, you need to enable MFA as an MFA authentication strategy in your Clerk application. - 1. Navigate to the [Clerk Dashboard.](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor) - 1. In the navigation sidebar, select **User & Authentication > Multi-factor**. + 1. In the Clerk Dashboard, navigate to the [**Multi-factor**](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor) page. 1. Enable **SMS verification code** and **Backup codes** and select **Save**. ### Create the multi-factor management flow diff --git a/docs/custom-flows/manage-totp-based-mfa.mdx b/docs/custom-flows/manage-totp-based-mfa.mdx index eb61decdb8..5a08c5d936 100644 --- a/docs/custom-flows/manage-totp-based-mfa.mdx +++ b/docs/custom-flows/manage-totp-based-mfa.mdx @@ -17,8 +17,7 @@ One of the options that Clerk supports for MFA is **Authenticator applications ( For your users to be able to enable MFA for their account, you need to enable MFA as an MFA authentication strategy in your Clerk application. - 1. Navigate to the [Clerk Dashboard.](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor) - 1. In the navigation sidebar, select **User & Authentication > Multi-factor**. + 1. In the Clerk Dashboard, navigate to the [**Multi-factor**](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor) page. 1. Enable **Authenticator application** and **Backup codes** and select **Save**. ### Create the multi-factor management flow diff --git a/docs/custom-flows/multi-session-applications.mdx b/docs/custom-flows/multi-session-applications.mdx index 6498fa10f4..1653dcff07 100644 --- a/docs/custom-flows/multi-session-applications.mdx +++ b/docs/custom-flows/multi-session-applications.mdx @@ -20,14 +20,13 @@ To implement the multi-session feature to your application, you need to handle t To enable multi-session in your application, you need to configure it in the Clerk Dashboard. -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=sessions) and select your application. -1. In the navigation sidebar, select **Sessions**. +1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page. 1. Toggle on **Multi-session handling**. 1. Select **Save changes**. ## Get the active session and user - + ```jsx import { useClerk } from '@clerk/clerk-react' @@ -54,7 +53,7 @@ To enable multi-session in your application, you need to configure it in the Cle ## Switch between sessions - + ```jsx import { useClerk } from '@clerk/clerk-react' @@ -86,19 +85,19 @@ To enable multi-session in your application, you need to configure it in the Cle ## Add a new session -To add a new session, simply link to your existing sign-in flow. New sign-ins will automatically add to the list of available sessions on the client. To create a sign-in flow, please check one of the following popular guides: +To add a new session, simply link to your existing sign-in flow. New sign-ins will automatically add to the list of available sessions on the client. To create a sign-in flow, see one of the following popular guides: - [Email and password](/docs/custom-flows/email-password) - [Passwordless authentication](/docs/custom-flows/email-sms-otp) - [Social sign-in (OAuth)](/docs/authentication/social-connections/oauth) -For more information on how Clerk's sign-in flow works, check out the [detailed sign-in guide](/docs/custom-flows/overview#sign-in-flow). +For more information on how Clerk's sign-in flow works, see the [detailed sign-in guide](/docs/custom-flows/overview#sign-in-flow). ## Sign out all sessions Use [`signOut()`](/docs/references/javascript/clerk/clerk#sign-out) to deactivate all sessions on the current client. - + ```jsx import { useClerk } from '@clerk/clerk-react' @@ -123,7 +122,7 @@ Use [`signOut()`](/docs/references/javascript/clerk/clerk#sign-out) to deactivat Use [`signOut()`](/docs/references/javascript/clerk/clerk#sign-out) to deactivate a specific session by passing the session ID. - + ```jsx import { useClerk } from '@clerk/clerk-react' diff --git a/docs/custom-flows/overview.mdx b/docs/custom-flows/overview.mdx index f3b1162cb3..39b3e7e7f2 100644 --- a/docs/custom-flows/overview.mdx +++ b/docs/custom-flows/overview.mdx @@ -16,7 +16,7 @@ Before building custom authentication flows, read the following sections to get The [`SignUp`](/docs/references/javascript/sign-up/sign-up) object is the pivotal concept in the sign-up process. It is used to gather the user's information, verify their email address or phone number, add OAuth accounts, and finally, convert them into a [`User`](/docs/references/javascript/user/user). -Every `SignUp` has a set of requirements it must meet before it is turned into a `User`. These requirements are defined by the instance settings you selected in the [Clerk Dashboard](https://dashboard.clerk.com/). For example, on the [Email, Phone, Username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page, configuring passwords or email links or even both as the [authentication strategies](/docs/authentication/configuration/sign-up-sign-in-options#authentication-strategies). +Every `SignUp` must meet specific requirements before being converted into a `User`. These requirements are defined by the instance settings you selected in the [Clerk Dashboard](https://dashboard.clerk.com/). For example, on the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page, you can configure passwords, email links, or both as [authentication strategies](/docs/authentication/configuration/sign-up-sign-in-options#authentication-strategies). Once all requirements are met, the `SignUp` will turn into a new `User`, and an active session for that `User` will be created on the current [`Client`](/docs/references/javascript/client). diff --git a/docs/custom-flows/passkeys.mdx b/docs/custom-flows/passkeys.mdx index ed1ca8ddfb..7d5245eb54 100644 --- a/docs/custom-flows/passkeys.mdx +++ b/docs/custom-flows/passkeys.mdx @@ -13,8 +13,7 @@ This guide will walk you through how to use the Clerk API to build custom flows To use passkeys, first enable the strategy in the Clerk Dashboard. -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username). -1. In the navigation sidebar, select **User & Authentication > Email, Phone, and Username**. +1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. In the **Authentication strategies** section of this page, ensure **Passkeys** is enabled. ## Create user passkeys diff --git a/docs/custom-flows/saml-connections.mdx b/docs/custom-flows/saml-connections.mdx index b1386039de..e062065c88 100644 --- a/docs/custom-flows/saml-connections.mdx +++ b/docs/custom-flows/saml-connections.mdx @@ -7,7 +7,7 @@ description: Learn how to use the Clerk API to build a custom sign-up and sign-i ## Before you start -You must configure your application instance through the Clerk Dashboard for the SAML connection(s) that you want to use. Visit [the appropriate SAML guide for your platform](/docs/authentication/saml/overview) to learn how to configure your instance. +You must configure your application instance through the Clerk Dashboard for the SAML connection(s) that you want to use. Visit [the appropriate SAML guide for your platform](/docs/authentication/enterprise-connections/overview) to learn how to configure your instance. ## Create the sign-up and sign-in flow diff --git a/docs/custom-flows/user-impersonation.mdx b/docs/custom-flows/user-impersonation.mdx index 27ca2f9e22..f314b944b7 100644 --- a/docs/custom-flows/user-impersonation.mdx +++ b/docs/custom-flows/user-impersonation.mdx @@ -34,8 +34,10 @@ This guide will walk you through how to build a custom flow that handles user im return

You do not have permission to access this page.

} + const client = await clerkClient() + // Fetch list of application's users using Clerk's Backend SDK - const users = await clerkClient.users.getUserList() + const users = await client.users.getUserList() // This page needs to be a server component to use clerkClient.users.getUserList() // You must pass the list of users to the client for the rest of the logic @@ -345,7 +347,7 @@ This guide will walk you through how to build a custom flow that handles user im ### Create an API route to generate actor tokens - Now create an endpoint that will call the [create actor token](/docs/reference/backend-api/tag/Actor-Tokens#operation/CreateActorToken) endpoint at `/actor_tokens` and pass in the Clerk secret key for authorization. In your API, you should build in permission checks to make sure this is only being accessed from a trusted source. + Now create an endpoint that will call the [create actor token](/docs/reference/backend-api/tag/Actor-Tokens#operation/CreateActorToken) endpoint at `/actor_tokens` and pass in the Clerk Secret Key for authorization. In your API, you should build in permission checks to make sure this is only being accessed from a trusted source. ```tsx {{ filename: 'app/generateActorToken+api.tsx' }} export async function POST(request: Request) { diff --git a/docs/customization/account-portal/disable-account-portal.mdx b/docs/customization/account-portal/disable-account-portal.mdx index 31cae60539..697947d042 100644 --- a/docs/customization/account-portal/disable-account-portal.mdx +++ b/docs/customization/account-portal/disable-account-portal.mdx @@ -8,10 +8,9 @@ description: Learn how to disable the Account Portal. To disable the Account Portal: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=account-portal). -1. In the navigation sidebar, select **Account Portal**. +1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. 1. Select the **Danger** tab. -1. Select **Disable account portal**. You will not be able to select this button until you have [set up an authentication flow for your users](#customizing-your-sign-upsign-in-flow), as applying this setting will immediately result in a 404 for all Account Portal pages. +1. Select **Disable Account Portal**. You will not be able to select this button until you have [set up an authentication flow for your users](#customizing-your-sign-upsign-in-flow), as applying this setting will immediately result in a 404 for all Account Portal pages. ## Customizing your sign-up/sign-in flow diff --git a/docs/customization/account-portal/getting-started.mdx b/docs/customization/account-portal/getting-started.mdx index c7fd25e7b9..7a657908ec 100644 --- a/docs/customization/account-portal/getting-started.mdx +++ b/docs/customization/account-portal/getting-started.mdx @@ -24,4 +24,4 @@ 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. +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/customization/account-portal/overview.mdx b/docs/customization/account-portal/overview.mdx index 7b5b6174f0..79fee3b8d6 100644 --- a/docs/customization/account-portal/overview.mdx +++ b/docs/customization/account-portal/overview.mdx @@ -1,9 +1,9 @@ --- -title: Account portal overview +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, check out the [setup guide](/docs/customization/account-portal/getting-started).** +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/customization/account-portal/getting-started).** ![Account Portal](/docs/images/account-portal/account_portal_splash.png) @@ -21,7 +21,7 @@ The Account Portal uses Clerk's [prebuilt components](/docs/components/overview) 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, check out the [setup guide](/docs/customization/account-portal/getting-started).** +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/customization/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). @@ -30,7 +30,7 @@ For each application environment, Clerk provides pages for sign-up, sign-in, use ### 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 your [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/overview). +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/overview). ![The Account Portal sign-in page hosts the \ component](/docs/images/account-portal/sign-in.png) @@ -38,7 +38,7 @@ Redirect users to the sign-in page using the [``](/docs/comp ### 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 your [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/overview). +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/overview). ![The Account Portal sign-up page hosts the \ component](/docs/images/account-portal/sign-up.png) @@ -67,3 +67,9 @@ The user profile page hosts the prebuilt [``](/docs/compo ![The Account Portal organization profile page hosts the \ component](/docs/images/account-portal/org-profile.png) 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. + +![The Account Portal waitliste page hosts the \ component](/docs/images/account-portal/waitlist.png) diff --git a/docs/customization/elements/examples/shadcn-ui.mdx b/docs/customization/elements/examples/shadcn-ui.mdx index c722d159c7..33b2a88753 100644 --- a/docs/customization/elements/examples/shadcn-ui.mdx +++ b/docs/customization/elements/examples/shadcn-ui.mdx @@ -37,7 +37,7 @@ To use these examples, you must first: You must also configure the appropriate settings in Clerk: -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Ensure that **Google** and **GitHub** are enabled. If they are not in the list of connections, select the **Add connection** button, and select **For all users**. Enable **Google** and **GitHub**. ## Sign up diff --git a/docs/customization/elements/examples/sign-in.mdx b/docs/customization/elements/examples/sign-in.mdx index 4068760e92..0180ae75a2 100644 --- a/docs/customization/elements/examples/sign-in.mdx +++ b/docs/customization/elements/examples/sign-in.mdx @@ -9,7 +9,7 @@ The following example demonstrates a simple username/password sign-in flow. Before you build your sign-in flow, you need to configure the appropriate settings in Clerk: -1. In the Clerk Dashboard, navigate to the [**Email, Phone, Username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. +1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. In the **Contact information** section, ensure that _only_ **Password** is enabled. 1. In the **Username** section, ensure that **Username** is enabled. @@ -110,9 +110,9 @@ The following example demonstrates a simple Google OAuth sign-in flow. Before you build your sign-in flow, you need to configure the appropriate settings in Clerk: -1. In the Clerk Dashboard, navigate to the [**Email, Phone, Username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. +1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. Ensure that all settings are disabled. -1. In the navigation sidebar, select [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). +1. In the navigation sidebar, select [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). 1. Ensure that _only_ **Google** is enabled. `](/docs/customization/elements/reference/common#loading) and [``](/docs/customization/elements/reference/common#fieldstate). + For more extensive customization of the UI, see the additional Clerk Elements components such as [``](/docs/customization/elements/reference/common#loading) and [``](/docs/customization/elements/reference/common#fieldstate). diff --git a/docs/customization/elements/guides/sign-up.mdx b/docs/customization/elements/guides/sign-up.mdx index 914bd40dd0..5aed014cf7 100644 --- a/docs/customization/elements/guides/sign-up.mdx +++ b/docs/customization/elements/guides/sign-up.mdx @@ -285,5 +285,5 @@ description: Learn how to build a complete sign-up form with Clerk Elements. Learn how to style your Clerk Elements components with the [styling guide](/docs/customization/elements/guides/styling). - For more extensive customization of the UI, check out additional Clerk Elements components such as [``](/docs/customization/elements/reference/common#loading) and [``](/docs/customization/elements/reference/common#fieldstate). + For more extensive customization of the UI, see the additional Clerk Elements components such as [``](/docs/customization/elements/reference/common#loading) and [``](/docs/customization/elements/reference/common#fieldstate). diff --git a/docs/customization/elements/overview.mdx b/docs/customization/elements/overview.mdx index 71fb54cccc..b571fe7ad4 100644 --- a/docs/customization/elements/overview.mdx +++ b/docs/customization/elements/overview.mdx @@ -6,7 +6,7 @@ description: Learn how to use Clerk Elements to build custom UIs on top of the C > [!WARNING] > Clerk Elements is currently in beta with support for Next.js App Router. It is **not yet recommended for production use**. > -> If you have any feedback, please reach out to [beta-elements@clerk.dev](mailto:beta-elements@clerk.dev) or head over to the [GitHub Discussion](https://github.com/orgs/clerk/discussions/3315). +> If you have any feedback, contact [beta-elements@clerk.dev](mailto:beta-elements@clerk.dev) or head over to the [GitHub Discussion](https://github.com/orgs/clerk/discussions/3315). Clerk Elements is a library of unstyled, composable components that can be used to build custom UIs on top of the Clerk APIs without having to manage the underlying logic. diff --git a/docs/customization/layout.mdx b/docs/customization/layout.mdx index e922a288bd..f98ec7b4fb 100644 --- a/docs/customization/layout.mdx +++ b/docs/customization/layout.mdx @@ -34,7 +34,7 @@ The `layout` property can be used to change the layout of the [``](/doc - `logoLinkUrl` - `string` - Controls where the browser will redirect to after the user clicks the application logo. If a URL is provided, it will be used as the `href` of the link. If a value is not passed in, the components will use the Home URL as set in the Clerk dashboard. Defaults to `undefined`. + Controls where the browser will redirect to after the user clicks the application logo. If a URL is provided, it will be used as the `href` of the link. If a value is not passed in, the components will use the Home URL as set in the Clerk Dashboard. Defaults to `undefined`. --- diff --git a/docs/customization/localization.mdx b/docs/customization/localization.mdx index 261c04b9bb..3b51ede253 100644 --- a/docs/customization/localization.mdx +++ b/docs/customization/localization.mdx @@ -4,7 +4,7 @@ description: Use the Clerk localizations package to override and provide predefi --- > [!WARNING] -> This feature is currently experimental and may not behave as expected. If you encounter any issues, please reach out to [support](/contact/support){{ target: '_blank' }} with as much detail as possible. +> This feature is currently experimental and may not behave as expected. If you encounter any issues, [contact support](/contact/support){{ target: '_blank' }} with as much detail as possible. Clerk offers the ability to override the strings for all of the elements in each of the Clerk components. This allows you to provide localization for your users or change the wording to suit your brand. diff --git a/docs/customization/organization-profile.mdx b/docs/customization/organization-profile.mdx index bbc6216f84..2c9576c876 100644 --- a/docs/customization/organization-profile.mdx +++ b/docs/customization/organization-profile.mdx @@ -64,7 +64,7 @@ To add a custom page to the `` component, use the `` or `` component: as a component or as a direct child. -", "Dedicated page"]}> +", "Dedicated page"]}> ```tsx {{ filename: '/app/components/Header.tsx' }} 'use client' @@ -246,7 +246,7 @@ You can add external links to the `` navigation sidebar u The following example adds a link to the homepage in the navigation sidebar of the `` component. -", "Dedicated page"]}> +", "Dedicated page"]}> ```tsx {{ filename: '/app/components/Header.tsx' }} 'use client' @@ -304,7 +304,7 @@ If you want to reorder the default routes, `Members` and `General`, set the `lab Note that when reordering default routes, the first item in the navigation sidebar cannot be a `` or `` component. -", "Dedicated Page"]}> +", "Dedicated Page"]}> ```tsx {{ filename: '/app/components/Header.tsx' }} 'use client' diff --git a/docs/customization/user-button.mdx b/docs/customization/user-button.mdx index 63c924494c..943248d0f3 100644 --- a/docs/customization/user-button.mdx +++ b/docs/customization/user-button.mdx @@ -146,7 +146,7 @@ The following example demonstrates how to add an action to the `` ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' - // Initialize Clerk with your Clerk publishable key + // Initialize Clerk with your Clerk Publishable Key const clerk = new Clerk('{{pub_key}}') await clerk.load() @@ -215,7 +215,7 @@ The following example demonstrates how to add an action, as well as a [custom pa In the following example, the `` component is used to add a "Help" menu item to the `` component. The `open` prop is set to `"help"` to open the `/help` page when the menu item is selected. - The `` component is used to render the `/help` page, and because its configured as a user profile page, the `` modal will be opened with the custom "Help" menu item. [Read more about custom pages.](/docs/customization/user-profile) + The `` component is used to render the `/help` page, and because its configured as a user profile page, the `` modal will be opened with the custom "Help" menu item. [Read more about custom pages](/docs/customization/user-profile). ```astro filename="pages/index.astro" --- @@ -356,7 +356,7 @@ The following example demonstrates how to add a link to the `` com ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' - // Initialize Clerk with your Clerk publishable key + // Initialize Clerk with your Clerk Publishable Key const clerk = new Clerk('{{pub_key}}') await clerk.load() diff --git a/docs/deployments/changing-domains.mdx b/docs/deployments/changing-domains.mdx index bb053f2afa..3ce166b22d 100644 --- a/docs/deployments/changing-domains.mdx +++ b/docs/deployments/changing-domains.mdx @@ -16,9 +16,9 @@ Learn how to change your Clerk production instance's domain or subdomain. 1. Once you make the change to your domain, you will need to update the following: - Update DNS records - Generate new SSL certificates - - [Update your publishable key](#updating-your-publishable-key) + - [Update your Publishable Key](#updating-your-publishable-key) - If using social connections, update the settings with your social connections so that the redirect URL they are using is correct. - - If using JWT templates, update JWT issuer and JWKS endpoint in external JWT SSO services. + - If using JWT templates, update JWT issuer and JWKS Endpoint in external JWT SSO services. ### Update your domain via Clerk Dashboard @@ -28,21 +28,21 @@ To update your production domain in the Clerk Dashboard: 1. Select the **Danger** tab. 1. Select **Change domain**. -### Update your domain via backend API +### Update your domain via Backend API -To update your production domain using the [Backend API](https://clerk.com/docs/reference/backend-api), you will need to make a POST request to the `change_domain` endpoint. You will need to provide your new domain in the request body. +To update your production domain using the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, you will need to make a POST request to the `change_domain` endpoint. You will need to provide your new domain in the request body. 1. Copy the following cURL command. - 2) Your secret key is required to authenticate the request. It is injected into the cURL command after `Authorization`. However, you can also find it on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page of the Clerk Dashboard. + 2) Your Secret Key is required to authenticate the request. It is injected into the cURL command after `Authorization`. However, you can also find it on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. - 2. Your secret key is required to authenticate the request. + 2. Your Secret Key is required to authenticate the request. - Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys) and sign in. - - In the navigation sidebar, select **API Keys** to copy your secret key. - - Paste your secret key into the cURL command after `Authorization`, replacing `sk_...`. + - In the navigation sidebar, select **API keys** to copy your Secret Key. + - Paste your Secret Key into the cURL command after `Authorization`, replacing `sk_...`. 3. Replace `YOUR_PROD_URL` with your new production domain. @@ -53,14 +53,14 @@ curl -XPOST -H 'Authorization: {{secret}}' -H "Content-type: application/json" - }' 'https://api.clerk.com/v1/instance/change_domain' ``` -For more information on how to update your instance settings using the backend API, see our [backend API reference](/docs/reference/backend-api/tag/Beta-Features#operation/UpdateInstanceAuthConfig){{ target: '_blank' }}. +For more information on how to update your instance settings using the Backend API, see the [Backend API reference](/docs/reference/backend-api/tag/Beta-Features#operation/UpdateInstanceAuthConfig){{ target: '_blank' }}. -### Update your publishable key +### Update your Publishable Key -After changing your domain, a new **Publishable key** will be automatically generated for your application. You will need to update your environment variables with this new key and redeploy your application. You can find your **Publishable key** on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page of the Clerk Dashboard. +After changing your domain, a new **Publishable Key** will be automatically generated for your application. You need to update your environment variables with this new key and redeploy your application. You can find your **Publishable Key** on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. > [!NOTE] -> Failing to update your **Publishable key** will result in Clerk failing to load. +> Failing to update your **Publishable Key** will result in Clerk failing to load. ## Set, change, or remove subdomain diff --git a/docs/deployments/clerk-cookies.mdx b/docs/deployments/clerk-cookies.mdx index d9cc9dd459..828b45b9bb 100644 --- a/docs/deployments/clerk-cookies.mdx +++ b/docs/deployments/clerk-cookies.mdx @@ -1,6 +1,6 @@ --- title: Clerk Cookies -description: +description: --- ## Strictly Necessary Application Cookies @@ -11,7 +11,7 @@ These cookies: - Are required for Clerk to function, and should not be blocked by you or your users. - Do not store any personally identifiable information by default. -- Can be configured by modifying the [session token](/docs/backend-requests/resources/session-tokens) in your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). +- Can be configured by modifying the [session token](/docs/backend-requests/resources/session-tokens) in the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). | Cookie Subgroup | Cookies | More Information | | - | - | - | diff --git a/docs/deployments/clerk-environment-variables.mdx b/docs/deployments/clerk-environment-variables.mdx index 348fcd9eba..99cac33ded 100644 --- a/docs/deployments/clerk-environment-variables.mdx +++ b/docs/deployments/clerk-environment-variables.mdx @@ -19,7 +19,7 @@ Components, such as [``](/docs/components/clerk-provider), [` + | Variable | Description | | - | - | @@ -43,25 +43,25 @@ However, it's recommended to use environment variables instead of these props wh -## Clerk publishable and secret keys +## Clerk Publishable and Secret Keys -To access your Clerk app in your local project, you must specify your app's publishable keys for use in the frontend, and secret keys for use in the backend. +To access your Clerk app in your local project, you must specify your app's Publishable Keys for use in the frontend, and Secret Keys for use in the backend. -You can find these keys in the Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. +You can find these keys on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. - + | Variable | Description | | - | - | - | `CLERK_PUBLISHABLE_KEY` | Your Clerk app's publishable key. It will be prefixed with `pk_test_` in development instances and `pk_live_` in production instances. | - | `CLERK_SECRET_KEY` | Your Clerk app's secret key, which you can find in the Clerk dashboard. It will be prefixed with `sk_test_` in development instances and `sk_live_` in production instances. **Do not expose this on the frontend with a public environment variable**. | + | `CLERK_PUBLISHABLE_KEY` | Your Clerk app's Publishable Key. It will be prefixed with `pk_test_` in development instances and `pk_live_` in production instances. | + | `CLERK_SECRET_KEY` | Your Clerk app's Secret Key, which you can find in the Clerk Dashboard. It will be prefixed with `sk_test_` in development instances and `sk_live_` in production instances. **Do not expose this on the frontend with a public environment variable**. | | Variable | Description | | - | - | - | `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Your Clerk app's publishable key, which you can find in the Clerk dashboard. It will be prefixed with `pk_test_` in development instances and `pk_live_` in production instances. | - | `CLERK_SECRET_KEY` | Your Clerk app's secret key, which you can find in the Clerk dashboard. It will be prefixed with `sk_test_` in development instances and `sk_live_` in production instances. **Do not expose this on the frontend with a public environment variable**. | + | `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Your Clerk app's Publishable Key, which you can find in the Clerk Dashboard. It will be prefixed with `pk_test_` in development instances and `pk_live_` in production instances. | + | `CLERK_SECRET_KEY` | Your Clerk app's Secret Key, which you can find in the Clerk Dashboard. It will be prefixed with `sk_test_` in development instances and `sk_live_` in production instances. **Do not expose this on the frontend with a public environment variable**. | @@ -69,7 +69,7 @@ You can find these keys in the Clerk Dashboard on the [API Keys](https://dashboa The following environment variables enable you to configure API and SDK behavior, such as what version of the SDK your project uses, what proxy URL you use to connect to Clerk's Frontend API, and more. - + | Variable | Description | | - | - | @@ -100,7 +100,7 @@ The following environment variables enable you to configure API and SDK behavior Clerk supports sharing sessions across different domains by adding one or many satellite domains to an application. See [the satellite domains guide](/docs/advanced-usage/satellite-domains) for more information. - + | Variable | Description | | - | - | @@ -120,7 +120,7 @@ Clerk supports sharing sessions across different domains by adding one or many s Clerk provides environment variables for opting out of telemetry data collection. See [the telemetry documentation](/docs/telemetry) for more information. - + | Variable | Description | | - | - | @@ -140,7 +140,7 @@ Clerk provides environment variables for opting out of telemetry data collection The following environment variables are deprecated but still supported to avoid breaking changes. Don't use them in new projects. It is recommended to switch to using the recommended alternatives in old projects. - + | Variable | Description | | - | - | diff --git a/docs/deployments/deploy-astro.mdx b/docs/deployments/deploy-astro.mdx index 3e2fda6aa6..227a204bb9 100644 --- a/docs/deployments/deploy-astro.mdx +++ b/docs/deployments/deploy-astro.mdx @@ -4,7 +4,7 @@ description: Learn how to deploy an Astro app to production with Clerk. --- > [!WARNING] -> This guide assumes that you have already installed Clerk in your application locally and are ready to deploy. If you haven't installed Clerk yet, see [the quickstart guide.](/docs/quickstarts/astro) +> This guide assumes that you have already installed Clerk in your application locally and are ready to deploy. If you haven't installed Clerk yet, see [the quickstart guide](/docs/quickstarts/astro). This guide will walk you through the steps to deploy your Astro app to production. @@ -18,7 +18,7 @@ To deploy to a hosting platform, it's recommended to choose one of the [official ### Netlify -Due to Netlify's caching strategies, one of Clerk's core mechanisms is unable to work as expected, resulting in infinite redirects that cause an app to fail. This also affects preview environments that use **development** API keys. It's recommended to use [production API keys with a new domain.](/docs/deployments/set-up-preview-environment#acquire-an-additional-root-domain) +Due to Netlify's caching strategies, one of Clerk's core mechanisms is unable to work as expected, resulting in infinite redirects that cause an app to fail. This also affects preview environments that use **development** API keys. It's recommended to use [production API keys with a new domain](/docs/deployments/set-up-preview-environment#acquire-an-additional-root-domain). Additionally, read [this section](#issues-with-edge-middleware) about **Edge middleware**. diff --git a/docs/deployments/deploy-chrome-extension.mdx b/docs/deployments/deploy-chrome-extension.mdx new file mode 100644 index 0000000000..33ada0d783 --- /dev/null +++ b/docs/deployments/deploy-chrome-extension.mdx @@ -0,0 +1,86 @@ +--- +title: Deploy a Chrome Extension to production +description: Learn how to deploy a Chrome Extension to production with Clerk. +--- + +> [!WARNING] +> This guide assumes you are using the Plasmo framework. If you need help applying these concepts to another framework, [contact support](https://clerk.com/contact/support). + +## Create a production instance + +For Clerk production instances, there must be a domain associated with the instance. Even though there may not be a web application associated with your Chrome Extension, a domain is still required. Follow the [guide on deploying your Clerk app to production](/docs/deployments/overview). + +## Update your `.env.production` file + + + Add your Publishable and Frontend API keys for your Clerk production instance to your `.env.production` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. If you're using [the Sync Host feature](/docs/references/chrome-extension/sync-host), you also need to set the `PLASMO_PUBLIC_CLERK_SYNC_HOST` environment variable. The value is the domain your web app's production server runs on. For example, `https://clerk.com`. + + + + 1. At the top in the Clerk Dashboard, in the instance selection dropdown, ensure that your production instance is selected. + 1. In the navigation sidebar, select [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys). + 1. In the **Quick Copy** section, select **Chrome Extension** and copy your Clerk Publishable and Frontend API keys. + 1. Paste your keys into your `.env.production` file. + 1. If you are using [the Sync Host feature](/docs/references/chrome-extension/sync-host), you will also need to set the `PLASMO_PUBLIC_CLERK_SYNC_HOST` environment variable. The value should be the domain your web app's production server runs on. For example, `https://clerk.com`. + + The final result should resemble the following: + + +```env {{ filename: '.env.production' }} +PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} +CLERK_FRONTEND_API={{fapi_url}} +PLASMO_PUBLIC_CLERK_SYNC_HOST=https://yourdomain.com +``` + +## Add production domain to `host_permissions` + +`host_permissions` specifies which hosts, or websites, will have permission to sync auth state with your app. It accepts an array, allowing you to add more than one host. You must add your production domain to the `host_permissions` array. + +> [!WARNING] +> If you are using the Sync Host feature and followed [the configuration guide](/docs/references/chrome-extension/sync-host), then you have already completed this step (the `http://$PLASMO_PUBLIC_CLERK_SYNC_HOST/*` value points to your production domain.) + +In the `package.json` file, in the `manifest` object, update the `host_permissions` array. Add your domain and ensure it is preceded with `https://`. For example, `https://clerk.com`. Only add the root domain and not any subdomains. Then, add `/*` to the end of the domain. + +The following example shows how to configure `host_permissions` for production: + +```json {{ filename: 'package.json', mark: [6] }} +{ + // The rest of your package.json file + "manifest": { + "key": "$CRX_PUBLIC_KEY", + "permissions": ["cookies", "storage"], + "host_permissions": ["https:///*", "$CLERK_FRONTEND_API/*"] + } +} +``` + +## Add the Extension's ID to your web app's `allowed_origins` + +> [!WARNING] +> You may have already added the Extension ID to your web app's `allowed_origins` using your **development** Secret Key. You must repeat this step using your **production** Secret Key. + + + In your terminal, paste the following command and replace the `` with your extension's ID. + + + + 1. At the top in the Clerk Dashboard, in the instance selection dropdown, ensure that your production instance is selected. + 1. In the navigation sidebar, select [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys). + 1. Copy your Secret Key. It should begin with `sk_live_`. + 1. In your terminal, paste the following command. Replace `YOUR_SECRET_KEY` with your Clerk Secret Key and the `` with your extension's ID. + + The final result should resemble the following: + + +```bash {{ filename: 'terminal' }} +curl -X PATCH https://api.clerk.com/v1/instance \ + -H "Authorization: Bearer {{secret}}" \ + -H "Content-type: application/json" \ + -d '{"allowed_origins": ["chrome-extension://"]}' +``` + +## Submit your extension for review + +1. In your app, create a new zip of the `build/chrome-mv3-dev` folder. +1. In the top-right of the [Chrome Web Store Developer Dashboard](https://chrome.google.com/webstore/developer/dashboard), select **Upload new package** and upload the zip file. +1. Complete the required information to submit your extension for review. To check the requirements that must be met before submitting, select **Why can't I submit?**. diff --git a/docs/deployments/deploy-expo.mdx b/docs/deployments/deploy-expo.mdx index 59b5571fdf..ee491a2e96 100644 --- a/docs/deployments/deploy-expo.mdx +++ b/docs/deployments/deploy-expo.mdx @@ -17,7 +17,7 @@ Clerk ensures that security critical nonces will be passed only to allowlisted U So for maximum security in your production instances, you need to allowlist your custom redirect URLs: -1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Scroll to the **Allowlist for mobile OAuth redirect** section and add your redirect URLs. 1. The default is `://oauth-native-callback` 1. If you'd like to pass a custom redirect URL, make sure you add that to the allowlist. The format is `/{PATH}`. For example, the redirect URL for the following code example is `myapp://dashboard`. @@ -34,7 +34,7 @@ So for maximum security in your production instances, you need to allowlist your ``` > [!TIP] -> You can also add redirect URLs via [the Backend API](/docs/reference/backend-api/tag/Redirect-URLs#operation/CreateRedirectURL). +> You can also add redirect URLs via [the Backend API](/docs/reference/backend-api/tag/Redirect-URLs#operation/CreateRedirectURL){{ target: '_blank' }}. ## Deploy to production diff --git a/docs/deployments/deploy-to-vercel.mdx b/docs/deployments/deploy-to-vercel.mdx index 9e5399fdf4..305d72b903 100644 --- a/docs/deployments/deploy-to-vercel.mdx +++ b/docs/deployments/deploy-to-vercel.mdx @@ -4,7 +4,7 @@ description: Learn how to deploy a Clerk app to Vercel. --- > [!WARNING] -> This guide assumes that you have already installed Clerk in your application locally and are ready to deploy. If you haven't installed Clerk yet, please see our [guide to installing Clerk in your application](/docs/quickstarts/setup-clerk) first. +> This guide assumes that you have already installed Clerk in your application locally and are ready to deploy. If you haven't installed Clerk yet, see the [setup guide](/docs/quickstarts/setup-clerk). If you haven't set up your application in Vercel yet, [set up a new Vercel project](#set-up-a-new-vercel-project). @@ -15,7 +15,7 @@ If you already have a Vercel project for your application and need to integrate 1. To set up a new Vercel project, start by going to your [Vercel Dashboard](https://vercel.com/dashboard). Here, you'll see a list of your projects or, if you don't have any projects yet, a prompt to create a new project. 1. Create a new project by pressing the **Add New** button in the top right corner of the screen or by [pressing this link](https://vercel.com/new). You'll be redirected to a page where you can import a Git repository. 1. Find the Git repository you want to use and press **Import**. You'll be redirected to the **Configure Project** page. -1. Fill out the necessary information. And most importantly, ensure to add your Clerk API keys to the **[Environment Variables](https://vercel.com/docs/concepts/projects/environment-variables)**. You can find your Clerk API keys by navigating to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys) and in the navigation sidebar, selecting **API Keys**. +1. Fill out the necessary information. And most importantly, ensure to add your Clerk API keys to the **[Environment Variables](https://vercel.com/docs/concepts/projects/environment-variables)**. You can find your Clerk API keys by navigating to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. > [!WARNING] > If you would like to deploy to production, you will need to add your **production** API keys to your Vercel project. Refer to the [Deploy to production](/docs/deployments/overview) guide for more information. @@ -24,7 +24,7 @@ If you already have a Vercel project for your application and need to integrate 1. To add your Clerk API keys to an existing Vercel project, start by selecting your project from your [Vercel dashboard](https://vercel.com/dashboard). 1. Select **Settings** in the navigation bar at the top. -1. In the sidebar, select **Environment Variables** and add your Clerk API keys. You can find your Clerk API keys by navigating to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys) and in the navigation sidebar, selecting **API Keys**. +1. In the sidebar, select **Environment Variables** and add your Clerk API keys. You can find your Clerk API keys by navigating to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. 1. When adding **Environment Variables**, you can select which keys associate with which Vercel deployment environments. Using this, you can have your production Vercel environment use your production Clerk API keys while having your preview and development Vercel deployments use your development Clerk API keys. > [!WARNING] @@ -32,7 +32,7 @@ If you already have a Vercel project for your application and need to integrate ## Vercel preview environment -To configure Clerk within your Vercel preview environment, please see our guide for [configuring a preview environment](/docs/deployments/set-up-preview-environment). +To configure Clerk within your Vercel preview environment, see the [guide for configuring a preview environment](/docs/deployments/set-up-preview-environment). ## Deploy to production diff --git a/docs/deployments/environments.mdx b/docs/deployments/environments.mdx index d7f6a9297f..f475466785 100644 --- a/docs/deployments/environments.mdx +++ b/docs/deployments/environments.mdx @@ -36,7 +36,7 @@ When deploying to production, you must first activate your `Production` environm ## 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. [Learn more.](/docs/deployments/set-up-staging) +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 diff --git a/docs/deployments/migrate-from-cognito.mdx b/docs/deployments/migrate-from-cognito.mdx index b722269e82..23e5b6ef67 100644 --- a/docs/deployments/migrate-from-cognito.mdx +++ b/docs/deployments/migrate-from-cognito.mdx @@ -11,8 +11,8 @@ This necessitates a password reset flow when migrating users to another platform To eliminate the need for a cumbersome password reset flow, Clerk provides a Cognito password migrator that enables your end users to sign in to Clerk using their existing Cognito passwords. -In its barest form, it is simply two fields that you set on a Clerk `user` object, through -the [backend API](/docs/reference/backend-api/tag/Users#operation/CreateUser). +In its barest form, it is simply two fields that you set on a Clerk `user` object through +the [Backend API](/docs/reference/backend-api/tag/Users#operation/CreateUser){{ target: '_blank' }}. - `password_hasher`: `awscognito` - `password_digest`: `awscognito###` @@ -75,7 +75,7 @@ The provided script below lists your Cognito user pool users, calls [^1]: [`CreateUser`](/docs/reference/backend-api/tag/Users#operation/CreateUser){{ target: '_blank' }} has a rate limit rule of 20 requests per 10 seconds. ```ts {{ title: '~/cognito_to_clerk/main.ts' }} -import { createClerkClient } from '@clerk/backend@' +import { createClerkClient } from '@clerk/backend' import * as IDP from '@aws-sdk/client-cognito-identity-provider' // NOTE: The IAM user should have permissions roughly equivalent to AmazonCognitoReadOnly. @@ -194,7 +194,7 @@ you will be able to validate the migration behavior. If the password is correct, sign in should work seamlessly. > [!TIP] - > If at any point you need to _reset_, you can delete the user via the Clerk dashboard, and restart the process. + > If at any point you need to _reset_, you can delete the user via the Clerk Dashboard, and restart the process. > > This validation may be performed on both your `development` and `production` instances. diff --git a/docs/deployments/migrate-overview.mdx b/docs/deployments/migrate-overview.mdx index b5dbe59558..2e34ef1b3b 100644 --- a/docs/deployments/migrate-overview.mdx +++ b/docs/deployments/migrate-overview.mdx @@ -12,9 +12,9 @@ Each of these have trade-offs you'll need to consider on behalf of for your appl ## Basic export / import -With basic export / import, you are 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#operation/CreateUser){{ target: '_blank' }} Backend API endpoint. It's important to note that the `CreateUser` endpoint is rate limited. Please review our [Rate Limits](/docs/backend-requests/resources/rate-limits#backend-api-requests) page for more details. +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#operation/CreateUser){{ 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 [Create a new user](/docs/reference/backend-api/tag/Users#operation/CreateUser!path=password_hasher\&t=request) Backend API Reference docs. +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#operation/CreateUser!path=password_hasher\&t=request){{ 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. @@ -33,7 +33,7 @@ Another consideration is centered around how you handle session management. Whil #### 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 may 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 [Clerk Dashboard Sessions page](https://dashboard.clerk.com/last-active?path=sessions). Under **Customize session token**, click Edit and add the following: +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**, select **Edit** and add the following: ```json { @@ -72,7 +72,7 @@ To use Clerk's migration script, clone the [repository](https://github.com/clerk ## Migration guides -Clerk is hard at work writing up more and more specific migration guides and tools. If you have are interested in specific guides please provide more feedback at [https://feedback.clerk.com](https://feedback.clerk.com) +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) diff --git a/docs/deployments/overview.mdx b/docs/deployments/overview.mdx index 957c9fad70..1fe1f00ecc 100644 --- a/docs/deployments/overview.mdx +++ b/docs/deployments/overview.mdx @@ -17,7 +17,7 @@ Before you begin: 1. The homepage of the dashboard will show you what is still required to deploy your production instance. > [!WARNING] -> For security reasons, **[SSO Connections](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections)**, **[Integrations](https://dashboard.clerk.com/last-active?path=integrations)**, and **[Paths](https://dashboard.clerk.com/last-active?path=paths)** settings do not copy over. You will need to set these values again. +> For security reasons, [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections), [**Integrations**](https://dashboard.clerk.com/last-active?path=integrations), and [**Paths**](https://dashboard.clerk.com/last-active?path=paths) settings do not copy over. You will need to set these values again. ## API keys and environment variables @@ -40,10 +40,7 @@ In production, these are not secure and you will need to provide your own. Each Clerk uses DNS records to provide session management and emails verified from your domain. -To see what DNS records you need to add: - -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=domains). -1. In the navigation sidebar, select **Domains**. +To see what DNS records you need, navigate to the [**Domains**](https://dashboard.clerk.com/last-active?path=domains) page in the Clerk Dashboard. > [!NOTE] > It can take up to 24hrs for DNS Records to fully propagate, so be patient. @@ -57,6 +54,9 @@ When you set a root domain for your production deployment, Clerk's authenticatio - `example-site.com` and `dashboard.example-site.com` - `dashboard.example-site.com` and `accounts.example-site.com` +> [!NOTE] +> If you're using [passkeys](/docs/authentication/configuration/sign-up-sign-in-options#passkeys), only the first scenario in the above example will work due to restrictions in the [WebAuthn standard](https://www.w3.org/TR/webauthn-2/#sctn-rp-operations). + To share sessions and authentication across two different domains with the same Clerk application, see the [Authentication across different domains guide](/docs/advanced-usage/satellite-domains). ## Deploy certificates @@ -67,7 +67,7 @@ The Clerk Dashboard home page will tell you what steps are still required to dep ### DNS records not propagating with Cloudflare -Clerk uses a DNS check to validate this CNAME record. If this subdomain is reverse proxied behind a service that points to generic hostnames, such as Cloudflare, the DNS check will fail. Please set the DNS record for this subdomain to a "DNS only" mode on your host to prevent proxying. +Clerk uses a DNS check to validate this CNAME record. If this subdomain is reverse proxied behind a service that points to generic hostnames, such as Cloudflare, the DNS check will fail. Set the DNS record for this subdomain to a "DNS only" mode on your host to prevent proxying. ### Deployment stuck in certificate issuance @@ -85,4 +85,4 @@ If the command returns an empty response, your domain is correctly configured. I ### Incorrect domain -If you accidentally set the wrong domain, you can change it through the Clerk Dashboard or the Backend API. For more information, see the [dedicated guide.](/docs/deployments/changing-domains) +If you accidentally set the wrong domain, you can change it through the Clerk Dashboard or the Backend API. For more information, see the [dedicated guide](/docs/deployments/changing-domains). diff --git a/docs/deployments/staging-alternatives.mdx b/docs/deployments/staging-alternatives.mdx index 5380935753..1c25c91276 100644 --- a/docs/deployments/staging-alternatives.mdx +++ b/docs/deployments/staging-alternatives.mdx @@ -24,7 +24,7 @@ The limitations of using shared production credentials to set up a staging envir - [Netlify](https://docs.netlify.com/domains-https/netlify-dns/delegate-a-subdomain-to-netlify-dns/) - [Cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-subdomain/) 1. **Add your CNAME record to your domain provider** - Depending on the provider, the verification process can take hours or days. -1. **Add your production instance's API keys to your staging deployment** - In your staging deployment's environment variables, add your production instance's API keys. To find them, visit the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard and ensure that the instance at the top of the Dashboard is set to **Production**. The following are environment variable guides from some popular providers: +1. **Add your production instance's API keys to your staging deployment** - In your staging deployment's environment variables, add your production instance's API keys. To find them, visit the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard and ensure that the instance at the top of the Dashboard is set to **Production**. The following are environment variable guides from some popular providers: - [Vercel](https://vercel.com/docs/projects/environment-variables#declare-an-environment-variable) - [Netlify](https://docs.netlify.com/environment-variables/get-started/#create-environment-variables) - [Cloudflare](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard) diff --git a/docs/guides/add-onboarding-flow.mdx b/docs/guides/add-onboarding-flow.mdx index 8306d431d9..62a9c15bb8 100644 --- a/docs/guides/add-onboarding-flow.mdx +++ b/docs/guides/add-onboarding-flow.mdx @@ -5,7 +5,7 @@ description: Leverage Clerk’s customizable session tokens, public metadata, an Onboarding is a crucial part of many authentication flows. Sometimes you need to make sure certain criteria is met and collected before allowing access to parts of your application. With Clerk, you can leverage customizable session tokens, public metadata, and Middleware to create a custom onboarding experience. -This guide demonstrates how to create a custom onboarding flow that requires users to complete a form before they can access the application. After a user authenticates using the [Account portal](/docs/customization/account-portal/overview), the user is prompted to fill out a form with an application name and type. Once the user has completed the form, they are redirected to the application's homepage. +This guide demonstrates how to create a custom onboarding flow that requires users to complete a form before they can access the application. After a user authenticates using the [Account Portal](/docs/customization/account-portal/overview), the user is prompted to fill out a form with an application name and type. Once the user has completed the form, they are redirected to the application's homepage. In this guide, you will learn how to: @@ -16,7 +16,7 @@ In this guide, you will learn how to: For the sake of this guide, examples are written for Next.js App Router, but can be used with Next.js Pager Router as well. The examples have been pared down to the bare minimum to enable you to easily customize them to your needs. > [!NOTE] -> To see this guide in action, check out the [repository](https://github.com/clerk/clerk-nextjs-onboarding-sample-app/tree/main). +> To see this guide in action, see the [repository](https://github.com/clerk/clerk-nextjs-onboarding-sample-app/tree/main). ## Add custom claims to your session token @@ -26,8 +26,7 @@ For this guide, you will use an `onboardingComplete` property in the user's publ To edit the session token: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=sessions). -1. In the navigation sidebar, select **Sessions**. +1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page. 1. In the **Customize session token** section, select the **Edit** button. 1. In the modal that opens, you can add any claim to your session token that you need. For this guide, add the following: @@ -137,7 +136,7 @@ NEXT_PUBLIC_CLERK_SIGN_UP_FORCE_REDIRECT_URL=/onboarding ## Use `publicMetadata` to track user onboarding state -Each Clerk user has a `User` object that contains a `publicMetadata` property, which can be used to store custom data about the user. This information can be accessed on the client-side and can be used to drive application state. [Learn more about public metadata.](/docs/users/metadata#public-metadata) +Each Clerk user has a `User` object that contains a `publicMetadata` property, which can be used to store custom data about the user. This information can be accessed on the client-side and can be used to drive application state. For more information, see the [guide on metadata](/docs/users/metadata#public-metadata). You can use the user's `publicMetadata` to track the user's onboarding state. To do this, you will create: @@ -217,8 +216,10 @@ export const completeOnboarding = async (formData: FormData) => { return { message: 'No Logged In User' } } + const client = await clerkClient() + try { - const res = await clerkClient().users.updateUser(userId, { + const res = await client.users.updateUser(userId, { publicMetadata: { onboardingComplete: true, applicationName: formData.get('applicationName'), diff --git a/docs/guides/authjs-migration.mdx b/docs/guides/authjs-migration.mdx index 5b1aea726e..7ccf9daa74 100644 --- a/docs/guides/authjs-migration.mdx +++ b/docs/guides/authjs-migration.mdx @@ -58,9 +58,9 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. ### Set environment variables - Add the following code to your `.env.local` file to set your public and secret keys. + Add the following code to your `.env.local` file to set your public and Secret Keys. - **Pro tip!** If you are signed into your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys), your secret key should become visible by clicking on the eye icon. + **Pro tip!** If you are signed into the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys), your Secret Key should become visible by clicking on the eye icon. ```env {{ filename: '.env.local' }} NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} @@ -239,7 +239,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. } ``` - + To access the `userId` from the session claims, you can use the `auth()` helper. @@ -301,7 +301,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. This walkthrough will help you move user data from your existing database to Clerk. - To retain the user data in your database for easy querying, check out the documentation on [data synchronization with webhooks](/docs/integrations/webhooks/sync-data). + To retain the user data in your database for easy querying, see the [guide on data synchronization with webhooks](/docs/webhooks/sync-data). 1. Clone `github.com/clerk/migration-script` @@ -334,7 +334,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. 1. Run the script with `npm start` - 1. Check that your users are listed in the [Users](https://dashboard.clerk.com/last-active?path=users) section of the Clerk Dashboard. If the users appear to have imported correctly, verify by signing in to your application secured by Clerk with your user account. + 1. Check that your users are listed on the [**Users**](https://dashboard.clerk.com/last-active?path=users) page in the Clerk Dashboard. If the users appear to have imported correctly, verify by signing in to your application secured by Clerk with your user account. 1. Check for an error log for any users that were not migrated successfully. diff --git a/docs/guides/basic-rbac.mdx b/docs/guides/basic-rbac.mdx index 89f2730d9c..c162efd9d8 100644 --- a/docs/guides/basic-rbac.mdx +++ b/docs/guides/basic-rbac.mdx @@ -3,7 +3,7 @@ title: Implement basic Role Based Access Control (RBAC) with metadata description: Learn how to leverage Clerk's publicMetadata to implement your own basic Role Based Access Controls. --- -To control which users can access certain parts of your application, you can leverage the [roles feature.](/docs/organizations/roles-permissions#roles) Although Clerk offers a roles feature as part of the feature set for [organizations](/docs/organizations/overview), not every app implements organizations. **This guide covers a workaround to set up a basic Role Based Access Control (RBAC) system for products that don't use Clerk's organizations or roles.** +To control which users can access certain parts of your app, you can use the [roles feature](/docs/organizations/roles-permissions#roles). Although Clerk offers roles as part of the [organizations](/docs/organizations/overview) feature set, not every app implements organizations. **This guide covers a workaround to set up a basic Role Based Access Control (RBAC) system for products that don't use Clerk's organizations or roles.** This guide assumes that you're using Next.js App Router, but the concepts can be adapted to Next.js Pages Router and Remix. @@ -14,8 +14,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be To build a basic RBAC system, you first need to make `publicMetadata` available to the application directly from the session token. By attaching `publicMetadata` to the user's session, you can access the data without needing to make a network request each time. - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=sessions). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **Sessions**. + 1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page. 1. Under the **Customize session token** section, select **Edit**. 1. In the modal that opens, 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. @@ -25,16 +24,12 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - > [!CAUTION] - > The session token has a 4KB size limit. Exceeding this limit can have adverse effects, such as an infinite redirect loop for users in Next.js applications. - > To avoid this, it's recommended to move large claims out of the JWT and fetch them via a separate API call from your backend. + ### Create a global TypeScript definition - 1. In your application's root folder, create a `types` directory. - 1. Inside this directory, add a `globals.d.ts` file. This file will provide auto-completion and prevent TypeScript errors when working with roles. - - For this guide, only the `admin` and `moderator` roles will be defined. + 1. In your application's root folder, create a `types/` directory. + 1. Inside this directory, create a `globals.d.ts` file with the following code. This file will provide auto-completion and prevent TypeScript errors when working with roles. For this guide, only the `admin` and `moderator` roles will be defined. ```ts {{ filename: 'types/globals.d.ts' }} export {} @@ -55,8 +50,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be Later in the guide, you will add a basic admin tool to change a user's role. For now, manually add the `admin` role to your own user account. - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=users) . - 1. In the top navigation, select **Users**. + 1. In the Clerk Dashboard, navigate to the [**Users**](https://dashboard.clerk.com/last-active?path=users) page. 1. Select your own user account. 1. Scroll down to the **User metadata** section and next to the **Public** option, select **Edit**. 1. Add the following JSON and select **Save**. @@ -72,11 +66,10 @@ This guide assumes that you're using Next.js App Router, but the concepts can be Create a helper function to simplify checking roles. 1. In your application's root directory, create a `utils/` folder. - 1. Inside this directory, add a `roles.ts` file. - 1. Create a `checkRole()` helper that uses the [`auth()`](/docs/references/nextjs/auth) helper to access the user's session claims. From the session claims, access the `publicMetadata` object to check the user's role. The `checkRole()` helper should accept a role of type `Roles`, which you created in the [Create a global TypeScript definition](#create-a-global-typescript-definition) step. It should return `true` if the user has that role or `false` if they do not. + 1. Inside this directory, create a `roles.ts` file with the following code. The `checkRole()` helper uses the [`auth()`](/docs/references/nextjs/auth) helper to access the user's session claims. From the session claims, it accesses the `metadata` object to check the user's role. The `checkRole()` helper accepts a role of type `Roles`, which you created in the [Create a global TypeScript definition](#create-a-global-typescript-definition) step. It returns `true` if the user has that role or `false` if they do not. ```ts {{ filename: 'utils/roles.ts' }} - import { Roles } from '@/types/global' + import { Roles } from '@/types/globals' import { auth } from '@clerk/nextjs/server' export const checkRole = async (role: Roles) => { @@ -93,8 +86,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be Now, it's time to create an admin dashboard. The first step is to create the `/admin` route. 1. In your `app/` directory, create an `admin/` folder. - 1. In the `admin/` folder, create a file named `page.tsx`. - 1. Add the following placeholder code to the file. + 1. In the `admin/` folder, create a `page.tsx` file with the following placeholder code. ```tsx {{ filename: 'app/admin/page.tsx' }} export default function AdminDashboard() { @@ -107,16 +99,14 @@ This guide assumes that you're using Next.js App Router, but the concepts can be To protect the `/admin` route, choose **one** of the two following methods: 1. **Middleware**: Apply role-based access control globally at the route level. This method restricts access to all routes matching `/admin` before the request reaches the actual page. - 1. **Page-Level Role Check**: Apply role-based access control directly in the `/admin` page component. This method protects this specific page. To protect other pages in the admin dashboard, apply this protection to each route. + 1. **Page-level role check**: Apply role-based access control directly in the `/admin` page component. This method protects this specific page. To protect other pages in the admin dashboard, apply this protection to each route. > [!IMPORTANT] > You only need to follow **one** of the following methods to secure your `/admin` route. #### Option 1: Protect the `/admin` route using middleware - 1. In your app's root directory, create a `middleware.ts` file. - 1. Use the `createRouteMatcher()` function to identify routes starting with `/admin`. - 1. Apply `clerkMiddleware` to intercept requests to the `/admin` route, and check the user's role in their `publicMetadata` to verify that they have the `admin` role. If they don't, redirect them to the home page. + 1. In your app's root directory, create a `middleware.ts` file with the following code. The `createRouteMatcher()` function identifies routes starting with `/admin`. `clerkMiddleware()` intercepts requests to the `/admin` route, and checks the user's role in their `metadata` to verify that they have the `admin` role. If they don't, it redirects them to the home page. ```tsx {{ filename: 'middleware.ts' }} import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server' @@ -144,16 +134,16 @@ This guide assumes that you're using Next.js App Router, but the concepts can be #### Option 2: Protect the `/admin` route at the page-level - 1. Navigate to your `app/admin/page.tsx` file. - 1. Use the `checkRole()` function to check if the user has the `admin` role. If they don't, redirect them to the home page. + 1. Add the following code to the `app/admin/page.tsx` file. The `checkRole()` function checks if the user has the `admin` role. If they don't, it redirects them to the home page. ```tsx {{ filename: 'app/admin/page.tsx' }} - import { auth } from '@clerk/nextjs/server' + import { checkRole } from '@/utils/roles' import { redirect } from 'next/navigation' - export default function AdminDashboard() { + export default async function AdminDashboard() { // Protect the page from users who are not admins - if (!checkRole('admin')) { + const isAdmin = await checkRole('admin') + if (!isAdmin) { redirect('/') } @@ -161,15 +151,9 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - ### Add admin tools to find users and manage roles + ### Create server actions for managing a user's role - You can use the `checkRole()` function along with server actions to build basic tools for finding users and managing roles. - - Create a server action for managing a user's role. - - 1. In your `app/admin/` directory, create an `_actions.ts` file. - 1. Create a server action that sets a user's role. Use the `checkRole()` function to verify that the current user has the `admin` role. If they do, proceed to update the specified user's role using the [JavaScript Backend SDK](/docs/references/backend/user/update-user). This ensures that only administrators can modify user roles. - 1. Create a server action that removes a user's role. + 1. In your `app/admin/` directory, create an `_actions.ts` file with the following code. The `setRole()` action checks that the current user has the `admin` role before updating the specified user's role using Clerk's [JavaScript Backend SDK](/docs/references/backend/user/update-user). The `removeRole()` action removes the role from the specified user. ```ts {{ filename: 'app/admin/_actions.ts' }} 'use server' @@ -178,13 +162,15 @@ This guide assumes that you're using Next.js App Router, but the concepts can be import { clerkClient } from '@clerk/nextjs/server' export async function setRole(formData: FormData) { + const client = await clerkClient() + // Check that the user trying to set the role is an admin if (!checkRole('admin')) { return { message: 'Not Authorized' } } try { - const res = await clerkClient().users.updateUser(formData.get('id') as string, { + const res = await client.users.updateUser(formData.get('id') as string, { publicMetadata: { role: formData.get('role') }, }) return { message: res.publicMetadata } @@ -194,8 +180,10 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } export async function removeRole(formData: FormData) { + const client = await clerkClient() + try { - const res = await clerkClient().users.updateUser(formData.get('id') as string, { + const res = await client.users.updateUser(formData.get('id') as string, { publicMetadata: { role: null }, }) return { message: res.publicMetadata } @@ -205,10 +193,9 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - With the server action set up, now build the `` component. This component includes a form for searching users, and when submitted, appends the search term to the URL as a search parameter. Your `/admin` route will then perform a query based on the updated URL. + ### Create a component for searching for users - 1. In your `app/admin/` directory, create a `SearchUsers.tsx` file. - 1. Add the following code to the file. + 1. In your `app/admin/` directory, create a `SearchUsers.tsx` file with the following code. The `` component includes a form for searching for users. When submitted, it appends the search term to the URL as a search parameter. Your `/admin` route will then perform a query based on the updated URL. ```tsx {{ filename: 'app/admin/SearchUsers.tsx' }} 'use client' @@ -230,7 +217,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be router.push(pathname + '?search=' + queryTerm) }} > - + @@ -239,12 +226,11 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - With the server action and the search form set up, it's time to refactor the `app/admin/page.tsx`. It will check whether a search parameter has been appended to the URL by the search form. If a search parameter is present, it will query for users matching the entered term. + ### Refactor the admin dashboard - If one or more users are found, the component will display a list of users, showing their first and last names, primary email address, and current role. Each user will have `Make Admin` and `Make Moderator` buttons, which include hidden inputs for the user ID and role. These buttons will use the `setRole()` server action to update the user's role. + With the server action and the search form set up, it's time to refactor the `app/admin/page.tsx`. - 1. Navigate to your `app/admin/page.tsx` file. - 1. Replace the code with the following code. + 1. Replace the code in your `app/admin/page.tsx` file with the following code. It checks whether a search parameter has been appended to the URL by the search form. If a search parameter is present, it queries for users matching the entered term. If one or more users are found, the component displays a list of users, showing their first and last names, primary email address, and current role. Each user has `Make Admin` and `Make Moderator` buttons, which include hidden inputs for the user ID and role. These buttons use the `setRole()` server action to update the user's role. ```tsx {{ filename: 'app/admin/page.tsx' }} import { redirect } from 'next/navigation' @@ -253,14 +239,18 @@ This guide assumes that you're using Next.js App Router, but the concepts can be import { clerkClient } from '@clerk/nextjs/server' import { removeRole, setRole } from './_actions' - export default async function AdminDashboard(params: { searchParams: { search?: string } }) { + export default async function AdminDashboard(params: { + searchParams: Promise<{ search?: string }> + }) { if (!checkRole('admin')) { redirect('/') } - const query = params.searchParams.search + const query = (await params.searchParams).search + + const client = await clerkClient() - const users = query ? (await clerkClient().users.getUserList({ query })).data : [] + const users = query ? (await client.users.getUserList({ query })).data : [] return ( <> diff --git a/docs/guides/custom-redirects.mdx b/docs/guides/custom-redirects.mdx index dfe9d9056a..b1ba643c4e 100644 --- a/docs/guides/custom-redirects.mdx +++ b/docs/guides/custom-redirects.mdx @@ -26,7 +26,7 @@ You can define a fallback redirect URL in the case that there is no `redirect_ur The following example shows how to define a fallback redirect URL for both sign-in and sign-up pages: - + ```env {{ filename: '.env.local' }} NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/dashboard NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/onboarding @@ -42,7 +42,7 @@ The following example shows how to define a fallback redirect URL for both sign- If you would like to override the `redirect_url` value and supply a custom redirect URL after sign-in or sign-up, you can use the following environment variables: - + ```env {{ filename: '.env.local' }} NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL=/dashboard NEXT_PUBLIC_CLERK_SIGN_UP_FORCE_REDIRECT_URL=/onboarding @@ -169,7 +169,7 @@ The "force redirect URL" props will _always_ redirect to the provided url after > [!NOTE] > It is recommended to define both `signInFallbackRedirectUrl` and `signUpFallbackRedirectUrl` redirects in each button as some users may choose to sign up after attempting to sign-in, or sign in after attempting to sign-up. - + ```jsx {{ filename: 'app/sign-in/page.tsx' }} 'use client' import { SignInButton, SignUpButton } from '@clerk/nextjs' @@ -199,7 +199,7 @@ The "force redirect URL" props will _always_ redirect to the provided url after > [!NOTE] > It is recommended to define both `signInFallbackRedirectUrl` and `signUpFallbackRedirectUrl` redirects in each component as some users may choose to sign up instead after attempting to sign in. - + ```tsx {{ filename: 'app/page.tsx' }} import { SignIn, SignUp, useUser } from '@clerk/nextjs' diff --git a/docs/guides/force-organizations.mdx b/docs/guides/force-organizations.mdx index ec0c39201e..ecfef6948c 100644 --- a/docs/guides/force-organizations.mdx +++ b/docs/guides/force-organizations.mdx @@ -296,65 +296,33 @@ This guide will be written for Next.js applications using App Router, but the sa Now that you have configured your middleware to redirect users to the `/org-selection` page if they are not active in an organization, you need to create the `/org-selection` page. This page will allow users to select an organization or create their own organization. - - - ```tsx {{ filename: 'app/org-selection/page.tsx' }} - 'use client' - - import { OrganizationList } from '@clerk/nextjs' - import { useSearchParams } from 'next/navigation' - - export default function OrganizationSelection() { - const searchParams = useSearchParams() - const redirectUrl = searchParams.get('redirectUrl') ?? '/' - - return ( -
-

Welcome to the Organization Selection page.

-

- This part of the application requires the user to select an organization in order to - proceed. If you are not part of an organization, you can accept an invitation or create your - own organization. -

- -
- ) - } - ``` - + ```tsx {{ filename: 'app/org-selection/page.tsx' }} + 'use client' - - ```tsx {{ filename: 'pages/org-selection.tsx' }} - import { OrganizationList } from '@clerk/nextjs' - import { useRouter } from 'next/router' + import { OrganizationList } from '@clerk/nextjs' + import { useSearchParams } from 'next/navigation' - export default function OrganizationSelection() { - const { query } = useRouter() - const redirectUrl = query.redirectUrl ?? '/' + export default function OrganizationSelection() { + const searchParams = useSearchParams() + const redirectUrl = searchParams.get('redirectUrl') ?? '/' - return ( -
-

Welcome to the Organization Selection page.

-

- This part of the application requires the user to select an organization in order to - proceed. If you are not part of an organization, you can accept an invitation or create your - own organization. -

- -
- ) - } - ``` - - + return ( +
+

Welcome to the Organization Selection page.

+

+ This part of the application requires the user to select an organization in order to + proceed. If you are not part of an organization, you can accept an invitation or create your + own organization. +

+ +
+ ) + } + ``` #### Limit access using an App Router layout diff --git a/docs/guides/image-optimization/imageurl-image-optimization.mdx b/docs/guides/image-optimization/imageurl-image-optimization.mdx index 1c7523f966..4441f4edf9 100644 --- a/docs/guides/image-optimization/imageurl-image-optimization.mdx +++ b/docs/guides/image-optimization/imageurl-image-optimization.mdx @@ -20,7 +20,7 @@ Some types in Clerk's JavaScript SDK, such as [`User`](/docs/references/javascri The following example demonstrates how you can get the `imageUrl` from the currently active user in a session, and display their profile picture using Clerk's image optimization options: - + ```tsx {{ filename: 'app/image-optimization/page.tsx' }} import { currentUser } from '@clerk/nextjs/server' diff --git a/docs/guides/reverification.mdx b/docs/guides/reverification.mdx new file mode 100644 index 0000000000..31235d932d --- /dev/null +++ b/docs/guides/reverification.mdx @@ -0,0 +1,202 @@ +--- +title: Add reverification for sensitive actions +description: Learn how to implement Clerk's reverification feature to protect sensitive actions in your application. +--- + +> [!WARNING] +> This feature is currently in public beta. **It is not recommended for production use**. +> +> Depending on the SDK you're using, this feature requires `@clerk/nextjs@6.5.0` or later, `@clerk/clerk-sdk-ruby@3.3.0` or later, and `@clerk/clerk-js@5.35.0` or later. + +Reverification allows you to prompt a user to verify their credentials before performing sensitive actions, even if they're already authenticated. For example, in a banking application, transferring money is considered a "sensitive action." Reverification can be used to confirm the user's identity. + +## How to require reverification + +To implement reverification, you need to handle it both on the server- and client-side. + +### Handle reverification server-side + +To handle reverification server-side, use the [`auth.has()`](/docs/references/nextjs/auth-object#has) helper to check if the user has verified their credentials within a specific time period. Pass a [configuration](#supported-verification-configurations) to set the time period you would like. If the user hasn't verified their credentials within that time period, return either `reverificationError` or `reverificationErrorResponse`, depending on the framework you're using. Use the following tabs to see examples for different frameworks. + + + + The following example uses the [`has()`](/docs/references/nextjs/auth-object#has) helper to check if the user has verified their credentials within a specific time period. The `strict` configuration sets the time period to 10 minutes. If the user hasn't verified their credentials within 10 minutes, the `reverificationError` utility is used to return an error. + + ```ts {{ filename: '/app/actions.ts' }} + 'use server' + + import { auth, reverificationError } from '@clerk/nextjs/server' + + export const myAction = async () => { + const { has } = await auth.protect() + + // Check if the user has *not* verified their credentials within the past 10 minutes + const shouldUserRevalidate = !has({ reverification: 'strict' }) + + // If the user hasn't reverified, return an error with the matching configuration (e.g. `strict`) + if (shouldUserRevalidate) { + return reverificationError('strict') + } + + // If the user has verified credentials, return a successful response + return { success: true } + } + ``` + + + + + + + + The following example uses the `clerk_user_needs_reverification` helper to check if the user has verified their credentials within a specific time period. The `moderate` configuration sets the time period to 1 hour. If the user hasn't verified their credentials within 1 hour, the `clerk_render_reverification` utility is used to return a `403 forbidden` error that the client reads to initiate the reverification flow. Once the user completes the reverification on the client-side, they can access the `foo` action, which returns a success response. + + ```ruby {{ filename: 'app/controllers/home_controller.rb' }} + class HomeController < ApplicationController + before_action :require_reverification, only: :foo + + def foo + render json: { success: "true" } + end + + private + + # will halt the request and respond with a JSON that Clerk.js + # will read and kickstart a reverification flow + def require_reverification + clerk_render_reverification(Clerk::StepUp::PRESETS[:moderate]) if clerk_user_needs_reverification?(Clerk::StepUp::PRESETS[:moderate]) + end + end + ``` + + + + > [!WARNING] + > `reverificationErrorResponse` and `reverificationError` requires `@clerk/shared@2.17.0` or later, and `@clerk/clerk-js@5.35.0` or later. + + - For a JavaScript or Typescript framework that supports the [Fetch API `Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), use the `reverificationErrorResponse` to trigger reverification. For example: + + ```typescript {{ filename: 'src/api/reverification-example.ts' }} + import type { APIRoute } from 'astro' + import { reverificationErrorResponse } from '@clerk/shared/authorization-errors' + + export const GET: APIRoute = async ({ locals }) => { + const { has } = locals.auth() + + // Check if the user has *not* verified their credentials within the past 10 minutes + const shouldUserRevalidate = !has({ reverification: 'strict' }) + + // If the user hasn't reverified, return an error with the matching configuration (e.g. `strict`) + if (shouldUserRevalidate) { + return reverificationErrorResponse('strict') + } + + return new Response('success', { status: 200 }) + } + ``` + + - For a JavaScript or Typescript framework that provides its own utilities to handle responses, use `reverificationError`. For example: + + ```typescript {{ filename: 'src/api/hello.ts' }} + import { Hono } from 'hono' + + const app = new Hono() + + // POST request route + app.post('/api/hello', async (c) => { + return c.json(reverificationError('strict')) + }) + ``` + + - Alternatively, if you're not using JavaScript or TypeScript, you can create a custom helper that returns the following JSON response (it's recommended to use a `403 Forbidden` status code in your response): + ```json + { + "clerk_error": { + "type": "forbidden", + "reason": "reverification-error" + } + } + ``` + + + +### Handle reverification client-side + +After setting up reverification on the server-side, you must handle reverification on the client-side. + +The following example demonstrates how to use the [`useReverification()`](/docs/references/react/use-reverification) hook to detect authorization errors and automatically display a modal that allows the user to verify their identity. Upon successful verification, the previously failed request is automatically retried. + + + + ```tsx {{ filename: '/app/perform-action/page.tsx' }} + 'use client' + + import { useReverification } from '@clerk/nextjs' + import { myAction } from '../actions' + + export default function Page() { + const [performAction] = useReverification(myAction) + + const handleClick = async () => { + const myData = await performAction() + // If `myData` is null, the user cancelled the reverification process + // You can choose how your app responds. This example returns null. + if (!myData) return + } + + return + } + ``` + + + + ```tsx {{ filename: '/app/transfer/page.tsx' }} + 'use client' + + import { useReverification } from '@clerk/nextjs' + + export default function Page({ amount_in_cents }: { amount_in_cents: number }) { + const [transferMoney] = useReverification( + async () => + await fetch('/api/reverification-example', { + method: 'POST', + body: JSON.stringify({ amount_in_cents }), + }), + ) + + return + } + ``` + + + + ```tsx {{ filename: '/src/components/TransferButton.js' }} + import { useReverification } from '@clerk/react' + + export function TransferButton({ amount_in_cents }: { amount_in_cents: number }) { + const [transferMoney] = useReverification(() => + fetch('/api/reverification-example', { + method: 'POST', + body: JSON.stringify({ amount_in_cents }), + }), + ) + + return + } + ``` + + + +## Supported reverification configurations + +To define the time period of the reverification check, you can pass the one of the following configurations to the `has()` helper: `strict_mfa`, `strict`, `moderate`, and `lax`. See the [`has()` reference doc](/docs/references/nextjs/auth-object#check-authorization-params-with-custom-permissions) for more details. + +## Caveats + +Before enabling this feature, consider the following: + +1. **Available factors for reverification**: Not all authentication factors are supported for reverification. The available options are: + - First factors: password, email code, phone code + - Second factors: phone code, authenticator app, backup code +1. **Graceful downgrade of verification level**: If you request a `second_factor` or `multi_factor` level of verification but the user lacks a second factor available, the utilities automatically downgrade the requested level to `first_factor`. +1. **Eligibility for sensitive actions**: Users without any of the above factors cannot reverify. This can be an issue for apps that don't require email addresses to sign up or have disabled email codes in favor of email links. diff --git a/docs/guides/transferring-your-app.mdx b/docs/guides/transferring-your-app.mdx index d754fe58ad..17350f11eb 100644 --- a/docs/guides/transferring-your-app.mdx +++ b/docs/guides/transferring-your-app.mdx @@ -5,7 +5,7 @@ description: Learn how to transfer ownership of your Clerk application To transfer ownership of your application: -1. Navigate to the [Settings view](https://dashboard.clerk.com/last-active?path=settings) within the Clerk Dashboard. +1. Navigate to your application's [**Settings**](https://dashboard.clerk.com/last-active?path=settings) page in the Clerk Dashboard. 1. Select **Transfer Ownership**. From here you can transfer an application to your "Personal Account" or any Organization where you are an admin. ## Transfer to an org without billing information diff --git a/docs/guides/waitlist.mdx b/docs/guides/waitlist.mdx new file mode 100644 index 0000000000..b1d25f2da8 --- /dev/null +++ b/docs/guides/waitlist.mdx @@ -0,0 +1,152 @@ +--- +title: Set up a waitlist in your Next.js app +description: Learn how to add a waitlist to your Next.js application. +--- + +In [**Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist), users can register their interest in your app by joining a waitlist. This mode is ideal for apps in early development stages or those wanting to generate interest before launch. This guide shows you how to get Clerk integrated and how to add a waitlist to your Next.js application. + + + ### Install `@clerk/nextjs` + + Clerk's [Next.js SDK](/docs/references/nextjs/overview) gives you access to prebuilt components, React hooks, and helpers to make user authentication easier. + + Run the following command to install the SDK: + + + ```bash {{ filename: 'terminal' }} + npm install @clerk/nextjs + ``` + + ```bash {{ filename: 'terminal' }} + yarn add @clerk/nextjs + ``` + + ```bash {{ filename: 'terminal' }} + pnpm add @clerk/nextjs + ``` + + + ### Set your Clerk API keys + + + + + + + + Add the following keys to your `.env.local` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. + + + + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys){{ track: 'exp_create_account_nextjs_quickstart' }} page. + 1. In the **Quick Copy** section, copy your Clerk Publishable and Secret Keys. + 1. Paste your keys into your `.env.local` file. + + The final result should resemble the following: + + + + ```env {{ filename: '.env.local' }} + NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} + CLERK_SECRET_KEY={{secret}} + ``` + + ### Enable Waitlist mode + + To enable **Waitlist** mode, follow these steps: + + 1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page. + 1. Under the **Sign-up modes** section, enable **Waitlist**. + + To manage users on your waitlist: + + 1. In the Clerk Dashboard, navigate to the [**Waitlist**](https://dashboard.clerk.com/last-active?path=waitlist) page. + 1. On the right-side of a user's row, select the menu icon (...). + 1. Select **Invite** to invite the user to your application. Select **Deny** to deny the user access to your application. + + ### Add the `` component + + The [``](/docs/components/waitlist) component renders a form that allows users to join for early access to your app. + + The following example includes a basic implementation of the `` component hosted on the `/` route (the home page). You can use this as a starting point for your own implementation. + + ```jsx {{ filename: '/app/page.tsx' }} + import { Waitlist } from '@clerk/nextjs' + + export default function Page() { + return + } + ``` + + ### Add `` to your app + + The [``](/docs/components/clerk-provider) component wraps your app to provide active session and user context to Clerk's hooks and other components. To use the `` component in your app, you must provide the `waitlistUrl` prop, which points to the URL of your waitlist page. + + ```tsx {{ filename: 'app/layout.tsx', mark: [6] }} + import { ClerkProvider } from '@clerk/nextjs' + import './globals.css' + + export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + {children} + + + ) + } + ``` + + ### Add sign-in functionality + + To allow users to sign in once they've been approved from the waitlist, you must: + + - [Add `clerkMiddleware()` to your app.](#add-clerkmiddleware-to-your-app) + - [Add a sign-in page.](#add-a-sign-in-page) + + #### Add `clerkMiddleware()` to your app + + [`clerkMiddleware()`](/docs/references/nextjs/clerk-middleware#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. + - If you're not using the `/src` directory, create `middleware.ts` in the root directory alongside `.env.local`. + + 1. In your `middleware.ts` file, export the `clerkMiddleware()` helper: + + ```tsx {{ filename: 'middleware.ts' }} + import { clerkMiddleware } from '@clerk/nextjs/server' + + export default clerkMiddleware() + + export const config = { + matcher: [ + // Skip Next.js internals and all static files, unless found in search params + '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', + // Always run for API routes + '/(api|trpc)(.*)', + ], + } + ``` + + 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/nextjs/clerk-middleware) to learn how to require authentication for specific routes. + + #### Add a sign-in page + + The following example demonstrates how to render the `` component. + + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }} + import { SignIn } from '@clerk/nextjs' + + export default function Page() { + return + } + ``` + + Update your environment variables to point to your custom sign-in page. For more information on building custom sign-in and sign-up pages, see the [dedicated guide](/docs/references/nextjs/custom-signup-signin-pages). + + ```env {{ filename: '.env.local' }} + NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in" + ``` + diff --git a/docs/index.mdx b/docs/index.mdx index 4c1c128c8e..7a997a05a7 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -40,7 +40,7 @@ Find all the guides and resources you need to develop with Clerk. --- - [React](/docs/quickstarts/react) - - Get started installing and initializing Clerk in a new Create React App. + - Get started installing and initializing Clerk in a new React + Vite app. - {} --- diff --git a/docs/integrations/analytics/google-analytics.mdx b/docs/integrations/analytics/google-analytics.mdx index 772f92af65..9b19ab171c 100644 --- a/docs/integrations/analytics/google-analytics.mdx +++ b/docs/integrations/analytics/google-analytics.mdx @@ -10,7 +10,7 @@ This integration enables Clerk to send user authentication events to the configu To enable the integration, you will need to provide Clerk with the required Google Analytics configuration attributes depending on the type of Google Analytics property. **We support both Universal Analytics and Google Analytics 4 properties.** -To get started, go to the Clerk Dashboard and navigate to the **[Integrations](https://dashboard.clerk.com/last-active?path=integrations)** page. Turn on the Google Analytics integration. +To get started, navigate to the [**Integrations**](https://dashboard.clerk.com/last-active?path=integrations) page in the Clerk Dashboard. Turn on the Google Analytics integration. ![The Integrations page in the Clerk Dashboard. A red arrow points to the toggle next to 'Google Analytics'.](/docs/images/integrations/google/integrations.webp) @@ -34,13 +34,13 @@ To send events to Google Analytics servers, Clerk uses the [Measurement Protocol - **Measurement ID**: The measurement ID associated with the data stream sending data to your Google Analytics 4 property. The format is **G-XXXXXXX** and can be found in the Google Analytics UI under **Admin → Data Streams → choose your stream → Measurement ID**. -![A gif showing how to access the measurement ID in the Google Analytics UI.](/docs/images/integrations/google/measurement-id.gif) +![A gif showing how to access the measurement ID in the Google Analytics UI](/docs/images/integrations/google/measurement-id.gif) #### Universal Analytics - **Tracking ID**: The tracking ID is a string composed of your account number and the property index and is used to send data to the correct Google Analytics property. The format is **UA-YYYYYY-Z** and can be found in the Google Analytics UI under **Admin → Tracking Info → Tracking Code**. -![A gif showing how to access the measurement ID in the Google Analytics UI.](/docs/images/integrations/google/tracking-id.webp) +![A gif showing how to access the measurement ID in the Google Analytics UI](/docs/images/integrations/google/tracking-id.webp) ### Include Clerk user ID diff --git a/docs/integrations/databases/convex.mdx b/docs/integrations/databases/convex.mdx index 9cc1199c12..c98732de47 100644 --- a/docs/integrations/databases/convex.mdx +++ b/docs/integrations/databases/convex.mdx @@ -17,7 +17,7 @@ description: Learn how to integrate Clerk into your Convex application. }, ]} > - - Create a JWT Template based on Convex + - Create a JWT template based on Convex - Configure Convex with the Clerk issuer domain - Install and configure Clerk's React SDK - Configure the Clerk and Convex providers @@ -31,19 +31,19 @@ Convex is the full-stack TypeScript development platform. With Convex you get to This tutorial assumes that you have already [set up a Clerk application](/docs/quickstarts/setup-clerk) and a [React + Convex application](https://docs.convex.dev/quickstart/react){{ target: '_blank' }}. This tutorial will also assume that you have not added Clerk to your application yet. - ### Create a JWT Template based on Convex + ### Create a JWT template based on Convex - In the Clerk Dashboard, navigate to the [JWT Templates](https://dashboard.clerk.com/last-active?path=jwt-templates)page. Select the **New template** button to create a new template based on Convex. + In the Clerk Dashboard, navigate to the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page. Select the **New template** button to create a new template based on Convex. - ![The JWT Templates page in the Clerk Dashboard. The 'New template' button was clicked, and a pop up titled 'New JWT template' is shown. The 'Convex' template is hovered over.](/docs/images/integrations/convex/jwt-templates.webp) + ![The JWT templates page in the Clerk Dashboard. The 'New template' button was clicked, and a pop up titled 'New JWT template' is shown. The 'Convex' template is hovered over](/docs/images/integrations/convex/jwt-templates.webp) Once the Convex template is created, you will be redirected to the template's page. You can now configure the template to your needs. - ![The 'Create new template' page of the JWT Templates page in the Clerk Dashboard.](/docs/images/integrations/convex/create-template.webp) + ![The 'Create new template' page of the JWT templates page in the Clerk Dashboard](/docs/images/integrations/convex/create-template.webp) The Convex template will pre-populate the default audience (`aud`) claim required by Convex. You can include additional claims as necessary. [Shortcodes](/docs/backend-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy. - ![The 'Create new template' page of the JWT Templates page in the Clerk Dashboard. The page is scrolled down to the 'Claims' section.](/docs/images/integrations/convex/template-shortcodes.webp) + ![The 'Create new template' page of the JWT templates page in the Clerk Dashboard. The page is scrolled down to the 'Claims' section](/docs/images/integrations/convex/template-shortcodes.webp) By default, Clerk will sign the JWT with a private key automatically generated for your application, which is what most developers use for Convex. If you so choose, you can customize this key. @@ -51,7 +51,7 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q The next step is to configure Convex with the issuer domain provided by Clerk. From your Clerk **JWT template** screen, find the **Issuer** input and click to **Copy** the URL. - ![The 'Create new template' page of the JWT Templates page in the Clerk Dashboard. There is a red box surrounding the 'Issuer' section.](/docs/images/integrations/convex/template-issuer.webp) + ![The 'Create new template' page of the JWT templates page in the Clerk Dashboard. There is a red box surrounding the 'Issuer' section](/docs/images/integrations/convex/template-issuer.webp) In your `convex` folder, add an `auth.config.js` file with the following configuration: @@ -94,9 +94,17 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q In your React project's root folder, you may have an `.env.local` file alongside `package.json` and other configuration files. If you don't see it, create it. - Add the following code to your `.env.local` file to set your public key. + + Add your Clerk Publishable Key to your `.env.local` file. It can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. + - **Pro tip!** If you are signed into your Clerk Dashboard, you can copy your publishable key below. Otherwise, you can find it in the Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. + + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable Key. + 1. Paste your key into your `.env.local` file. + + The final result should resemble the following: + ```env {{ filename: '.env.local' }} VITE_CLERK_PUBLISHABLE_KEY={{pub_key}} @@ -117,7 +125,7 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q import { ConvexProviderWithClerk } from 'convex/react-clerk' import { ConvexReactClient } from 'convex/react' - // Import your publishable key + // Import your Publishable Key const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY if (!PUBLISHABLE_KEY) { @@ -157,9 +165,9 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q }) ``` - You can customize the information in the JWT by navigating to the [JWT Templates](https://dashboard.clerk.com/last-active?path=jwt-templates) page in the Clerk Dashboard. Previously, Convex explicitly listed fields derived from [OpenID standard claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). Now, Convex allows keys to accept [custom claims](https://docs.convex.dev/api/interfaces/server.UserIdentity). + You can customize the information in the JWT by navigating to the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page in the Clerk Dashboard. Previously, Convex explicitly listed fields derived from [OpenID standard claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). Now, Convex allows keys to accept [custom claims](https://docs.convex.dev/api/interfaces/server.UserIdentity). ### Finished! - You now have a fully functioning React and Convex application with Clerk authentication. Be aware that Convex may require usage of their custom hooks and methods rather than Clerk's, such as using Convex's `useConvexAuth()` hook instead of Clerk's `useAuth()` hook in some cases. For more information on how to use Convex with Clerk, check out the [Convex docs](https://docs.convex.dev/auth/clerk). + You now have a fully functioning React and Convex application with Clerk authentication. Be aware that Convex may require usage of their custom hooks and methods rather than Clerk's, such as using Convex's `useConvexAuth()` hook instead of Clerk's `useAuth()` hook in some cases. For more information on how to use Convex with Clerk, see the [Convex docs](https://docs.convex.dev/auth/clerk). diff --git a/docs/integrations/databases/fauna.mdx b/docs/integrations/databases/fauna.mdx index 955a353379..40ed46991e 100644 --- a/docs/integrations/databases/fauna.mdx +++ b/docs/integrations/databases/fauna.mdx @@ -23,7 +23,7 @@ description: Learn how to integrate Clerk into your Fauna application. > [!IMPORTANT] -> Check out the [demo repo](https://github.com/clerk/clerk-fauna-nextjs) for a full example of how to integrate Fauna with Clerk in a Next.js app. +> See the [demo repo](https://github.com/clerk/clerk-fauna-nextjs) for a full example of how to integrate Fauna with Clerk in a Next.js app. Integrating Fauna with Clerk gives you the benefits of using a Fauna database while leveraging Clerk's authentication, prebuilt components, and webhooks. @@ -33,15 +33,14 @@ This guide will walk you through the steps to integrate Fauna with Clerk in your ### Get your Clerk Frontend API URL and JWKS URL - Add the following keys to your `.env.local` file. These keys can always be retrieved from the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page of your Clerk Dashboard. + Add the following keys to your `.env.local` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. - 1. Navigate to the Clerk Dashboard. - 1. In the navigation sidebar, select [API Keys](https://dashboard.clerk.com/last-active?path=api-keys). - 1. In the left sidebar, select **Show API URLs**. + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the navigation sidebar, select **Show API URLs**. 1. Copy the **Frontend API URL**. - 1. In the left sidebar, select **Show JWT public key**. + 1. In the navigation sidebar, select **Show JWT public key**. 1. Copy the **JWKS URL**. 1. Paste your keys into your `.env.local` file. @@ -83,8 +82,7 @@ This guide will walk you through the steps to integrate Fauna with Clerk in your To create a JWT template for Fauna: - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). - 1. In the navigation sidebar, select **JWT Templates**. + 1. In the Clerk Dashboard, navigate to the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page. 1. Select the **New template** button, then select **Fauna** from the list of options. 1. Configure your template: - The value of the **Name** field will be required when using the template in your code. For this tutorial, name it `fauna`. diff --git a/docs/integrations/databases/firebase.mdx b/docs/integrations/databases/firebase.mdx index 7c880302fb..51c692f0eb 100644 --- a/docs/integrations/databases/firebase.mdx +++ b/docs/integrations/databases/firebase.mdx @@ -29,7 +29,7 @@ description: Learn how to integrate Clerk into your Firebase application. Integrating Firebase with Clerk gives you the benefits of using Firebase's features while leveraging Clerk's authentication, prebuilt components, and webhooks. > [!TIP] -> Check out the [demo repo](https://github.com/clerk/clerk-firebase-nextjs) for a full example of how to integrate Firebase with Clerk in a Next.js app. +> See the [demo repo](https://github.com/clerk/clerk-firebase-nextjs) for a full example of how to integrate Firebase with Clerk in a Next.js app. ### Configure the integration @@ -38,13 +38,12 @@ Integrating Firebase with Clerk gives you the benefits of using Firebase's featu To get enable the integration: - 1. Navigate to the Clerk Dashboard. - 1. In the sidebar, select **[Integrations](https://dashboard.clerk.com/last-active?path=integrations)**. + 1. In the Clerk Dashboard, navigate to the [**Integrations**](https://dashboard.clerk.com/last-active?path=integrations) page. 1. Toggle the **Firebase** integration on. The configuration modal will appear. Keep this open while you configure your Firebase project. Next, configure your integration. - + The recommended way to configure your integration is to use a service account key provided by Firebase in order to configure the integration _automatically_. To do so: @@ -201,7 +200,7 @@ Integrating Firebase with Clerk gives you the benefits of using Firebase's featu ## Next steps - - [Use webhooks to sync Firebase data with Clerk](/docs/integrations/webhooks/sync-data) + - [Use webhooks to sync Firebase data with Clerk](/docs/webhooks/sync-data) - Learn how to sync Firebase auth or Firestore data with Clerk data using webhooks. --- diff --git a/docs/integrations/databases/grafbase.mdx b/docs/integrations/databases/grafbase.mdx index 9e066640c2..948b6f3bd1 100644 --- a/docs/integrations/databases/grafbase.mdx +++ b/docs/integrations/databases/grafbase.mdx @@ -3,28 +3,28 @@ title: Integrate Grafbase with Clerk description: Learn how to integrate Clerk and Grafbase into your application --- -The first step is to create a new Clerk application from your Clerk Dashboard if you haven’t done so already. You can choose whichever authentication strategy and social sign-in providers you prefer. For more information, check out our [Set up your application](/docs/quickstarts/setup-clerk) guide. +The first step is to create a new Clerk application from the Clerk Dashboard if you haven’t done so already. You can choose whichever authentication strategy and social sign-in providers you prefer. For more information, see the [setup guide](/docs/quickstarts/setup-clerk). -After your Clerk application has been created, go to the Clerk Dashboard and navigate to the **[JWT Templates](https://dashboard.clerk.com/last-active?path=jwt-templates)** page. Click on the **New template** button to create a new template based on Grafbase. +After your Clerk application has been created, navigate to the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page in the Clerk Dashboard. Click on the **New template** button to create a new template based on Grafbase. -![The JWT Templates page in the Clerk Dashboard. The 'New template' button was clicked, and a pop up titled 'New JWT template' is shown. The 'Grafbase' template is hovered over.](/docs/images/integrations/grafbase/jwt-template.webp) +![The JWT templates page in the Clerk Dashboard. The 'New template' button was clicked, and a pop up titled 'New JWT template' is shown. The 'Grafbase' template is hovered over](/docs/images/integrations/grafbase/jwt-template.webp) Once the Grafbase template is created, you will be redirected to the template's page. You can now configure the template to your needs. -![The 'Create new template' page of the JWT Templates page in the Clerk Dashboard.](/docs/images/integrations/grafbase/create-template.webp) +![The 'Create new template' page of the JWT templates page in the Clerk Dashboard](/docs/images/integrations/grafbase/create-template.webp) The Grafbase template will pre-populate the default claims required by Grafbase. You can include additional claims as necessary. [Shortcodes](/docs/backend-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy. > [!NOTE] > If your GraphQL API restricts access based on groups, you’ll need to specify the users groups in the `groups` claim. -![The 'Create new template' page of the JWT Templates page in the Clerk Dashboard. The page is scrolled down to the 'Claims' section.](/docs/images/integrations/grafbase/template-shortcodes.webp) +![The 'Create new template' page of the JWT templates page in the Clerk Dashboard. The page is scrolled down to the 'Claims' section](/docs/images/integrations/grafbase/template-shortcodes.webp) ## Configure Grafbase The next step is to configure Grafbase with the issuer domain provided by Clerk. From your Clerk **JWT template** screen, find the **Issuer** input and click to **Copy** the URL. -![The 'Create new template' page of the JWT Templates page in the Clerk Dashboard. There is a red box surrounding the 'Issuer' section.](/docs/images/integrations/grafbase/template-issuer.webp) +![The 'Create new template' page of the JWT templates page in the Clerk Dashboard. There is a red box surrounding the 'Issuer' section](/docs/images/integrations/grafbase/template-issuer.webp) ### Signed in user authentication @@ -37,7 +37,7 @@ schema } ``` -Make sure to set the environment variable `ISSUER_URL` (using the Grafbase CLI, or Clerk Dashboard) to be your Frontend API value. This value can be found in the Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. +Make sure to set the environment variable `ISSUER_URL` (using the Grafbase CLI, or Clerk Dashboard) to be your Frontend API value. This value can be found on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. ### Group-based authentication @@ -53,9 +53,9 @@ schema } ``` -Make sure to replace `YOUR_FRONTEND_API` with the Frontend API value. This value can be found in the Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. +Make sure to replace `YOUR_FRONTEND_API` with the Frontend API value. This value can be found on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. -If needed, you can also use a shortcode to dynamically include the users current organization's role. Shortcodes can be found and updated on your **[JWT template](https://dashboard.clerk.com/last-active?path=jwt-templates)** for Grafbase in the Clerk Dashboard. +If needed, you can also use a shortcode to dynamically include the users current organization's role. Shortcodes can be found and updated in the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page in the Clerk Dashboard. ```json { diff --git a/docs/integrations/databases/hasura.mdx b/docs/integrations/databases/hasura.mdx index 03c865991a..9dea99b5d3 100644 --- a/docs/integrations/databases/hasura.mdx +++ b/docs/integrations/databases/hasura.mdx @@ -3,29 +3,29 @@ title: Integrate Hasura with Clerk description: Learn how to integrate Clerk into your Hasura application. --- -The first step is to create a new Clerk application from your Clerk Dashboard if you haven’t done so already. You can choose whichever authentication strategy and social sign-in providers you prefer. For more information, check out our [Set up your application](/docs/quickstarts/setup-clerk) guide. +The first step is to create a new Clerk application from the Clerk Dashboard if you haven’t done so already. You can choose whichever authentication strategy and social sign-in providers you prefer. For more information, see the [setup guide](/docs/quickstarts/setup-clerk). -After your Clerk application has been created, go to the Clerk Dashboard and navigate to the **[JWT Templates](https://dashboard.clerk.com/last-active?path=jwt-templates)** page. Click on the **New template** button to create a new template based on Hasura. +After your Clerk application has been created, navigate to the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page in the Clerk Dashboard. Click on the **New template** button to create a new template based on Hasura. -![The JWT Templates page in the Clerk Dashboard. The 'New template' button was clicked, and a pop up titled 'New JWT template' is shown. The 'Hasura' template is hovered over.](/docs/images/integrations/hasura/jwt-template.webp) +![The JWT templates page in the Clerk Dashboard. The 'New template' button was clicked, and a pop up titled 'New JWT template' is shown. The 'Hasura' template is hovered over](/docs/images/integrations/hasura/jwt-template.webp) Once the Hasura template is created, you will be redirected to the template's page. You can now configure the template to your needs. -![The 'Create new template' page of the JWT Templates page in the Clerk Dashboard.](/docs/images/integrations/hasura/create-template.webp) +![The 'Create new template' page of the JWT templates page in the Clerk Dashboard](/docs/images/integrations/hasura/create-template.webp) The Hasura template will pre-populate the default claims required by Hasura. You can include additional claims as necessary. [Shortcodes](/docs/backend-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy. -![The 'Create new template' page of the JWT Templates page in the Clerk Dashboard. The page is scrolled down to the 'Claims' section.](/docs/images/integrations/hasura/template-shortcodes.webp) +![The 'Create new template' page of the JWT templates page in the Clerk Dashboard. The page is scrolled down to the 'Claims' section](/docs/images/integrations/hasura/template-shortcodes.webp) By default, Clerk will sign the JWT with a private key automatically generated for your application, which is what most developers use for Hasura. If you so choose, you can customize this key. ## Configure Hasura -The next step is to provide Hasura with the public keys used to verify the JWT issued by Clerk. Assuming you didn’t use a custom signing key, set the **JWKS endpoint** field to the JSON Web Key Set (JWKS) URL Clerk automatically created with your Frontend API at `https:///.well-known/jwks.json` +The next step is to provide Hasura with the public keys used to verify the JWT issued by Clerk. Assuming you didn’t use a custom signing key, set the **JWKS Endpoint** field to the JSON Web Key Set (JWKS) URL Clerk automatically created with your Frontend API at `https:///.well-known/jwks.json` -You can find this URL in the Clerk Dashboard on the **[API keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. Scroll down and click on **Advanced**. In the **JWT public key** section, copy the **JWKS URL**. +You can find this URL on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. In the left sidebar, select **Show JWT public key**. Copy the **JWKS URL**. -![The API Keys page in the Clerk Dashboard. A red box outlines the 'Advanced' drop down button. A red arrow is pointing to the copy button next to 'JWKS URL' in the 'JWT public key' section.](/docs/images/integrations/jwks-url.webp) +![The API keys page in the Clerk Dashboard. A red box outlines the 'Advanced' drop down button. A red arrow is pointing to the copy button next to 'JWKS URL' in the 'JWT public key' section](/docs/images/integrations/jwks-url.webp) You can set up your project either with Hasura Cloud or you can [run the Hasura GraphQL engine locally using Docker Compose](https://hasura.io/docs/2.0/getting-started/docker-simple). @@ -45,14 +45,14 @@ To add the JWT secret locally with Hasura Core, you need to set both the `HASURA `HASURA_GRAPHQL_ADMIN_SECRET` can be set to any text string. -`HASURA_GRAPHQL_JWT_SECRET` should be set to a stringified JSON object of the JWT secret which contains the JWKS endpoint as the value of `jwk_url`. +`HASURA_GRAPHQL_JWT_SECRET` should be set to a stringified JSON object of the JWT secret which contains the JWKS Endpoint as the value of `jwk_url`. ```yaml HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey HASURA_GRAPHQL_JWT_SECRET: '{"jwk_url":"https://{{fapi}}/.well-known/jwks.json"}' ``` -Replace `` with the Frontend API value. This value can be found in the Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. +Replace `` with the Frontend API value. This value can be found on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. ### With custom signing key diff --git a/docs/integrations/databases/instantdb.mdx b/docs/integrations/databases/instantdb.mdx index e87cf82021..43522defff 100644 --- a/docs/integrations/databases/instantdb.mdx +++ b/docs/integrations/databases/instantdb.mdx @@ -28,7 +28,7 @@ description: Learn how to integrate Clerk into your InstantDB application. > [!IMPORTANT] -> Check out the [demo repo](https://github.com/clerk/clerk-instantdb-nextjs) for a full example of how to integrate InstantDB with Clerk in a Next.js app. +> See the [demo repo](https://github.com/clerk/clerk-instantdb-nextjs) for a full example of how to integrate InstantDB with Clerk in a Next.js app. Integrating [InstantDB](https://www.instantdb.com/) with Clerk gives you the benefits of using an InstantDB database while leveraging Clerk's authentication, prebuilt components, and webhooks. @@ -39,8 +39,7 @@ This guide will walk you through the steps to integrate InstantDB with Clerk in InstantDB uses Clerk's [session token](/docs/backend-requests/resources/session-tokens) to authenticate users. To use InstantDB with Clerk, you need to include the `email` claim in your session token. - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=sessions). - 1. In the navigation sidebar, select **Sessions**. + 1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page. 1. In the **Customize session token** section, select **Edit**. 1. Add the `email` claim to your session token: ```json @@ -51,24 +50,22 @@ This guide will walk you through the steps to integrate InstantDB with Clerk in You can have additional claims as long as the `email` claim is set to `{{user.primary_email_address}}`. - ### Get your Clerk publishable key + ### Get your Clerk Publishable Key - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys). - 1. In the navigation sidebar, select **API Keys**. - 1. In the **Quick Copy** section, copy your Clerk publishable key. + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable Key. ### Configure InstantDB - 1. Navigate to the [InstantDB dashboard](https://www.instantdb.com/dash?t=auth). - 1. Select the **Auth** tab. + 1. In the InstantDB dashboard, navigate to the [**Auth**](https://www.instantdb.com/dash?t=auth) tab. 1. Select **Setup Clerk**. - 1. Add the publishable key you copied in the previous step. + 1. Add the Publishable Key you copied in the previous step. 1. Confirm the **The session token has the "email" claim.** message. 1. Select **Add Clerk app**. ### Install the InstantDB library - Add the InstantDB library to your project. + Run the following command to add the InstantDB library to your project. ```bash {{ filename: 'terminal' }} @@ -88,7 +85,7 @@ This guide will walk you through the steps to integrate InstantDB with Clerk in To sign in to InstantDB with Clerk, you need to: - - Initialize InstantDB with your Clerk publishable key. + - Initialize InstantDB with your Clerk Publishable Key. - Use Clerk's `getToken()` helper to get the session for the user that is signed in to Clerk. - Pass the session to InstantDB's `db.auth.signInWithIdToken()` method in order to sign in to InstantDB. When you call `db.auth.signInWithIdToken()`, InstantDB will verify that the session was signed by your Clerk app. If verified, InstantDB uses the email in the session's claims to sign in, look up your user, or create a new one. diff --git a/docs/integrations/databases/nhost.mdx b/docs/integrations/databases/nhost.mdx index 6665e61aff..9ccf6c0d1a 100644 --- a/docs/integrations/databases/nhost.mdx +++ b/docs/integrations/databases/nhost.mdx @@ -3,31 +3,31 @@ title: Integrate Nhost with Clerk description: Learn how to integrate Clerk into your Nhost project. --- -The first step is to create a new Clerk application from your Clerk Dashboard if you haven’t done so already. You can choose whichever authentication strategy and social sign-in providers you prefer. For more information, check out our [Set up your application](/docs/quickstarts/setup-clerk) guide. +The first step is to create a new Clerk application from the Clerk Dashboard if you haven’t done so already. You can choose whichever authentication strategy and social sign-in providers you prefer. For more information, see the [setup guide](/docs/quickstarts/setup-clerk). -After your Clerk application has been created, go to the Clerk Dashboard and navigate to the **[JWT Templates](https://dashboard.clerk.com/last-active?path=jwt-templates)** page. Click on the **New template** button to create a new template based on Nhost. +After your Clerk application has been created, navigate to the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page in the Clerk Dashboard. Click on the **New template** button to create a new template based on Nhost. -![The JWT Templates page in the Clerk Dashboard. The 'New template' button was clicked, and a pop up titled 'New JWT template' is shown. The 'Nhost' template is hovered over.](/docs/images/integrations/nhost/jwt-template.webp) +![The JWT templates page in the Clerk Dashboard. The 'New template' button was clicked, and a pop up titled 'New JWT template' is shown. The 'Nhost' template is hovered over](/docs/images/integrations/nhost/jwt-template.webp) Once the Nhost template is created, you will be redirected to the template's page. You can now configure the template to your needs. -![The 'Create new template' page of the JWT Templates page in the Clerk Dashboard.](/docs/images/integrations/nhost/create-template.webp) +![The 'Create new template' page of the JWT templates page in the Clerk Dashboard](/docs/images/integrations/nhost/create-template.webp) The Nhost template will pre-populate the default claims required by Nhost and Hasura. You can include additional claims as necessary. [Shortcodes](/docs/backend-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy. -![The 'Create new template' page of the JWT Templates page in the Clerk Dashboard. The page is scrolled down to the 'Claims' section.](/docs/images/integrations/nhost/template-shortcodes.webp) +![The 'Create new template' page of the JWT templates page in the Clerk Dashboard. The page is scrolled down to the 'Claims' section](/docs/images/integrations/nhost/template-shortcodes.webp) ## Configure Nhost -The next step is to provide Nhost with the public keys used to verify the JWT issued by Clerk. Assuming you didn’t use a custom signing key, set the **JWKS endpoint** field to the JSON Web Key Set (JWKS) URL Clerk automatically created with your Frontend API at `https:///.well-known/jwks.json` +The next step is to provide Nhost with the public keys used to verify the JWT issued by Clerk. Assuming you didn’t use a custom signing key, set the **JWKS Endpoint** field to the JSON Web Key Set (JWKS) URL Clerk automatically created with your Frontend API at `https:///.well-known/jwks.json` -You can find this URL in the Clerk Dashboard on the **[API keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. Scroll down and click on **Advanced**. In the **JWT public key** section, copy the **JWKS URL**. +You can find this URL on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. In the left sidebar, select **Show JWT public key**. Copy the **JWKS URL**. -![The API Keys page in the Clerk Dashboard. A red box outlines the 'Advanced' drop down button. A red arrow is pointing to the copy button next to 'JWKS URL' in the 'JWT public key' section.](/docs/images/integrations/jwks-url.webp) +![The API keys page in the Clerk Dashboard. A red box outlines the 'Advanced' drop down button. A red arrow is pointing to the copy button next to 'JWKS URL' in the 'JWT public key' section](/docs/images/integrations/jwks-url.webp) From your Nhost dashboard, navigate to **Settings** --> **Environment variables**. -![The Environment variables page in the Nhost dashboard.](/docs/images/integrations/nhost/nhost-env-var.webp) +![The Environment variables page in the Nhost dashboard](/docs/images/integrations/nhost/nhost-env-var.webp) Next to the **NOHST\_JWT\_SECRET**, click the **Edit** button and paste in the **JWKS URL** that you copied from the Clerk Dashboard. diff --git a/docs/integrations/databases/supabase.mdx b/docs/integrations/databases/supabase.mdx index a8705490dc..5e07259eef 100644 --- a/docs/integrations/databases/supabase.mdx +++ b/docs/integrations/databases/supabase.mdx @@ -23,7 +23,7 @@ description: Learn how to integrate Clerk into your Supabase application. > [!IMPORTANT] -> Check out the [demo repo](https://github.com/clerk/clerk-supabase-nextjs) for a full example of how to integrate Supabase with Clerk in a Next.js app. +> See the [demo repo](https://github.com/clerk/clerk-supabase-nextjs) for a full example of how to integrate Supabase with Clerk in a Next.js app. Integrating Supabase with Clerk gives you the benefits of using a Supabase database while leveraging Clerk's authentication, prebuilt components, and webhooks. To get the most out of Supabase with Clerk, you must implement custom [Row Level Security](https://supabase.com/docs/guides/auth/row-level-security) (RLS) policies. @@ -37,7 +37,7 @@ RLS works by validating database queries according to the restrictions defined i This guide will have you create a new table in your [Supabase project](https://supabase.com/dashboard/projects), but you can apply these concepts to your existing tables as well. > [!TIP] -> This integration restricts what data authenticated users can access in the database, but does not synchronize user records between Clerk and Supabase. To send additional data from Clerk to your Supabase database, use [webhooks](/docs/integrations/webhooks/overview). +> This integration restricts what data authenticated users can access in the database, but does not synchronize user records between Clerk and Supabase. To send additional data from Clerk to your Supabase database, use [webhooks](/docs/webhooks/overview). ## Choose your own adventure @@ -165,11 +165,11 @@ For interacting with the Supabase dashboard, you can either use the **Supabase i - ### Get your Supabase JWT secret key + ### Get your Supabase JWT Secret Key - To give users access to your data, Supabase's API requires an authentication token. Your Clerk project can generate these authentication tokens, but it needs your Supabase project's JWT secret key first. + To give users access to your data, Supabase's API requires an authentication token. Your Clerk project can generate these authentication tokens, but it needs your Supabase project's JWT Secret Key first. - To find the JWT secret key: + To find the JWT Secret Key: 1. In the sidebar, navigate to **Project Settings > API**. 1. Under the **JWT Settings** section, save the value in the **JWT Secret** field somewhere secure. This value will be used in the next step. @@ -180,13 +180,12 @@ For interacting with the Supabase dashboard, you can either use the **Supabase i To create a JWT template for Supabase: - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates). - 1. In the navigation sidebar, select **JWT Templates**. + 1. In the Clerk Dashboard, navigate to the [**JWT templates**](https://dashboard.clerk.com/last-active?path=jwt-templates) page. 1. Select the **New template** button, then select **Supabase** from the list of options. 1. Configure your template: - The value of the **Name** field will be required when using the template in your code. For this tutorial, name it `supabase`. - **Signing algorithm** will be `HS256` by default. This algorithm is required to use JWTs with Supabase. [Learn more in their docs](https://supabase.com/docs/guides/resources/glossary#jwt-signing-secret). - - Under **Signing key**, add the value of your Supabase **JWT secret key** from [the previous step](#get-your-supabase-jwt-secret-key). + - Under **Signing key**, add the value of your Supabase **JWT Secret Key** from [the previous step](#get-your-supabase-jwt-secret-key). - You can leave all other fields at their default settings or customize them to your needs. See the [JWT template guide](/docs/backend-requests/making/jwt-templates#creating-a-template) to learn more about these settings. - Select **Save** from the notification bubble to complete setup. diff --git a/docs/integrations/overview.mdx b/docs/integrations/overview.mdx index c7ff73b838..e05f80e23c 100644 --- a/docs/integrations/overview.mdx +++ b/docs/integrations/overview.mdx @@ -60,7 +60,7 @@ description: Learn about the available integrations with Clerk. --- - - [Inngest](/docs/integrations/webhooks/inngest) + - [Inngest](/docs/webhooks/inngest) - Use events from Clerk to trigger functions defined in your codebase with Inngest. Easily handle data synchronization, onboarding campaigns, or billing workflows in code. - ![](data:image/webp;base64,UklGRh4EAABXRUJQVlA4WAoAAAAQAAAAPwAAPwAAQUxQSCsBAAABgGPbttrmrd+p+6VqlV5/GqHKy2WwM7ZsV2G1nkmYORpBmJmZGV5I8J8pVETEBIBcT9/9veFhkKFMGPilITKD69dorvMM8K6g5XUvNdGHtg1BiSfRyfukSoV5V9DhdS8N0YoS+4Q8JY1y79OqJPcpSl/3yBDdSNIQDjGunyLRa111xD2BhNc9zJY2gcQNYY1FkP5lklmJYEZ6LainmXGvmNVghnrNajMl+e2T+D+sJlPKzZTnzNjjZuDLjBBYZOGjDAgxKwDaCLUhFWyXzVGaLQMned0lvtI4TXFw2NVBo1UDiWXL8raLQC5vvpSkM5DMQOuQ0aIByfI1pxaqGRBVw47cpDgQ1jrstWhAvHza2kI10FfqLNykFMhI19BXfS7IVFbUd3PTVwRyAQBWUDggzAIAAFAPAJ0BKkAAQAA+bSyQRb+ioZgLBn34BsS2NhOjmcG42OcWxB5zzRbd/dPwjyhVt/Ej6ZfmA/Yb9gPeH6QD+8ei56lfoAeWZ+tfwVfuR+2HtMtEDSBM1kzDpLxf/u+uW/v4piORnc5jdBlHICkQIbU3Q9Rw1Zv+uCAbrW6IG1df/8EAAP7qGh/9l4pVVBFh+rUY1hy2oGoQV6VGbRHBB2iO0tH/tfH1yRzR3C0HtWw52pZ0QY3Z/vV9q0pqPxK/4/lkfqd2FNP7c15rLCwA8JOvCrqUwq06o83BkZP1MFUdnpr2V8QfIhwktF8gJKTzekh0l7+/J3/8Yi1u5rwesYJlTUDJaZxeZ0/QyaSj7PbEmRwoKia7uNMXgW9sCo+LA7cRYi69D1+QB3yCR8SxVeuahEJAN3IAVOiUwzBeniXMzc5T8B9e5IRgPrynbpSBzCUDWb473yJev7dzLbFtmzFn/234VUeDew/CTEy7fXMomgYBxRubyPU2Os+UNxy8j9+kG1qXNRuPnoCCFf7eempoK9f64lDFekVGNfaP0FMN0yI9fXJBMR6LzLIQ284yBv9SZqJR9yHk9vnwcr+2bcZY+fYRnwm7ed7tJWvWNG/aOZm4ixfPARv8bEWp8DBlrSSNM0fP8eK9AS6LrhQR4cIVsezbBjAAlJ0xwriFeai5RHah1NpMj1I1V6MvEtL8cyoBRz1k492Yo9Nkejreud7UO/yuLM4D1p4btGlGKDTRLgeZPVj9+RDUFTMl8CYLf9V/Wz/4xh/8jFCrLaD3wHlLZ+Wb8PD58Tmzvmvw1gSFiLOt6tdsX0DR5Nov5r6abhM8je+r0W5wX2KGXS/q+a6XpKSVE+mm49uS4cjDWPste4EBGZhmVfnH62FO6za+oovV0UW4rF8TTGp60bC3uj7wnfm6xh7FRW+BBTpGQRbGJMgbchuEdsEhgAAA) diff --git a/docs/integrations/webhooks/sync-data.mdx b/docs/integrations/webhooks/sync-data.mdx deleted file mode 100644 index 50047fe5e7..0000000000 --- a/docs/integrations/webhooks/sync-data.mdx +++ /dev/null @@ -1,379 +0,0 @@ ---- -title: Sync Clerk data to your application with webhooks -description: Learn how to sync Clerk data to your application with webhooks. ---- - - - - Listen for an event in the Clerk Dashboard - - Create a webhook handler that: - - uses Svix to verify the webhook signature - - receives the webhook's payload - - Test the webhook locally using ngrok and the Clerk Dashboard - - Add logic to your application to trigger the webhook - - -The recommended way to sync data between Clerk and your application is to use webhooks. - -In this guide, you will learn how to create a Clerk webhook in your Next.js application. You will listen for the `user.updated` event by creating a webhook endpoint in the Clerk Dashboard, creating a webhook handler in your Next.js application, and testing the webhook locally using ngrok and the Clerk Dashboard. - -This guide can be adapted to listen for any Clerk event. - - - ### Set up ngrok - - To test a webhook locally, you will need to expose your local server to the internet. For this guide, you will use [ngrok](https://ngrok.com/). ngrok will create a **forwarding URL** that you can send your webhook payload to and it will forward the payload to your local server. - - 1. Go to the [ngrok website](https://ngrok.com/) and create an account. - 1. Once you have made it to the [ngrok dashboard](https://dashboard.ngrok.com/get-started/setup/macos), in navigation sidebar, select [**Domains**](https://dashboard.ngrok.com/cloud-edge/domains). - 1. Select **Create domain**. - 1. Install ngrok and add your auth token by following steps 1 and 2 in their [install guide](https://ngrok.com/docs/getting-started/#step-1-install). - 1. ngrok will generate a free, non-ephemeral domain for you and a command to start a tunnel with that domain. The command should look something like this: - - `ngrok http --domain=fawn-two-nominally.ngrok-free.app 3000` - 1. Change the port number to whatever your server is running on. For this guide, ensure it is set to 3000 and then run the command in your terminal. - 1. Copy your **forwarding URL**. It should look something like `https://fawn-two-nominally.ngrok-free.app`. - - ### Create an endpoint in the Clerk Dashboard - - To create a webhook endpoint, you must provide the **Endpoint URL** and then choose the events you want to listen to. For this guide, you will listen to the `user.updated` event. - - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=webhooks). - 1. In the navigation sidenav, select **Webhooks**. - 1. Select the **Add Endpoint** button. - 1. In the **Endpoint URL** field, paste the ngrok URL you copied earlier followed by `/api/webhooks`. This is the endpoint that you will later create, that Svix will send the webhook payload to. The full URL should look something like `https://fawn-two-nominally.ngrok-free.app/api/webhooks`. - 1. In the **Message Filtering** section, select the `user.updated` event. - 1. Select the **Create** button. - 1. You will be redirected to your endpoint's settings page. Leave this page open. - - ### Add your signing secret to your `.env.local` file - - To verify the webhook payload, you will need your endpoint's signing secret. However, you do not want to expose this secret in your codebase, so you will want to provide it as an environment variable. In local development, this can be done by storing the secret in the `.env.local` file. - - 1. On the endpoint's settings page, copy the **Signing Secret**. It should be on the right side of the page with an eye icon next to it. - 1. In your project's root directory, you should have an `.env.local` file that includes your Clerk API keys. Here, assign your signing secret to `WEBHOOK_SECRET`. Your file should look something like this: - - ```env {{ filename: '.env.local' }} - NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} - CLERK_SECRET_KEY={{secret}} - WEBHOOK_SECRET=whsec_123 - ``` - - ### Set webhook route as public in your Middleware - - Incoming webhook events will never be signed in -- they are coming from a source outside of your application. Since they will be in a signed out state, the route should be public. - - The following example shows the recommended Middleware configuration for your webhook routes. - - ```tsx {{ filename: 'middleware.tsx' }} - import { clerkMiddleware } from '@clerk/nextjs/server' - - // Make sure that the `/api/webhooks(.*)` route is not protected here - export default clerkMiddleware() - - export const config = { - matcher: [ - // Skip Next.js internals and all static files, unless found in search params - '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', - // Always run for API routes - '/(api|trpc)(.*)', - ], - } - ``` - - ### Install `svix` - - You will use [`svix`](https://www.npmjs.com/package/svix) to verify the webhook signature. Run the following command to install it: - - - ```bash {{ filename: 'terminal' }} - npm install svix - ``` - - ```bash {{ filename: 'terminal' }} - yarn add svix - ``` - - ```bash {{ filename: 'terminal' }} - pnpm add svix - ``` - - - ### Create the endpoint in your application - - Create a Route Handler that uses `svix` to verify the webhook signature and that receives the webhook's payload. - - For the sake of this guide, you will only log the payload to the console. In a real world application, you would use the payload to trigger some action. For example, you are listening for the `user.updated` event, so you could perform a database `update` or `upsert` to update the user's details. - - Your webhook will need to return either an error code, or a success code, like `200` or `201`. If it returns an error code, the webhook will reflect that in the Dashboard log and it will [retry](/docs/integrations/webhooks/overview#retry). When the webhook returns a success code, there will be no retries and the webhook will show a success status in the Dashboard. - - > [!NOTE] - > The following Route Handler is not specific to the `user.updated` event and can be used for any webhook event you choose to listen to. - - - - - ```ts {{ filename: 'app/api/webhooks/route.ts' }} - import { Webhook } from 'svix' - import { headers } from 'next/headers' - import { WebhookEvent } from '@clerk/nextjs/server' - - export async function POST(req: Request) { - // You can find this in the Clerk Dashboard -> Webhooks -> choose the endpoint - const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET - - if (!WEBHOOK_SECRET) { - throw new Error('Please add WEBHOOK_SECRET from Clerk Dashboard to .env or .env.local') - } - - // Get the headers - const headerPayload = headers() - const svix_id = headerPayload.get('svix-id') - const svix_timestamp = headerPayload.get('svix-timestamp') - const svix_signature = headerPayload.get('svix-signature') - - // If there are no headers, error out - if (!svix_id || !svix_timestamp || !svix_signature) { - return new Response('Error occured -- no svix headers', { - status: 400, - }) - } - - // Get the body - const payload = await req.json() - const body = JSON.stringify(payload) - - // Create a new Svix instance with your secret. - const wh = new Webhook(WEBHOOK_SECRET) - - let evt: WebhookEvent - - // Verify the payload with the headers - try { - evt = wh.verify(body, { - 'svix-id': svix_id, - 'svix-timestamp': svix_timestamp, - 'svix-signature': svix_signature, - }) as WebhookEvent - } catch (err) { - console.error('Error verifying webhook:', err) - return new Response('Error occured', { - status: 400, - }) - } - - // Do something with the payload - // For this guide, you simply log the payload to the console - const { id } = evt.data - const eventType = evt.type - console.log(`Webhook with and ID of ${id} and type of ${eventType}`) - console.log('Webhook body:', body) - - return new Response('', { status: 200 }) - } - ``` - - ```ts {{ filename: 'pages/api/webhooks.ts' }} - import { Webhook } from 'svix' - import { WebhookEvent } from '@clerk/nextjs/server' - import { NextApiRequest, NextApiResponse } from 'next' - import { buffer } from 'micro' - - export const config = { - api: { - bodyParser: false, - }, - } - - export default async function handler(req: NextApiRequest, res: NextApiResponse) { - if (req.method !== 'POST') { - return res.status(405) - } - // You can find this in the Clerk Dashboard -> Webhooks -> choose the webhook - const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET - - if (!WEBHOOK_SECRET) { - throw new Error('Please add WEBHOOK_SECRET from Clerk Dashboard to .env or .env.local') - } - - // Get the Svix headers for verification - const svix_id = req.headers['svix-id'] as string - const svix_timestamp = req.headers['svix-timestamp'] as string - const svix_signature = req.headers['svix-signature'] as string - - // If there are no headers, error out - if (!svix_id || !svix_timestamp || !svix_signature) { - return res.status(400).json({ error: 'Error occured -- no svix headers' }) - } - - console.log('headers', req.headers, svix_id, svix_signature, svix_timestamp) - // Get the body - const body = (await buffer(req)).toString() - - // Create a new Svix instance with your secret. - const wh = new Webhook(WEBHOOK_SECRET) - - let evt: WebhookEvent - - // Attempt to verify the incoming webhook - // If successful, the payload will be available from 'evt' - // If the verification fails, error out and return error code - try { - evt = wh.verify(body, { - 'svix-id': svix_id, - 'svix-timestamp': svix_timestamp, - 'svix-signature': svix_signature, - }) as WebhookEvent - } catch (err) { - console.error('Error verifying webhook:', err) - return res.status(400).json({ Error: err }) - } - - // Do something with the payload - // For this guide, you simply log the payload to the console - const { id } = evt.data - const eventType = evt.type - console.log(`Webhook with and ID of ${id} and type of ${eventType}`) - console.log('Webhook body:', body) - - return res.status(200).json({ response: 'Success' }) - } - ``` - - - - - ```js {{ filename: 'clerkWebhookHandler.js' }} - import { Webhook } from 'svix' - import bodyParser from 'body-parser' - - app.post( - '/api/webhooks', - // This is a generic method to parse the contents of the payload. - // Depending on the framework, packages, and configuration, this may be - // different or not required. - bodyParser.raw({ type: 'application/json' }), - async function (req, res) { - // You can find this in the Clerk Dashboard -> Webhooks -> choose the webhook - const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET - if (!WEBHOOK_SECRET) { - throw new Error('You need a WEBHOOK_SECRET in your .env') - } - - // Get the headers and body - const headers = req.headers - const payload = req.body - - // Get the Svix headers for verification - const svix_id = headers['svix-id'] - const svix_timestamp = headers['svix-timestamp'] - const svix_signature = headers['svix-signature'] - - // If there are no Svix headers, error out - if (!svix_id || !svix_timestamp || !svix_signature) { - return new Response('Error occured -- no svix headers', { - status: 400, - }) - } - - // Create a new Svix instance with your secret. - const wh = new Webhook(WEBHOOK_SECRET) - - let evt - - // Attempt to verify the incoming webhook - // If successful, the payload will be available from 'evt' - // If the verification fails, error out and return error code - try { - evt = wh.verify(payload, { - 'svix-id': svix_id, - 'svix-timestamp': svix_timestamp, - 'svix-signature': svix_signature, - }) - } catch (err) { - console.log('Error verifying webhook:', err.message) - return res.status(400).json({ - success: false, - message: err.message, - }) - } - - // Do something with the payload - // For this guide, you simply log the payload to the console - const { id } = evt.data - const eventType = evt.type - console.log(`Webhook with an ID of ${id} and type of ${eventType}`) - console.log('Webhook body:', evt.data) - - return res.status(200).json({ - success: true, - message: 'Webhook received', - }) - }, - ) - ``` - - - - ### Narrow the webhook event to get typing - - The `WebhookEvent` reflects all possible webhook types. You can narrow down the event to get the types inferred correctly for the event type you are working with. - - In the following example, the `if` statement will narrow the type to the `user.created` type and using `evt.data` will give you autocompletion and type safety for that event. - - ```ts {{ filename: 'app/api/webhooks/route.ts', del: [1, 2], ins: [[4, 6]] }} - console.log(`Webhook with and ID of ${id} and type of ${eventType}`) - console.log('Webhook body:', body) - - if (evt.type === 'user.created') { - console.log('userId:', evt.data.id) - } - ``` - - If you want to handle types yourself, you can import the following types from your backend SDK, such as `@clerk/nextjs/server`. - - - `DeletedObjectJSON` - - `EmailJSON` - - `OrganizationInvitationJSON` - - `OrganizationJSON` - - `OrganizationMembershipJSON` - - `SessionJSON` - - `SMSMessageJSON` - - `UserJSON` - - ### Test your webhook - - 1. Start your Next.js server. - 1. On your endpoint's settings page in the Clerk Dashboard, select the **Testing** tab. - 1. In the **Select event** dropdown, select `user.updated`. - 1. Select the **Send Example** button. - 1. Below that section, in the **Message Attempts** section, you should see a successful attempt with a status of `200`. - - #### Message failed - - If the message failed: - - 1. Select the message. - 1. Scroll down to the **Webhook Attempts** section. - 1. Select the arrow icon the left side. - 1. Investigate the error. Your solution is going to depend on the error message. See the [Debug your webhooks](/docs/integrations/webhooks/debug-your-webhooks) guide for more information. - - ### Trigger your webhook - - To trigger the `user.updated` event, you can do one of the following: - - 1. You can edit your user in the Dashboard. - 1. You can use the `` component in your application to edit your profile. - - Once you have updated a user, you should be able to see the webhook's payload logged to your terminal. You can also check the Clerk Dashboard to see the webhook attempt, the same way you did when [testing the webhook](#test-your-webhook). - - ### Wrap up - - In this guide, you learned how to create a Clerk webhook using Svix. You created a webhook in the Clerk Dashboard to listen for the `user.updated` event and created a Route Handler for your webhook endpoint to verify the webhook signature and receive the payload. You tested the webhook locally using ngrok and the Clerk Dashboard to ensure it was configured properly. And lastly, you added logic to your application to actually trigger the `user.updated` event. Now, you can do whatever you want with the webhook payload, such as sending a notification to your users, updating a database, or anything else you can think of. - diff --git a/docs/maintenance-mode.mdx b/docs/maintenance-mode.mdx index 0e2c5dfd55..21f085f3aa 100644 --- a/docs/maintenance-mode.mdx +++ b/docs/maintenance-mode.mdx @@ -3,14 +3,36 @@ title: Maintenance Mode description: Learn about Clerk's Maintenance Mode. --- -**Maintenance Mode** is a special operational state designed to ensure minimal disruption to signed-in users during critical database upgrades or outages. +> [!IMPORTANT] +> Maintenance mode will be deprecated in 2025 as we upgrade our infrastructure. + +Once or twice per year, Clerk undergoes maintenance on its infrastructure and enters **Maintenance Mode**. During this time, users who are already signed in will not be signed out, and will continue to have access to your app. However, new sign-ups, sign-ins and user mutations will return an error. **Maintenance Mode** is a special operational state designed to minimize disruption for signed-in users during critical database upgrades or outages. ## Production instances -Mutation methods (`POST`, `PATCH`, `PUT`, `DELETE`) will be rejected with a `503 Service Unavailable` status, along with an error message informing users that the system is temporarily unavailable. This includes all sign-up and sign-in attempts. Clerk's prebuilt components and the hosted Account Portal will display errors for these requests. +Mutation methods (`POST`, `PATCH`, `PUT`, `DELETE`) will be rejected with a `SystemUnderMaintenance` error. This includes all new sign-ups and sign-ins. + +Active sessions, and session refresh requests **are not** affected. This applies to `GET` requests as well as session refresh requests ([`/touch`](/docs/reference/frontend-api/tag/Sessions#operation/touchSession) and [`/tokens`](/docs/reference/frontend-api/tag/Sessions#operation/createSessionToken) endpoints). Users who are already signed in will not be signed out and will continue to have access to your app. However, any mutations to their user or org data will return the same `SystemUnderMaintenance` error. + +### API errors + +All mutations from both the Frontend API and the Backend API will return the following `SystemUnderMaintenance` error. + +```json +// 503 StatusServiceUnavailable +{ + "shortMessage": "System under maintenance", + "longMessage": "We are currently undergoing maintenance and only essential operations are permitted. We will be back shortly.", + "code": "maintenance_mode" +} +``` + +### UI components + +During **Maintenance Mode**, Clerk's UI components will display the following error for sign-ins, sign-ups, and all mutations to user and org data. -GET requests, as well as session refresh requests ([`/touch`](/docs/reference/frontend-api/tag/Sessions#operation/touchSession) and [`/tokens`](/docs/reference/frontend-api/tag/Sessions#operation/createSessionToken) endpoints), aren't affected. Users with active sessions (already signed in) will not be signed out, and will continue to have access to your app. However, any mutations to their user or org data will return the same `503` error. +![The \ component with a maintenance mode error.](/docs/images/maintenance-mode/maintenance-mode-error-sm.png) ## Development instances -During this period, development instances will experience full downtime. Users will be unable to sign up or in, and already signed-in users will be signed out. +For development instances, all requests will return a `SystemUnderMaintenance ` error, and the instance will be completely unavailable. diff --git a/docs/manifest.json b/docs/manifest.json index 4711aba8e9..5cc863fd1e 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -35,7 +35,11 @@ "href": "/docs/quickstarts/remix", "icon": "remix" }, - { "title": "Astro", "href": "/docs/quickstarts/astro", "icon": "astro" }, + { + "title": "Astro", + "href": "/docs/quickstarts/astro", + "icon": "astro" + }, { "title": "TanStack Start", "tag": "(Beta)", @@ -68,7 +72,15 @@ "title": "Expo", "href": "/docs/quickstarts/expo" }, - { "title": "iOS", "tag": "(Beta)", "href": "/docs/quickstarts/ios" } + { + "title": "iOS", + "tag": "(Beta)", + "href": "/docs/quickstarts/ios" + }, + { + "title": "Chrome Extension", + "href": "/docs/quickstarts/chrome-extension" + } ] ] }, @@ -104,10 +116,19 @@ "title": "Add custom onboarding to your authentication flow", "href": "/docs/guides/add-onboarding-flow" }, + { + "title": "Set up a waitlist", + "href": "/docs/guides/waitlist" + }, { "title": "Architecture scenarios", "href": "/docs/guides/architecture-scenarios" }, + { + "title": "Add reverification for sensitive actions", + "tag": "(Beta)", + "href": "/docs/guides/reverification" + }, { "title": "Routing in Clerk", "href": "/docs/guides/routing" @@ -224,6 +245,18 @@ ] ] }, + { + "title": "Waitlist Component", + "items": [ + [ + { + "title": "``", + "wrap": false, + "href": "/docs/components/waitlist" + } + ] + ] + }, { "title": "Control Components", "items": [ @@ -495,40 +528,62 @@ ] }, { - "title": "SAML", + "title": "Enterprise Connections", "items": [ [ { "title": "Overview", - "href": "/docs/authentication/saml/overview" + "href": "/docs/authentication/enterprise-connections/overview" }, { "title": "Authentication flows", - "href": "/docs/authentication/saml/authentication-flows" + "href": "/docs/authentication/enterprise-connections/authentication-flows" }, { "title": "Account linking", - "href": "/docs/authentication/saml/account-linking" - }, - { - "title": "Azure", - "href": "/docs/authentication/saml/azure" + "href": "/docs/authentication/enterprise-connections/account-linking" }, { - "title": "Google", - "href": "/docs/authentication/saml/google" - }, - { - "title": "Okta", - "href": "/docs/authentication/saml/okta" + "title": "Just-in-Time account provisioning", + "href": "/docs/authentication/enterprise-connections/jit-provisioning" }, { - "title": "Custom provider", - "href": "/docs/authentication/saml/custom-provider" + "title": "EASIE", + "items": [ + [ + { + "title": "Microsoft", + "href": "/docs/authentication/enterprise-connections/easie/microsoft" + }, + { + "title": "Google", + "href": "/docs/authentication/enterprise-connections/easie/google" + } + ] + ] }, { - "title": "Just-in-Time account provisioning", - "href": "/docs/authentication/saml/jit-provisioning" + "title": "SAML", + "items": [ + [ + { + "title": "Azure", + "href": "/docs/authentication/enterprise-connections/saml/azure" + }, + { + "title": "Google", + "href": "/docs/authentication/enterprise-connections/saml/google" + }, + { + "title": "Okta", + "href": "/docs/authentication/enterprise-connections/saml/okta" + }, + { + "title": "Custom provider", + "href": "/docs/authentication/enterprise-connections/saml/custom-provider" + } + ] + ] } ] ] @@ -560,8 +615,14 @@ "title": "Metadata", "href": "/docs/users/metadata" }, - { "title": "Invitations", "href": "/docs/users/invitations" }, - { "title": "User impersonation", "href": "/docs/users/user-impersonation" }, + { + "title": "Invitations", + "href": "/docs/users/invitations" + }, + { + "title": "User impersonation", + "href": "/docs/users/user-impersonation" + }, { "title": "Create users", "href": "/docs/users/creating-users" @@ -624,6 +685,10 @@ { "title": "Organization workspaces", "href": "/docs/organizations/organization-workspaces" + }, + { + "title": "Create organizations on behalf of users", + "href": "/docs/organizations/create-orgs-for-users" } ] ] @@ -700,7 +765,7 @@ "href": "/docs/backend-requests/making/custom-session-token" }, { - "title": "JWT Templates", + "title": "JWT templates", "href": "/docs/backend-requests/making/jwt-templates" } ] @@ -767,6 +832,34 @@ } ] ] + }, + { + "title": "Webhooks", + "collapse": true, + "items": [ + [ + { + "title": "Overview", + "href": "/docs/webhooks/overview" + }, + { + "title": "Sync Clerk data to your application with webhooks", + "href": "/docs/webhooks/sync-data" + }, + { + "title": "Handling webhooks with Inngest", + "href": "/docs/webhooks/inngest" + }, + { + "title": "Send webhooks to Loops", + "href": "/docs/webhooks/loops" + }, + { + "title": "Debug your webhooks", + "href": "/docs/webhooks/debug-your-webhooks" + } + ] + ] } ] ] @@ -832,7 +925,10 @@ ] ] }, - { "title": "Localization", "href": "/docs/customization/localization" }, + { + "title": "Localization", + "href": "/docs/customization/localization" + }, { "title": "Custom Pages", "collapse": true, @@ -1306,6 +1402,10 @@ "title": "Set up a staging environment", "href": "/docs/deployments/set-up-staging" }, + { + "title": "Deploy a Chrome Extension to production", + "href": "/docs/deployments/deploy-chrome-extension" + }, { "title": "Deploy an Expo app to production", "href": "/docs/deployments/deploy-expo" @@ -1380,33 +1480,6 @@ "title": "Overview", "href": "/docs/integrations/overview" }, - { - "title": "Webhooks", - "items": [ - [ - { - "title": "Overview", - "href": "/docs/integrations/webhooks/overview" - }, - { - "title": "Sync Clerk data to your application with webhooks", - "href": "/docs/integrations/webhooks/sync-data" - }, - { - "title": "Handling webhooks with Inngest", - "href": "/docs/integrations/webhooks/inngest" - }, - { - "title": "Send webhooks to Loops", - "href": "/docs/integrations/webhooks/loops" - }, - { - "title": "Debug your webhooks", - "href": "/docs/integrations/webhooks/debug-your-webhooks" - } - ] - ] - }, { "title": "Databases", "items": [ @@ -1848,6 +1921,12 @@ "title": "`useOrganizationList()`", "wrap": false, "href": "/docs/references/react/use-organization-list" + }, + { + "title": "`useReverification()`", + "tag": "(Beta)", + "wrap": false, + "href": "/docs/references/react/use-reverification" } ] ] @@ -1878,6 +1957,10 @@ "title": "Organization methods", "href": "/docs/references/javascript/clerk/organization-methods" }, + { + "title": "Waitlist methods", + "href": "/docs/references/javascript/clerk/waitlist-methods" + }, { "title": "Redirect methods", "href": "/docs/references/javascript/clerk/redirect-methods" @@ -2106,6 +2189,10 @@ "title": "SessionStatus", "href": "/docs/references/javascript/types/session-status" }, + { + "title": "SessionVerification", + "href": "/docs/references/javascript/types/session-verification" + }, { "title": "SignInFirstFactor", "href": "/docs/references/javascript/types/sign-in-first-factor" @@ -2144,6 +2231,43 @@ ] ] }, + { + "title": "Chrome Extension", + "collapse": true, + "icon": "chrome", + "items": [ + [ + { + "title": "Overview", + "href": "/docs/references/chrome-extension/overview" + }, + { + "title": "Guides", + "collapse": false, + "items": [ + [ + { + "title": "Add React Router", + "href": "/docs/references/chrome-extension/add-react-router" + }, + { + "title": "Sync auth status between your Chrome Extension and web app", + "href": "/docs/references/chrome-extension/sync-host" + }, + { + "title": "`createClerkClient()`", + "href": "/docs/references/chrome-extension/create-clerk-client" + }, + { + "title": "Configure a consistent CRX ID", + "href": "/docs/references/chrome-extension/configure-consistent-crx-id" + } + ] + ] + } + ] + ] + }, { "title": "Expo", "collapse": true, @@ -2207,11 +2331,24 @@ "icon": "apple", "items": [ [ - { "title": "Overview", "href": "/docs/references/ios/overview" }, - { "title": "`getToken()`", "href": "/docs/references/ios/get-token" }, + { + "title": "Overview", + "href": "/docs/references/ios/overview" + }, + { + "title": "`getToken()`", + "href": "/docs/references/ios/get-token" + }, { "title": "Guides", - "items": [[{ "title": "Sign in with Apple", "href": "/docs/references/ios/sign-in-with-apple" }]] + "items": [ + [ + { + "title": "Sign in with Apple", + "href": "/docs/references/ios/sign-in-with-apple" + } + ] + ] } ] ] @@ -2241,7 +2378,14 @@ "title": "Express", "collapse": true, "icon": "expressjs", - "items": [[{ "title": "Overview", "href": "/docs/references/express/overview" }]] + "items": [ + [ + { + "title": "Overview", + "href": "/docs/references/express/overview" + } + ] + ] }, { "title": "Remix", @@ -2279,7 +2423,10 @@ "tag": "(Beta)", "items": [ [ - { "title": "Overview", "href": "/docs/references/tanstack-start/overview" }, + { + "title": "Overview", + "href": "/docs/references/tanstack-start/overview" + }, { "title": "General references", "items": [ @@ -2346,7 +2493,10 @@ "icon": "astro", "items": [ [ - { "title": "Overview", "href": "/docs/references/astro/overview" }, + { + "title": "Overview", + "href": "/docs/references/astro/overview" + }, { "title": "UI Frameworks", "items": [ @@ -3029,11 +3179,26 @@ "icon": "code-bracket", "items": [ [ - { "title": "Overview", "href": "/docs/references/sdk/overview" }, - { "title": "Terminology", "href": "/docs/references/sdk/terminology" }, - { "title": "Philosophy", "href": "/docs/references/sdk/philosophy" }, - { "title": "Conventions", "href": "/docs/references/sdk/conventions" }, - { "title": "SDK Types", "href": "/docs/references/sdk/types" }, + { + "title": "Overview", + "href": "/docs/references/sdk/overview" + }, + { + "title": "Terminology", + "href": "/docs/references/sdk/terminology" + }, + { + "title": "Philosophy", + "href": "/docs/references/sdk/philosophy" + }, + { + "title": "Conventions", + "href": "/docs/references/sdk/conventions" + }, + { + "title": "SDK Types", + "href": "/docs/references/sdk/types" + }, { "title": "Guides", "items": [ diff --git a/docs/manifest.schema.json b/docs/manifest.schema.json index 1bf5173f71..d8178bddf0 100644 --- a/docs/manifest.schema.json +++ b/docs/manifest.schema.json @@ -101,6 +101,7 @@ "c-sharp", "chart", "checkmark-circle", + "chrome", "clerk", "code-bracket", "cog-6-teeth", diff --git a/docs/organizations/create-orgs-for-users.mdx b/docs/organizations/create-orgs-for-users.mdx new file mode 100644 index 0000000000..f66fe1c439 --- /dev/null +++ b/docs/organizations/create-orgs-for-users.mdx @@ -0,0 +1,41 @@ +--- +title: Create organizations on behalf of users +description: Learn how to architect your application to create organizations on users' behalf without running into rate limits and billing issues. +--- + +In some cases, you may want the onboarding process for your app to include creating an organization on the user's behalf. This could be beneficial for several reasons, such as: + +- You'd like your users to be manually onboarded by sales staff who will send invites to join via an organization created for them. +- Your app only makes sense if the user is part of an organization, so you want to create the organization on their behalf as part of onboarding. +- You'd like to have an "admin account" that has access to all organizations across your app and can achieve this by creating an organization for the user with an admin account, rather than allowing the user to create their own organization. + +If this aligns with your use case, this guide will walk you through architecting your app to avoid unexpected rate limits or billing issues, which can be a common problem when creating organizations on behalf of users. + +## Recommended: require users to create orgs during onboarding + +The recommended approach is to implement an [onboarding flow](/docs/guides/add-onboarding-flow) in which it's required to create an organization before the user is able to access the app. You can use tools like the [`` component](/docs/components/organization/create-organization) to allow the user to create and name their own organization, or you can use the [Backend API](/docs/reference/backend-api/tag/Organizations#operation/CreateOrganization){{ target: '_blank' }} or a backend SDK, such as the [JS Backend SDK](/docs/references/backend/organization/create-organization), to create an organization on the user's behalf. + +If you'd like to have the onboarding flow include inviting users via email, use the [invitation feature](/docs/users/invitations). The flow would look like this: + +- User receives an invitation via email to join your app. +- User visits the invitation link, registers an account, and enters the onboarding flow. +- User creates an organization as part of the onboarding flow, and can invite other users if needed. +- The user can now access your app and is part of an org. + +If you'd like to enable users to join an existing org that matches their email domain (if one exists) as an alternative to creating a new organization, use the [verified domains](/docs/organizations/verified-domains) feature. + +## Not recommended: use an admin account to create organizations for users + +Although it may seem like a reasonable option, it's strongly recommended not to use a single admin account to create organizations on the behalf of users. Generally, this is because it can create **unexpectedly high costs** due to [the way that organizations are billed](/docs/organizations/overview#monthly-active-organization-mao). + +Let's walk through an example to see why. + +Imagine you have an admin account configured to create organizations on a user's behalf during onboarding and then sends an invitation to the user to join the organization. When the user accepts the invitation, the organization will have their account plus the admin account in it. At that point, the organization has two monthly active users (MAUs), which makes it a **billable** organization. All [Clerk plans](https://clerk.com/pricing) come with 100 active organizations included for free, but over that limit, organizations are billed at $1 per month. In this case, for every user that is created in your app, they have an active organization automatically, because of the fact that the admin account is also in the organization. This tends to result in much higher costs than if users' organizations are created without an admin account included, since orgs with only one active user are not billable. Additionally, it's generally a nicer experience for users not to have extra admin accounts in their organizations. + +If you have an architecture scenario that isn't covered here or feel that it's critical to create organizations using an admin account, contact [support@clerk.com](mailto:support@clerk.com) for help. + +## Grant a user access to all orgs + +The simplest way to grant someone on your team access to all orgs in your app is to add them as a member to your [organization workspace](/docs/organizations/organization-workspaces) in the Clerk Dashboard. Members of your organization workspace, also known as collaborators, can view all of the orgs for each of your apps and perform administrative actions, such as adding or removing members, renaming an org, or deleting an org. + +If this isn't an option, you can use the [Backend API](/docs/reference/backend-api){{ target: '_blank' }} or a backend SDK, such as the [JS Backend SDK](/docs/references/backend/overview), along with [roles and permissions](/docs/organizations/roles-permissions) to create a custom admin dashboard where authorized users can take adminstrative actions for orgs. diff --git a/docs/organizations/create-roles-permissions.mdx b/docs/organizations/create-roles-permissions.mdx index e42d650e68..5095350ea3 100644 --- a/docs/organizations/create-roles-permissions.mdx +++ b/docs/organizations/create-roles-permissions.mdx @@ -7,21 +7,21 @@ In the Clerk Dashboard, you can create roles, assign permissions to them, and ch ## Create a new role for your organization -1. In your Clerk Dashboard, navigate to [**Organization Settings**](https://dashboard.clerk.com/last-active?path=organizations-settings) and select the **roles** tab. +1. In the Clerk Dashboard, navigate to [**Roles**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles) 1. Select **Create new role**. 1. Give the role a name, a key to reference it by in the format `org:`, and a description. 1. Select **Create role**. ## Create a new permission for your organization -1. In your Clerk Dashboard, navigate to [**Organization Settings**](https://dashboard.clerk.com/last-active?path=organizations-settings) and select the **Permissions** tab. +1. In the Clerk Dashboard, navigate to [**Permissions**](https://dashboard.clerk.com/last-active?path=organizations-settings/permissions). 1. Select **Create new permission**. 1. Give the permission a name, a key to reference it by in the format `org::`, and a description. 1. Select **Create permission**. -## Change a user’s role in an organization +## Change a user's role in an organization -1. In your Clerk Dashboard, navigate to [**Organizations**](https://dashboard.clerk.com/last-active?path=organizations) and select an organization. +1. In the top in the Clerk Dashboard, select [**Organizations**](https://dashboard.clerk.com/last-active?path=organizations) and select an organization. 1. Select the **Members** tab. 1. In the list of members, find the one whose role you want to change. 1. Select another role from their role dropdown. @@ -30,6 +30,6 @@ In the Clerk Dashboard, you can create roles, assign permissions to them, and ch You cannot delete a role that is still assigned to members of an organization. Change the members to a different role before completing the following steps. -1. In your Clerk Dashboard, navigate to [**Organization Settings**](https://dashboard.clerk.com/last-active?path=organizations-settings) and select the **Roles** tab. +1. In the Clerk Dashboard, navigate to [**Roles**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles). 1. Select the "..." menu next to the role. 1. Select **Delete role**. diff --git a/docs/organizations/creator-role.mdx b/docs/organizations/creator-role.mdx index 08f1f9205d..1390b7c756 100644 --- a/docs/organizations/creator-role.mdx +++ b/docs/organizations/creator-role.mdx @@ -16,9 +16,8 @@ The **Creator** role must _at least_ have the following [System Permissions](/do To reassign the **Creator** role: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=organizations-settings/roles). -1. In the top navigation, select **Configure**. Then in the sidebar, under **Organization Management**, select **Roles and Permissions**. -1. Select the **Roles** tab. [Create a new role](/docs/organizations/create-roles-permissions#create-a-new-role-for-your-organization) or use an existing role from the list. +1. In the Clerk Dashboard, navigate to [**Roles**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles). +1. [Create a new role](/docs/organizations/create-roles-permissions#create-a-new-role-for-your-organization) or use an existing role from the list. 1. Ensure that **Manage members**, **Read members**, and **Delete organization** system permissions are selected for the role. 1. Open the "..." menu for the role. 1. From the dropdown, select the **Set as Creator role** option. diff --git a/docs/organizations/default-role.mdx b/docs/organizations/default-role.mdx index 91f965ff88..eead61555c 100644 --- a/docs/organizations/default-role.mdx +++ b/docs/organizations/default-role.mdx @@ -10,8 +10,7 @@ You cannot delete an organization role if it is used as the organization **Defau To reassign the **Default** role: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=organizations-settings/roles). -1. In the top navigation, select **Configure**. Then in the sidebar, under **Organization Management**, select **Roles and Permissions**. -1. Select the **Roles** tab. [Create a new role](/docs/organizations/create-roles-permissions#create-a-new-role-for-your-organization) or use an existing role from the list. +1. In the Clerk Dashboard, navigate to [**Roles**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles). +1. [Create a new role](/docs/organizations/create-roles-permissions#create-a-new-role-for-your-organization) or use an existing role from the list. 1. Open the "..." menu for the role. 1. From the dropdown, select the **Set as Default role** option. diff --git a/docs/organizations/invitations.mdx b/docs/organizations/invitations.mdx index 0f7a9fec80..bac4c3d7ae 100644 --- a/docs/organizations/invitations.mdx +++ b/docs/organizations/invitations.mdx @@ -5,7 +5,7 @@ description: Learn how to invite users to your organization. Organization invitations allow you to add new members to your organization, granting them access to organization-specific features and resources. -Once you create an invitation, Clerk sends an email to the invited user with a unique invitation link. When the user visits the organization invitation link, they will be redirected to the [Account Portal sign-in page](/docs/customization/account-portal/overview#sign-in). If the user is already signed in, they will be redirected to your application's homepage (`/`). If you want to redirect the user to a specific page in your application, you can [specify a redirect URL when creating the invitation.](#redirect-url) +Once you create an invitation, Clerk sends an email to the invited user with a unique invitation link. When the user visits the organization invitation link, they will be redirected to the [Account Portal sign-in page](/docs/customization/account-portal/overview#sign-in). If the user is already signed in, they will be redirected to your application's homepage (`/`). If you want to redirect the user to a specific page in your application, you can [specify a redirect URL when creating the invitation](#redirect-url). ## Create an invitation @@ -28,11 +28,11 @@ Use the following tabs to see examples for each method. The following example demonstrates how to create an organization invitation using cURL. - Replace the `` with the ID of the organization you want to invite the user to. Replace the `user_123` with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Your secret key is already injected into the code snippet. + Replace the `` with the ID of the organization you want to invite the user to. Replace the `user_123` with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Your Secret Key is already injected into the code snippet. - Replace the `` with the ID of the organization you want to invite the user to. Replace the `user_123` with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Replace `YOUR_SECRET_KEY` with your Clerk secret key. You can find your secret key in the Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. + Replace the `` with the ID of the organization you want to invite the user to. Replace the `user_123` with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Replace `YOUR_SECRET_KEY` with your Clerk Secret Key. You can find your Secret Key on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. ```bash {{ filename: 'terminal' }} @@ -49,7 +49,7 @@ Use the following tabs to see examples for each method. -Check out [the Backend API reference](https://clerk.com/docs/reference/backend-api/tag/Organization-Invitations#operation/CreateOrganizationInvitation) to see an example of the response. +See the [Backend API reference](/docs/reference/backend-api/tag/Organization-Invitations#operation/CreateOrganizationInvitation){{ target: '_blank' }} for an example of the response. ### Redirect URL @@ -68,7 +68,7 @@ curl 'https://api.clerk.com/v1/organizations//invitations' Once the user visits the invitation link, they will be redirected to the page you specified. On that page, you must handle the authentication flow in your code. You can either embed the [`](/docs/components/authentication/sign-in) component or, if the prebuilt component doesn't meet your needs or you require more control over the logic, you can build a [custom flow](/docs/organizations/accept-organization-invitations). > [!TIP] -> For testing redirect URLs in your development environment, you can pass your port (`http://localhost:3000`). If you'd like to use Clerk's Account Portal, pass your Clerk Frontend API URL as the base URL. For example, `https://prepared-phoenix-98.clerk.accounts.dev/sign-up` redirects the user to the Account Portal sign-up page. You can find your Frontend API URL in the Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. In the left sidebar, select **Show API URLs**. +> To test redirect URLs in your development environment, you can pass your port (`http://localhost:3000`). If you'd like to use Clerk's Account Portal, pass your Clerk Frontend API URL as the base URL. For example, `https://prepared-phoenix-98.clerk.accounts.dev/sign-up` redirects the user to the Account Portal sign-up page. You can find your Frontend API URL on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. In the left sidebar, select **Show API URLs**. ### Invitation metadata @@ -79,11 +79,11 @@ To add metadata to an invitation, you can use the `public_metadata` property whe The following example demonstrates how to create an invitation with metadata using cURL. - Replace the `` with the ID of the organization you want to invite the user to. Replace the `user_123` with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Your secret key is already injected into the code snippet. + Replace the `` with the ID of the organization you want to invite the user to. Replace the `user_123` with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Your Secret Key is already injected into the code snippet. - Replace the `` with the ID of the organization you want to invite the user to. Replace the `user_123` with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Replace `YOUR_SECRET_KEY` with your Clerk secret key. You can find your secret key in the Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. + Replace the `` with the ID of the organization you want to invite the user to. Replace the `user_123` with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Replace `YOUR_SECRET_KEY` with your Clerk Secret Key. You can find your Secret Key on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. ```bash @@ -113,11 +113,11 @@ You can either use a cURL command or Clerk's [JavaScript Backend SDK](/docs/refe The following example demonstrates how to revoke an invitation using cURL. - Replace the `` with the ID of the organization you want to revoke the invitation from. Replace the `` with the ID of the invitation you want to revoke. Replace `user_123` with the ID of the user who is revoking the invitation. Your secret key is already injected into the code snippet. + Replace the `` with the ID of the organization you want to revoke the invitation from. Replace the `` with the ID of the invitation you want to revoke. Replace `user_123` with the ID of the user who is revoking the invitation. Your Secret Key is already injected into the code snippet. - Replace the `` with the ID of the organization you want to revoke the invitation from. Replace the `` with the ID of the invitation you want to revoke. Replace `user_123` with the ID of the user who is revoking the invitation. Replace `YOUR_SECRET_KEY` with your Clerk secret key. You can find your secret key in the Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. + Replace the `` with the ID of the organization you want to revoke the invitation from. Replace the `` with the ID of the invitation you want to revoke. Replace `user_123` with the ID of the user who is revoking the invitation. Replace `YOUR_SECRET_KEY` with your Clerk Secret Key. You can find your Secret Key on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. ```bash {{ filename: 'terminal' }} diff --git a/docs/organizations/organization-workspaces.mdx b/docs/organizations/organization-workspaces.mdx index 2bea196637..2f6239c2bb 100644 --- a/docs/organizations/organization-workspaces.mdx +++ b/docs/organizations/organization-workspaces.mdx @@ -12,23 +12,24 @@ This guide will walk you through how to use the Clerk Dashboard to create an org ## Create an organization workspace -1. Navigate to the [Clerk Dashboard](https://clerk.com/dashboard). -1. In the top left navigation, select the workspace (such as **Personal account**) and select **Create organization**. A modal will appear. -1. Create an organization by providing a name and an optional organization logo. organization slugs are unique across instances, so common organization naming conventions may already be in use for another instance. -1. When finished, select **Create organization**. Clerk will set the newly created organization as the active organization. +1. In the top-left of the [Clerk Dashboard](https://dashboard.clerk.com), select the workspace dropdown. +1. Select **Create organization**. A modal will open. +1. Complete the form. Organization slugs are unique across all instances, so common naming conventions might already be in use by another instance. +1. Select **Create organization**. The newly created organization will be set the active organization. ## Invite collaborators to your organization workspace -1. Navigate to the [Clerk Dashboard](https://clerk.com/dashboard). -1. In the top left navigation, select the organization workspace and select the settings icon. A modal will appear with the organization profile. -1. Select the **Members** tab and select the **Invite** button. -1. Enter the email address of the collaborator you wish to invite and select the role you wish to assign to the collaborator. If inviting multiple collaborators at a time, ensure email addresses are separated by spaces or commas. +1. In the top-left of the [Clerk Dashboard](https://dashboard.clerk.com), select the workspace dropdown. +1. Select **Manage**. A modal will open showing the organization's information. +1. In the left nav, select **Members**. +1. Select **Invite**. +1. In the **Invite new members** form, enter the email of the user you want to invite and select the role to assign. 1. Select **Send invitations**. ## Transfer your applications between workspaces -1. Navigate to the [Clerk Dashboard](https://clerk.com/dashboard). -1. Select the workspace that contains the application you wish to transfer. -1. Select the application you wish to transfer. +1. In the top-left of the [Clerk Dashboard](https://dashboard.clerk.com), select the workspace dropdown. +1. Select the workspace that has the application you want to transfer. 1. In the navigation sidebar, select [**Settings**](https://dashboard.clerk.com/last-active?path=settings). -1. Select **Transfer ownership** and follow the instructions. +1. Select **Transfer ownership**. A modal will open. +1. Complete the form and select **Transfer ownership**. The page will redirect to the **Applications** page and show the transferred application. diff --git a/docs/organizations/overview.mdx b/docs/organizations/overview.mdx index bcccaf36ca..9674c0dfbc 100644 --- a/docs/organizations/overview.mdx +++ b/docs/organizations/overview.mdx @@ -6,7 +6,7 @@ description: Learn about how to create and manage Clerk organizations and their 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. > [!NOTE] -> To explore organizations in Clerk, check out this demo repo: +> To explore organizations in Clerk, see the demo repo: > [https://github.com/clerk/organizations-demo](https://github.com/clerk/organizations-demo) ## Enable organizations in your application @@ -15,15 +15,14 @@ Organizations are disabled by default. To enable organizations: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=organizations-settings). -1. In the navigation sidebar, select **Organizations Settings**. +1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/last-active?path=organizations-settings) page. 1. Toggle on **Enable Organizations**. Once organizations are enabled, you will be presented with the default settings, roles, and permissions that are applied to all organizations in that application instance. The following sections will explain these settings in more detail. ### Roles and permissions -Roles determine a user's level of access and permissions within an organization. [Learn more about how roles and permissions work and how to create your own with Clerk.](/docs/organizations/roles-permissions) +Roles determine a user's level of access and permissions within an organization. Learn more about [how roles and permissions work and how to create your own with Clerk](/docs/organizations/roles-permissions). ### Membership limit @@ -37,8 +36,7 @@ If you have the Pro plan, you can set the membership limit to unlimited. You can also change this limit on a per-organization basis: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=organizations). -1. In the navigation sidebar, select **Organizations**. +1. In the top in the Clerk Dashboard, select [**Organizations**](https://dashboard.clerk.com/last-active?path=organizations). 1. Select the organization you want to update. 1. In the **Membership limit** section, update the membership limit. Note that this will not apply to organizations that already exist. @@ -82,7 +80,7 @@ If you would like to hide personal workspaces and require users to always have a ## Create an organization -[You can create organizations in the Clerk Dashboard](#application-owner), or [your end users can create organizations in your application.](#application-user) +[You can create organizations in the Clerk Dashboard](#application-owner), or [your end users can create organizations in your application](#application-user). > [!WARNING] > Clerk automatically deletes organizations that have no members after one hour. @@ -91,8 +89,7 @@ If you would like to hide personal workspaces and require users to always have a To create an organization in the Clerk Dashboard: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=organizations). -1. In the navigation sidebar, select **Organizations**. +1. In the top in the Clerk Dashboard, select [**Organizations**](https://dashboard.clerk.com/last-active?path=organizations). 1. Select the **Create Organization** button. 1. Enter the organization's name and slug. The slug is a unique identifier for the organization and is used in URLs. Select the organization's owner from the list of users in your application. The owner is the user who will be the organization's admin. @@ -110,28 +107,26 @@ With the Pro plan: - In development instances, you can have an unlimited number of MAOs in a single Clerk application _for free_. Each MAO can have an unlimited number of members. - In production instances, you can have up to 100 MAOs in a single Clerk application _for free_. Each MAO after the first 100 costs $1.00 per month. Each MAO can have an unlimited number of members. -For more details on pricing, see [our pricing page](/pricing){{ target: '_blank' }}. +For more information on pricing, see the [pricing page](/pricing){{ target: '_blank' }}. -If you need more organizations or custom pricing, please contact [our sales team](/contact/sales){{ target: '_blank' }} to upgrade to the Enterprise plan. +If you need more organizations or custom pricing, contact the [sales team](/contact/sales){{ target: '_blank' }} to upgrade to the Enterprise plan. ### Create an organization in your application By default, users have the permission to create organizations within your application. To configure this permission for all users: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=organizations-settings). -1. In the top navigation, select **Configure**. Then, in the sidebar, under **Organization management**, select **Settings**. +1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/last-active?path=organizations-settings) page. 1. At the bottom of the page, in the **Limit creation** section, enable/disable **Allow new users to create organizations**. You can also configure the number of organizations that can be created by each user. By default, each user can create an unlimited number of organizations. If you want to only configure this permission for a specific user, you can override it on a per-user basis on the user's profile page in the Clerk Dashboard: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=users). -1. In the top navigation, select **Users**. +1. In the top in the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users). 1. Select the user you want to update. 1. In the **User permissions** section, enable/disable **Allow user to create organizations**. When a user creates an organization, they become the organization's admin. As the organization's admin, they have full control over the organization, including the ability to update the organization's settings, invite users to join the organization, and manage the organization's members. -A single user within one of your applications can create _up to_ 100 organizations in that application. If you need users to be able to create more organizations than this, [reach out to support](/contact/support){{ target: '_blank' }} and you can have the limit raised. +A single user within one of your applications can create _up to_ 100 organizations in that application. If you need users to be able to create more organizations than this, [contact support](/contact/support){{ target: '_blank' }} to have the limit raised. The easiest way to allow users to create organizations is to use the [``](/docs/components/organization/create-organization) and/or [``](/docs/components/organization/organization-switcher) components. @@ -145,8 +140,7 @@ This feature requires that **Email address** is enabled as an [identifier](/docs To configure your application's **Email address** settings: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username). -1. In the navigation sidebar, select **User & Authentication > Email, Phone, Username**. +1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. 1. In the **Contact information** section, ensure that **Email address** is toggled on. 1. Next to **Email address**, select the settings icon to configure the email address settings. Here, at least **Require** should be toggled on. @@ -154,8 +148,7 @@ To configure your application's **Email address** settings: As the application owner, you have control over all of the organizations within your application - both those created by you and those created by your users. You can create, update, and delete organizations, as well as manage their members and settings. -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=organizations). -1. In the navigation sidebar, select **Organizations**. Here, you can view and manage all organizations within your application. +1. In the top in the Clerk Dashboard, select [**Organizations**](https://dashboard.clerk.com/last-active?path=organizations). Here, you can view and manage all organizations in your application. 1. Select a specific organization to view its details, members, and settings. Here, you can update the organization's name, slug, and logo. You can also set the organization's [membership limit](#how-many-organizations-can-i-create) and public and private metadata. For managing organizations in your application, Clerk provides a set of prebuilt components: diff --git a/docs/organizations/roles-permissions.mdx b/docs/organizations/roles-permissions.mdx index 190092cf4d..e5174ad494 100644 --- a/docs/organizations/roles-permissions.mdx +++ b/docs/organizations/roles-permissions.mdx @@ -21,7 +21,7 @@ For each instance, there are currently two default roles: ### Custom role -You can create up to 10 custom organization roles per application instance to meet your application needs. If you need more than 10 roles, reach out to [support@clerk.dev](mailto:support@clerk.dev). +You can create up to 10 custom organization roles per application instance to meet your application needs. If you need more than 10 roles, [contact support](/contact/support){{ target: '_blank' }}. Custom roles can be granted permissions and access. For example, you can create a new role of **Billing** (`org:billing`) which can be used to group users who belong to a specific department of the organization and have permission to manage credit card information, invoices, and other resources related to billing. diff --git a/docs/organizations/verified-domains.mdx b/docs/organizations/verified-domains.mdx index 0645b1f849..f434825539 100644 --- a/docs/organizations/verified-domains.mdx +++ b/docs/organizations/verified-domains.mdx @@ -13,8 +13,7 @@ Enabling verified domains applies to all organizations and cannot currently be m In order to enable this feature: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=organizations-settings) -1. In the navigation sidebar, select **Organizations Settings**. +1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/last-active?path=organizations-settings) page. 1. In the **Verified domains** section, check the **Enable verified domains** checkbox. 1. The following setting will appear: @@ -37,7 +36,7 @@ Domains can be verified through an email verification code sent to an email that An application instance may only have one verified domain of the same name, and an organization may only have one domain of the same name (verified or unverified). -You can create up to 10 domains per organization to meet your needs. If you need more than 10 domains, reach out to [support@clerk.dev](mailto:support@clerk.dev). +You can create up to 10 domains per organization to meet your needs. If you need more than 10 domains, [contact support](/contact/support){{ target: '_blank' }}. ### Custom flow diff --git a/docs/organizations/verify-user-permissions.mdx b/docs/organizations/verify-user-permissions.mdx index c4a73a3efc..1d0063c620 100644 --- a/docs/organizations/verify-user-permissions.mdx +++ b/docs/organizations/verify-user-permissions.mdx @@ -74,7 +74,7 @@ The following examples work for both SSR and CSR. The following example uses the `` component to only render the layout for users with the correct permission. If the user is not authorized, the component will not render its children. > [!WARNING] - > Be cautious when doing authorization checks in layouts, as these don't re-render on navigation, meaning the user session won't be checked on every route change. [Read more in the Next.js docs.](https://nextjs.org/docs/app/building-your-application/authentication#layouts-and-auth-checks) + > Be cautious when doing authorization checks in layouts, as these don't re-render on navigation, meaning the user session won't be checked on every route change. [Read more in the Next.js docs](https://nextjs.org/docs/app/building-your-application/authentication#layouts-and-auth-checks). ```tsx {{ filename: '/app/dashboard/settings/layout.tsx' }} import type { PropsWithChildren } from 'react' @@ -90,7 +90,7 @@ The following examples work for both SSR and CSR. The following example uses `has()` to inspect a user's permissions granularly. If the user doesn't have the correct permission, `has()` returns `false`, causing the component to return `null` instead of rendering its children. > [!WARNING] - > Be cautious when doing authorization checks in layouts, as these don't re-render on navigation, meaning the user session won't be checked on every route change. [Read more in the Next.js docs.](https://nextjs.org/docs/app/building-your-application/authentication#layouts-and-auth-checks) + > Be cautious when doing authorization checks in layouts, as these don't re-render on navigation, meaning the user session won't be checked on every route change. [Read more in the Next.js docs](https://nextjs.org/docs/app/building-your-application/authentication#layouts-and-auth-checks). ```tsx {{ filename: '/app/dashboard/settings/layout.tsx' }} import type { PropsWithChildren } from 'react' @@ -296,7 +296,7 @@ If you are not using React or any of the meta-frameworks we support, you can use ```tsx {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' - // Initialize Clerk with your Clerk publishable key + // Initialize Clerk with your Clerk Publishable Key const clerk = new Clerk('{{pub_key}}') await clerk.load() diff --git a/docs/quickstarts/astro.mdx b/docs/quickstarts/astro.mdx index 6c3eda1c7c..f1767b7ed2 100644 --- a/docs/quickstarts/astro.mdx +++ b/docs/quickstarts/astro.mdx @@ -54,12 +54,12 @@ description: Add authentication and user management to your Astro app with Clerk ### Set your Clerk API keys - Add the following keys to your `.env.local` file. These keys can always be retrieved from the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page of your Clerk Dashboard. + Add the following keys to your `.env.local` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. - 1. In the Clerk Dashboard, navigate to the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. - 1. In the **Quick Copy** section, copy your Clerk publishable and secret key. + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable and Secret Keys. 1. Paste your keys into your `.env.local` file. The final result should resemble the following: @@ -125,7 +125,7 @@ description: Add authentication and user management to your Astro app with Clerk - [``](/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/customization/account-portal/overview#sign-in) + - [``](/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/customization/account-portal/overview#sign-in). ```astro {{ filename: 'src/layouts/SiteLayout.astro' }} --- diff --git a/docs/quickstarts/chrome-extension.mdx b/docs/quickstarts/chrome-extension.mdx new file mode 100644 index 0000000000..fcc1493cae --- /dev/null +++ b/docs/quickstarts/chrome-extension.mdx @@ -0,0 +1,294 @@ +--- +title: Chrome Extension Quickstart +description: Add authentication and user management to your Chrome Extension with Clerk. +--- + + + - Create a new app with Plasmo + - Install `@clerk/chrome-extension` + - Set your Clerk API keys + - Add `` and Clerk components to your app + - Configure your app to use a consistent CRX ID + - Build, load, and test your 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#authenication-options) + + This guide will use a popup. + + ### Create a new app using the Plasmo framework + + [Plasmo](https://docs.plasmo.com/framework) is a browser extension framework that includes hot reloading and creating development and production extension builds easily from the same code. + + Plasmo strongly recommends using `pnpm`, so this guide will only use `pnpm`-based examples. + + The following command creates an app with Tailwind CSS preconfigured and with a `src/` directory. You can choose to remove one or both of those options. + + ```bash {{ filename: 'terminal' }} + pnpm create plasmo --with-tailwindcss --with-src clerk-chrome-extension + cd clerk-chrome-extension + ``` + + ### Install `@clerk/chrome-extension` + + Clerk's [Chrome Extension SDK](/docs/references/chrome-extension/overview) gives you access to prebuilt components, React hooks, and helpers to make user authentication easier. + + Add the SDK to your project: + + ```bash {{ filename: 'terminal' }} + pnpm add @clerk/chrome-extension + ``` + + ### Set your Clerk API keys + + Plasmo offers [several options](https://docs.plasmo.com/framework/env) for environment variable files, as the same codebase can be used for development and production builds, as well as for targeting different browsers. This guide uses `.env.development` and `.env.chrome` files. + + + Add the following keys to your `.env.development` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. + + + + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, select **Chrome Extension** and copy your Clerk Publishable Key and Frontend API URL. + 1. Paste your keys into your `.env.development` file. + + The final result should resemble the following: + + + ```env {{ filename: '.env.development' }} + PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} + CLERK_FRONTEND_API={{fapi_url}} + ``` + + ### Add `` to your app + + All Clerk hooks and components must be children of the [``](/docs/components/clerk-provider) component, which provides active session and user context. Wrap your app in the `` component and pass your Publishable Key as a prop. + + ```tsx {{ filename: 'src/popup.tsx', mark: [1, [7, 11], 15, 19] }} + import { ClerkProvider } from '@clerk/chrome-extension' + + import { CountButton } from '~features/count-button' + + import '~style.css' + + const PUBLISHABLE_KEY = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY + + if (!PUBLISHABLE_KEY) { + throw new Error('Please add the PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY to the .env.development file') + } + + function IndexPopup() { + return ( + +
+ +
+ + ) + } + + export default IndexPopup + ``` + + ### 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). + + - [``](/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/customization/account-portal/overview) + + ```tsx {{ filename: 'src/popup.tsx', mark: [[1, 7], [22, 29]] }} + import { + ClerkProvider, + SignInButton, + SignedIn, + SignedOut, + UserButton, + } from '@clerk/chrome-extension' + import { CountButton } from '~features/count-button' + + import '~style.css' + + const PUBLISHABLE_KEY = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY + + if (!PUBLISHABLE_KEY) { + throw new Error('Please add the PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY to the .env.development file') + } + + function IndexPopup() { + return ( + +
+
+ + + + + + +
+
+ +
+
+ + ) + } + + export default IndexPopup + ``` + + ### Update `` props for Chrome Extension navigation + + To avoid navigation errors, set the `afterSignOutUrl`, `signInFallbackRedirectUrl` and `signUpFallbackRedirectUrl` props for ``. Chrome Extensions don't use an `http` URL, such as `http://localhost:3000`. Instead, they use a `chrome-extension://` URL appended with an unique extension ID called a CRX ID. This URL is what you will pass to these props. + + ```tsx {{ filename: 'src/popup.tsx', mark: [14, [24, 26]] }} + import { + ClerkProvider, + SignInButton, + SignedIn, + SignedOut, + UserButton, + } from '@clerk/chrome-extension' + + import { CountButton } from '~features/count-button' + + import '~style.css' + + const PUBLISHABLE_KEY = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY + const EXTENSION_URL = chrome.runtime.getURL('.') + + if (!PUBLISHABLE_KEY) { + throw new Error('Please add the PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY to the .env.development file') + } + + function IndexPopup() { + return ( + +
+
+ + + + + + +
+
+ +
+
+ + ) + } + + export default IndexPopup + ``` + + ### Create a consistent CRX ID for your extension + + Chrome Extensions have a unique CRX ID that rotates by default, which can cause errors with the Clerk integration. To avoid these problems, ensure that you have a **consistent** CRX ID in both development and production for your extension by following these steps: + + 1. Visit Plasmo Itero's [Generate Keypairs](https://itero.plasmo.com/tools/generate-keypairs) tool. + 1. Select **Generate KeyPairs**. + 1. Save the **Private Key** somewhere secure in case you need it in the future. Save the **Public Key** and the **CRX ID** for the next steps. + + ### Create an `.env.chrome` file to store your public key + + Create an `.env.chrome` file and add your public key to it, as shown in the following example: + + ```env {{ filename: '.env.chrome' }} + CRX_PUBLIC_KEY= + ``` + + ### Edit your `package.json` to use the new public key + + Plasmo [uses the `package.json` to generate a `manifest.json` on build](https://docs.plasmo.com/framework#where-is-the-manifestjson-file), and allows for the use of environment variables in `package.json`. + + In your `package.json`, in the `manifest` object: + + - Set the `key` value to `"$CRX_PUBLIC_KEY"`. This helps configure the consistent CRX ID for your extension. + - Set the `permissions` array to include `"cookies"` and `"storage"`. `permissions` specifies which permissions your extension requires. + - Set/update the `host_permissions` array to include `"http://localhost/*"` and `"$CLERK_FRONTEND_API/*"`. `host_permissions` specifies which hosts, or websites, will have permission to sync auth state with your app. + + ```json {{ filename: 'package.json' }} + { + // The rest of your package.json file + "manifest": { + "key": "$CRX_PUBLIC_KEY", + "permissions": ["cookies", "storage"], + "host_permissions": ["http://localhost/*", "$CLERK_FRONTEND_API/*"] + } + } + ``` + + ### Use `pnpm dev` to start your development server and create a build + + Plasmo facilitates Chrome Extension development by automatically "hot loading" the app whenever you save a changed file in the project. This ensures the `build/chrome-mv3-dev` folder remains up to date. Without the plugin, you would need to manually execute the build command and reload your Chrome Extension after each change. Plasmo automates this process, streamlining development. + + Run the following command to start your development environment. This also creates the build in `build/chrome-mv3-dev`, and rebuilds when you make changes to the extension. + + ```bash {{ filename: 'terminal' }} + pnpm dev + ``` + + ### Load your Chrome Extension into your Chromium-based browser + + To load your Chrome Extension, follow these steps: + + 1. Open Chrome or a Chromium-based browser and navigate to `chrome://extensions`. + 1. In the top-right, enable **Developer mode**. + 1. In the top-left, select **Load unpacked**. + 1. Navigate to where your project is located and select the `build/chrome-mv3-dev` folder. Then select **Select**. Your extension will now be loaded and shown in the list of extensions. + 1. Confirm that the ID shown in your extension matches the CRX ID you saved [earlier](#create-a-consistent-crx-id-for-your-extension). + + ### Test your Chrome Extension + + In your Chrome browser, open the extension popup. Ensure that the `` appears, and that selecting it opens the `` modal. Sign in and ensure that the `` appears in the header. + + > [!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. + + +## Next steps + + + - [Add React Router](/docs/references/chrome-extension/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) + - Learn how to configure your Chrome Extension to sync user authentication with your web application. + + --- + + - [createClerkClient()](/docs/references/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/quickstarts/expo.mdx index 6724174f32..65d5069244 100644 --- a/docs/quickstarts/expo.mdx +++ b/docs/quickstarts/expo.mdx @@ -74,12 +74,12 @@ description: Add authentication and user management to your Expo app with Clerk. ### Set your Clerk API keys - Add your Clerk publishable key to your `.env` file. It can always be retrieved from the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page of your Clerk Dashboard. + Add your Clerk Publishable Key to your `.env` file. It can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. - 1. In the Clerk Dashboard, navigate to the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. - 1. In the **Quick Copy** section, copy your Clerk publishable key. + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable Key. 1. Paste your key into your `.env` file. The final result should resemble the following: @@ -91,7 +91,7 @@ description: Add authentication and user management to your Expo app with Clerk. ### Add `` to your root layout - The [``](/docs/components/clerk-provider) component wraps your app to provide active session and user context to Clerk's hooks and other components. You must pass your publishable key as a prop to the `` component. + The [``](/docs/components/clerk-provider) component wraps your app to provide active session and user context to Clerk's hooks and other components. You must pass your Publishable Key as a prop to the `` component. Clerk also provides [``](/docs/components/control/clerk-loaded), which won't render its children until the Clerk API has loaded. diff --git a/docs/quickstarts/express.mdx b/docs/quickstarts/express.mdx index 2e1148f957..dd3f092403 100644 --- a/docs/quickstarts/express.mdx +++ b/docs/quickstarts/express.mdx @@ -56,13 +56,12 @@ Learn how to integrate Clerk into your Express backend for secure user authentic ### Set your Clerk API keys - Add the following keys to your `.env` file. These keys can always be retrieved from the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page of your Clerk Dashboard. + Add the following keys to your `.env` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. - 1. Navigate to the Clerk Dashboard. - 1. In the navigation sidebar, select [API Keys](https://dashboard.clerk.com/last-active?path=api-keys). - 1. In the **Quick Copy** section, copy your Clerk publishable and secret key. + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable and Secret Keys. 1. Paste your keys into your `.env` file. The final result should resemble the following: diff --git a/docs/quickstarts/fastify.mdx b/docs/quickstarts/fastify.mdx index e41d30f720..1d760b5f72 100644 --- a/docs/quickstarts/fastify.mdx +++ b/docs/quickstarts/fastify.mdx @@ -62,16 +62,12 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic ### Set your Clerk API keys - Add the following keys to your `.env.local` file. These keys can always be - retrieved from the [API - Keys](https://dashboard.clerk.com/last-active?path=api-keys) page of your - Clerk Dashboard. + Add the following keys to your `.env.local` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. - 1. Navigate to the Clerk Dashboard. - 1. In the navigation sidebar, select [API Keys](https://dashboard.clerk.com/last-active?path=api-keys). - 1. In the **Quick Copy** section, copy your Clerk publishable and secret key. + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable and Secret Keys. 1. Paste your keys into your `.env` file. The final result should resemble the following: @@ -89,7 +85,7 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic The following example registers the plugin for all routes. To register the plugin for specific routes only, refer to the [**Using Clerk for specific pages only**](/docs/quickstarts/fastify#using-clerk-for-specific-routes-only) section. > [!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 details, refer to the [Fastify docs](https://fastify.dev/docs/latest/Guides/Getting-Started/#loading-order-of-your-plugins). + > 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). ```ts {{ filename: 'index.ts' }} import 'dotenv/config' diff --git a/docs/quickstarts/ios.mdx b/docs/quickstarts/ios.mdx index 22c50396d6..0cb4ffdf5a 100644 --- a/docs/quickstarts/ios.mdx +++ b/docs/quickstarts/ios.mdx @@ -18,7 +18,7 @@ description: Add authentication and user management to your iOS app with Clerk. > - Create a new Xcode project - Install the Clerk iOS SDK - - Configure `Clerk` with your publishable key + - Configure `Clerk` with your Publishable Key - Use Clerk to enable users to sign in and out of your application @@ -41,7 +41,7 @@ description: Add authentication and user management to your iOS app with Clerk. - Import `ClerkSDK`. - Add a new variable `clerk` marked with the `@ObservedObject` property wrapper. - Replace `ContentView()` with the below `ZStack`. - - Attach a `.task` modifier to the new `ZStack`. In the body of the task, configure `clerk` with your publishable key, and then load `clerk`. You can get your publishable key from the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page of the Clerk Dashboard. + - Attach a `.task` modifier to the new `ZStack`. In the body of the task, configure `clerk` with your Publishable Key, and then load `clerk`. You can get your Publishable Key from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. ```swift {{ filename: 'ClerkQuickstartApp.swift', mark: [2, 6, [10, 20]] }} import SwiftUI diff --git a/docs/quickstarts/javascript.mdx b/docs/quickstarts/javascript.mdx index 23eb217cbb..9feb90d979 100644 --- a/docs/quickstarts/javascript.mdx +++ b/docs/quickstarts/javascript.mdx @@ -85,15 +85,15 @@ Use the following tabs to choose your preferred method. ### Set your Clerk API keys - It's recommended to use environment variables to store your Clerk publishable key. In JavaScript projects, you can add these values in an `.env` file and load them into your app using a package like [`dotenv`](https://www.npmjs.com/package/dotenv). For Vite projects, environment variables in an `.env` file at the project root are automatically accessible through the [`import.meta.env` object](https://vitejs.dev/guide/env-and-mode.html#env-variables). + It's recommended to use environment variables to store your Clerk Publishable Key. In JavaScript projects, you can add these values in an `.env` file and load them into your app using a package like [`dotenv`](https://www.npmjs.com/package/dotenv). For Vite projects, environment variables in an `.env` file at the project root are automatically accessible through the [`import.meta.env` object](https://vitejs.dev/guide/env-and-mode.html#env-variables). - Add your Clerk publishable key to your `.env` file. It can always be retrieved from the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page of your Clerk Dashboard. + Add your Clerk Publishable Key to your `.env` file. It can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. - 1. In the Clerk Dashboard, navigate to the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. - 1. In the **Quick Copy** section, copy your Clerk publishable key. + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable Key. 1. Paste your key into your `.env` file. The final result should resemble the following: @@ -103,7 +103,7 @@ Use the following tabs to choose your preferred method. VITE_CLERK_PUBLISHABLE_KEY={{pub_key}} ``` - In your `main.js` file, import the publishable key using Vite's `import.meta.env` object. + In your `main.js` file, import the Publishable Key using Vite's `import.meta.env` object. ```js {{ filename: 'main.js' }} const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY @@ -111,7 +111,7 @@ Use the following tabs to choose your preferred method. ### Initialize Clerk - To initialize Clerk, import the `Clerk` class and instantiate it with your Clerk publishable key. Then, call the `load()` method, as shown in the following example: + To initialize Clerk, import the `Clerk` class and instantiate it with your Clerk Publishable Key. Then, call the `load()` method, as shown in the following example: ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' @@ -125,7 +125,7 @@ Use the following tabs to choose your preferred method. ``` > [!NOTE] - > Calling the `load()` method initializes Clerk. For more information on the `load()` method and what options you can pass to it, check out the [reference documentation](/docs/references/javascript/clerk/clerk#load). + > Calling the `load()` method initializes Clerk. For more information on the `load()` method and what options you can pass to it, see the [reference documentation](/docs/references/javascript/clerk/clerk#load). ### Add Clerk components to your app @@ -213,7 +213,7 @@ Use the following tabs to choose your preferred method. This ` + + + ``` + diff --git a/docs/references/javascript/organization-invitation.mdx b/docs/references/javascript/organization-invitation.mdx index c13f1e3dce..004d4752e0 100644 --- a/docs/references/javascript/organization-invitation.mdx +++ b/docs/references/javascript/organization-invitation.mdx @@ -84,7 +84,7 @@ The following example demonstrates how to revoke an organization invitation. It It assumes: - you have followed the [quickstart](/docs/quickstarts/javascript) in order to add Clerk to your JavaScript application -- you have [enabled the Organizations feature in your Clerk Dashboard](/docs/organizations/overview#enable-organizations-in-your-application) +- you have [enabled the Organizations feature in the Clerk Dashboard](/docs/organizations/overview#enable-organizations-in-your-application) ```js {{ filename: 'main.js', mark: [22, 23] }} import { Clerk } from '@clerk/clerk-js' diff --git a/docs/references/javascript/organization/domains.mdx b/docs/references/javascript/organization/domains.mdx index e5d7169e17..14e3d21c88 100644 --- a/docs/references/javascript/organization/domains.mdx +++ b/docs/references/javascript/organization/domains.mdx @@ -8,7 +8,7 @@ These methods on the [`Organization`](/docs/references/javascript/organization/o The following examples assume: - you have followed the [quickstart](/docs/quickstarts/javascript) in order to add Clerk to your JavaScript application -- you have [enabled the Organizations feature in your Clerk Dashboard](/docs/organizations/overview#enable-organizations-in-your-application) +- you have [enabled the Organizations feature in the Clerk Dashboard](/docs/organizations/overview#enable-organizations-in-your-application) - you have [enabled **Verified domains** for your organization](/docs/organizations/verified-domains) ## `createDomain()` diff --git a/docs/references/javascript/organization/invitations.mdx b/docs/references/javascript/organization/invitations.mdx index f77c96e025..09e1f11898 100644 --- a/docs/references/javascript/organization/invitations.mdx +++ b/docs/references/javascript/organization/invitations.mdx @@ -8,7 +8,7 @@ These methods on the [`Organization`](/docs/references/javascript/organization/o The following examples assume: - you have followed the [quickstart](/docs/quickstarts/javascript) in order to add Clerk to your JavaScript application -- you have [enabled the Organizations feature in your Clerk Dashboard](/docs/organizations/overview#enable-organizations-in-your-application) +- you have [enabled the Organizations feature in the Clerk Dashboard](/docs/organizations/overview#enable-organizations-in-your-application) ## `getInvitations()` @@ -54,7 +54,7 @@ function getInvitations( ```js {{ filename: 'main.js', mark: [12, 13] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -126,7 +126,7 @@ function inviteMember(params: InviteMemberParams): Promise ```js {{ filename: 'main.js', mark: [10, 11] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerk = new Clerk('{{pub_key}}') await clerk.load() @@ -189,7 +189,7 @@ function destroy(): Promise ```js {{ filename: 'main.js', mark: [10, 11] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerk = new Clerk('{{pub_key}}') await clerk.load() @@ -273,7 +273,7 @@ function setLogo(params: SetOrganizationLogoParams): Promise ```js {{ filename: 'main.js', mark: [14, 15] }} import { Clerk } from '@clerk/clerk-js' - // Initialize Clerk with your Clerk publishable key + // Initialize Clerk with your Clerk Publishable Key const clerk = new Clerk('{{pub_key}}') await clerk.load() @@ -448,7 +448,7 @@ An _experimental_ interface that includes information about a user's permission. ```js {{ filename: 'main.js', mark: [10, 11] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const clerk = new Clerk('{{pub_key}}') await clerk.load() diff --git a/docs/references/javascript/overview.mdx b/docs/references/javascript/overview.mdx index 47333013a7..55031d0fdf 100644 --- a/docs/references/javascript/overview.mdx +++ b/docs/references/javascript/overview.mdx @@ -9,7 +9,7 @@ While we typically recommend using one of our framework SDK's, such as [Clerk Re ## Installation -Please follow the instructions in the [ClerkJS quickstart](/docs/quickstarts/javascript) to add ClerkJS to your project. +Follow the instructions in the [ClerkJS quickstart](/docs/quickstarts/javascript) to add ClerkJS to your project. ## Usage diff --git a/docs/references/javascript/session.mdx b/docs/references/javascript/session.mdx index 9e4e9b87bf..51b016f679 100644 --- a/docs/references/javascript/session.mdx +++ b/docs/references/javascript/session.mdx @@ -1,5 +1,5 @@ --- -title: '`Session`' +title: Session description: The Session object is an abstraction over an HTTP session. It models the period of information exchange between a user and the server. --- @@ -14,7 +14,7 @@ In certain scenarios, a session might be replaced by another one. This is often All sessions that are **expired**, **removed**, **replaced**, **ended** or **abandoned** are not considered valid. > [!NOTE] -> For more details regarding the different session states, see our documentation on [session management](/docs/authentication/configuration/session-options). +> For more information regarding the different session states, see the [guide on session management](/docs/authentication/configuration/session-options). ## Properties @@ -96,6 +96,13 @@ All sessions that are **expired**, **removed**, **replaced**, **ended** or **aba --- + - `factorVerificationAge` + - `[number, number] | null` + + An array where each item represents the number of minutes since the last verification of a first or second factor: `[firstFactorAge, secondFactorAge]`. + + --- + - `actor` - `ActJWTClaim | null` @@ -182,7 +189,7 @@ function getToken(options?: GetTokenOptions): Promise ```js {{ filename: 'main.js', mark: [10, 11] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -238,6 +245,141 @@ type CheckAuthorizationParams = - `string` Accepts [permission](/docs/organizations/roles-permissions#permissions) key + + --- + + - `reverification?` + - [ReverificationConfig](/docs/references/nextjs/auth-object#reverification-config) + + The reverification configuration to check for. +### `startVerification()` + +Initiates the reverification flow. Returns a [`SessionVerification`](/docs/references/javascript/types/session-verification) instance with its status and supported factors. + +```typescript +function startVerification(params: SessionVerifyCreateParams): Promise +``` + +#### `SessionVerifyCreateParams` + +```typescript +type SessionVerifyCreateParams = { + status: 'pending' | 'verified' | 'failed' +} +``` + +### `prepareFirstFactorVerification()` + +Initiates the first factor verification process. This is a required step to complete a reverification flow when using a preparable factor. Returns a [`SessionVerification`](/docs/references/javascript/types/session-verification) instance with its status and supported factors. + +```typescript +function prepareFirstFactorVerification( + params: SessionVerifyPrepareFirstFactorParams, +): Promise +``` + +#### `SessionVerifyPrepareFirstFactorParams` + +```ts +type SessionVerifyPrepareFirstFactorParams = EmailCodeConfig | PhoneCodeConfig + +type EmailCodeConfig = { + strategy: 'email_code' + primary?: boolean | undefined + emailAddressId: string +} + +type PhoneCodeConfig = { + strategy: 'phone_code' + phoneNumberId: string + primary?: boolean + default?: boolean +} +``` + +### `attemptFirstFactorVerification()` + +Attempts to complete the first factor verification process. Returns a [`SessionVerification`](/docs/references/javascript/types/session-verification) instance with its status and supported factors. + +```typescript +function attemptFirstFactorVerification( + params: SessionVerifyAttemptFirstFactorParams, +): Promise +``` + +#### `SessionVerifyAttemptFirstFactorParams` + +```ts +type SessionVerifyAttemptFirstFactorParams = EmailCodeAttempt | PhoneCodeAttempt | PasswordAttempt + +type EmailCodeAttempt = { + strategy: 'email_code' + code: string +} + +type PhoneCodeAttempt = { + strategy: 'phone_code' + code: string +} + +type PasswordAttempt = { + strategy: 'password' + password: string +} +``` + +### `prepareSecondFactorVerification()` + +Initiates the second factor verification process. This is a required step to complete a reverification flow when using a preparable factor. Returns a [`SessionVerification`](/docs/references/javascript/types/session-verification) instance with its status and supported factors. + +```typescript +function prepareSecondFactorVerification( + params: SessionVerifyPrepareSecondFactorParams, +): Promise +``` + +#### `SessionVerifyPrepareSecondFactorParams` + +```ts +type SessionVerifyPrepareSecondFactorParams = PhoneCodeSecondFactorConfig + +type PhoneCodeSecondFactorConfig = { + strategy: 'phone_code' + phoneNumberId?: string +} +``` + +### `attemptSecondFactorVerification()` + +Attempts to complete the second factor verification process. Returns a [`SessionVerification`](/docs/references/javascript/types/session-verification) instance with its status and supported factors. + +```typescript +function attemptSecondFactorVerification( + params: SessionVerifyAttemptSecondFactorParams, +): Promise +``` + +#### `SessionVerifyAttemptSecondFactorParams` + +```ts +type SessionVerifyAttemptSecondFactorParams = PhoneCodeAttempt | TOTPAttempt | BackupCodeAttempt + +type PhoneCodeAttempt = { + strategy: 'phone_code' + code: string +} + +type TOTPAttempt = { + strategy: 'totp' + code: string +} + +type BackupCodeAttempt = { + strategy: 'backup_code' + code: string +} +``` + [client-ref]: /docs/references/javascript/client diff --git a/docs/references/javascript/sign-in/authenticate-with.mdx b/docs/references/javascript/sign-in/authenticate-with.mdx index 8d4004251a..bd7949b32c 100644 --- a/docs/references/javascript/sign-in/authenticate-with.mdx +++ b/docs/references/javascript/sign-in/authenticate-with.mdx @@ -87,7 +87,7 @@ function authenticateWithWeb3(params: AuthenticateWithWeb3Params): Promise Promise` - The method of how to generate the signature for the Web3 sign-in. See [`GenerateSignatureParams`](#generate-signature-params) for more details. + The method of how to generate the signature for the Web3 sign-in. See [`GenerateSignatureParams`](#generate-signature-params) for more information. --- diff --git a/docs/references/javascript/sign-in/sign-in.mdx b/docs/references/javascript/sign-in/sign-in.mdx index f4e916c3f7..f435a46aaf 100644 --- a/docs/references/javascript/sign-in/sign-in.mdx +++ b/docs/references/javascript/sign-in/sign-in.mdx @@ -8,7 +8,7 @@ The `SignIn` object holds the state of the current sign-in and provides helper m The following steps outline the sign-in process: 1. Initiate the sign-in process by collecting the user's authentication information and passing the appropriate parameters to the [`create()`](#create) method. -1. Prepare the [first factor verification.](#first-factor) Users _must_ complete a first factor verification. This can be something like providing a password, an email link, a one-time code (OTP), a Web3 wallet address, or providing proof of their identity through an external social account (SSO/OAuth). +1. Prepare the [first factor verification](#first-factor). Users _must_ complete a first factor verification. This can be something like providing a password, an email link, a one-time code (OTP), a Web3 wallet address, or providing proof of their identity through an external social account (SSO/OAuth). 1. Attempt to complete the first factor verification. 1. Optionally, if you have enabled [multi-factor](/docs/authentication/configuration/sign-up-sign-in-options) for your application, you will need to prepare the [second factor verification](#second-factor) for users who have set up 2FA for their account. 1. Attempt to complete the second factor verification. @@ -262,4 +262,4 @@ In addition to the methods listed above, the `SignIn` class also has the followi ## Example -For examples of how to access the `SignUp` object and use the associated methods, see the [custom flow guides.](/docs/custom-flows/overview) +For examples of how to access the `SignUp` object and use the associated methods, see the [custom flow guides](/docs/custom-flows/overview). diff --git a/docs/references/javascript/sign-up/authenticate-with.mdx b/docs/references/javascript/sign-up/authenticate-with.mdx index b645e0ca09..8f2f746c29 100644 --- a/docs/references/javascript/sign-up/authenticate-with.mdx +++ b/docs/references/javascript/sign-up/authenticate-with.mdx @@ -88,7 +88,7 @@ function authenticateWithWeb3(params: AuthenticateWithWeb3Params): Promise(opts: [GenerateSignatureParams](#generate-signature-params)) => Promise\ - The method of how to generate the signature for the Web3 sign-in. See [`GenerateSignatureParams`](#generate-signature-params) for more details. + The method of how to generate the signature for the Web3 sign-in. See [`GenerateSignatureParams`](#generate-signature-params) for more information. --- diff --git a/docs/references/javascript/sign-up/sign-up.mdx b/docs/references/javascript/sign-up/sign-up.mdx index c59bb5624d..9e802b1b0e 100644 --- a/docs/references/javascript/sign-up/sign-up.mdx +++ b/docs/references/javascript/sign-up/sign-up.mdx @@ -8,7 +8,7 @@ The `SignUp` object holds the state of the current sign-up and provides helper m The following steps outline the sign-up process: 1. Initiate the sign-up process by collecting the user's authentication information and passing the appropriate parameters to the [`create()`](#create) method. -1. Prepare the [verification.](#verification) +1. Prepare the [verification](#verification). 1. Attempt to complete the verification. 1. If the verification is successful, set the newly created session as the active session by passing the `SignIn.createdSessionId` to the [`setActive()`](/docs/references/javascript/clerk/session-methods#set-active) method on the `Clerk` object. @@ -71,7 +71,7 @@ The following steps outline the sign-up process: - `username` - `string | null` - The username supplied to the current sign-up. This attribute is available only if usernames are enabled. Check the available instance settings in your Clerk Dashboard for more information. + The username supplied to the current sign-up. This attribute is available only if usernames are enabled. Check the available instance settings in the Clerk Dashboard for more information. --- @@ -167,42 +167,42 @@ function create(params: SignUpCreateParams): Promise - `firstName` - `string | null` - The user's first name. This option is available only if name is selected in personal information. Please check the instance settings for more information. + The user's first name. This option is available only if name is selected in personal information. Check the instance settings for more information. --- - `lastName` - `string | null` - The user's last name. This option is available only if name is selected in personal information. Please check the instance settings for more information. + The user's last name. This option is available only if name is selected in personal information. Check the instance settings for more information. --- - `password` - `string | null` - The user's password. This option is available only if password-based authentication is selected. Please check the instance settings for more information. + The user's password. This option is available only if password-based authentication is selected. Check the instance settings for more information. --- - `gender` - `string | null` - The user's gender. This option is available only if gender is selected in personal information. Please check the instance settings for more information. + The user's gender. This option is available only if gender is selected in personal information. Check the instance settings for more information. --- - `emailAddress` - `string | null` - The user's email address. This option is available only if email address is selected in contact information. Keep in mind that the email address requires an extra verification process. Please check the instance settings for more information. + The user's email address. This option is available only if email address is selected in contact information. Keep in mind that the email address requires an extra verification process. Check the instance settings for more information. --- - `phoneNumber` - `string | null` - The user's phone number. This option is available only if phone number is selected in contact information. Keep in mind that the phone number requires an extra verification process. Please check the instance settings for more information. + The user's phone number. This option is available only if phone number is selected in contact information. Keep in mind that the phone number requires an extra verification process. Check the instance settings for more information. --- @@ -216,7 +216,7 @@ function create(params: SignUpCreateParams): Promise - `username` - `string | null` - The user's username. This option is available only if usernames are enabled. Please check the instance settings for more information. + The user's username. This option is available only if usernames are enabled. Check the instance settings for more information. --- @@ -364,4 +364,4 @@ In addition to the methods listed above, the `SignUp` class also has the followi ## Example -For examples of how to access the `SignUp` object and use the associated methods, see the [custom flow guides.](/docs/custom-flows/overview) +For examples of how to access the `SignUp` object and use the associated methods, see the [custom flow guides](/docs/custom-flows/overview). diff --git a/docs/references/javascript/types/session-verification.mdx b/docs/references/javascript/types/session-verification.mdx new file mode 100644 index 0000000000..53a10fc5e7 --- /dev/null +++ b/docs/references/javascript/types/session-verification.mdx @@ -0,0 +1,57 @@ +--- +title: SessionVerification +description: The SessionVerification interface represents the state of a session reverification process. +--- + +An interface that represents the state of the session verification process. + +## Properties + + + - `status` + - `'needs_first_factor' | 'needs_second_factor' | 'complete'` + + The current state of the session verification. + + --- + + - `level` + - `'first_factor' | 'second_factor' | 'multi_factor'` + + The requested level of the session verification. + + --- + + - `session` + - [`Session`](/docs/references/javascript/session) + + The `Session` object that the session verification is attached to. + + --- + + - `firstFactorVerification` + - [`Verification`](/docs/references/javascript/types/verification) + + The state of the verification process for the selected first factor. Initially, this property contains an empty `Verification` object, since there is no first factor selected. You need to call the [`prepareFirstFactorVerification()`](/docs/references/javascript/session#prepare-first-factor-verification) method in order to start the verification process. + + --- + + - `secondFactorVerification` + - [`Verification`](/docs/references/javascript/types/verification) + + The state of the verification process for the selected second factor. Initially, this property contains an empty `Verification` object, since there is no second factor selected. For the `phone_code` strategy, you need to call the [`prepareSecondFactorVerification()`](/docs/references/javascript/session#prepare-second-factor-verification) method in order to start the verification process. For the `totp` or `backup_code` strategies, you can directly attempt the verification by calling the [`attemptSecondFactorVerification()`](/docs/references/javascript/session#attempt-second-factor-verification) method. + + --- + + - `supportedFirstFactors` + - [EmailCodeFactor](/docs/references/javascript/types/sign-in-first-factor#email-code-factor)\[] | [PhoneCodeFactor](/docs/references/javascript/types/sign-in-first-factor#phone-code-factor)\[] | [PasswordFactor](/docs/references/javascript/types/sign-in-first-factor#password-factor)\[] + + Array of the first factors that are supported in the current session verification. Each factor contains information about the verification strategy that can be used. + + --- + + - `supportedSecondFactors` + - [TOTPFactor](/docs/references/javascript/types/sign-in-second-factor#totp-factor)\[] | [PhoneCodeFactor](/docs/references/javascript/types/sign-in-first-factor#phone-code-factor)\[] | [BackupCodeFactor](/docs/references/javascript/types/sign-in-second-factor#backup-code-factor)\[] + + Array of the second factors that are supported in the current session verification. Each factor contains information about the verification strategy that can be used. + diff --git a/docs/references/javascript/types/user-organization-invitation.mdx b/docs/references/javascript/types/user-organization-invitation.mdx index e5173948d4..048fb2c518 100644 --- a/docs/references/javascript/types/user-organization-invitation.mdx +++ b/docs/references/javascript/types/user-organization-invitation.mdx @@ -85,4 +85,4 @@ function accept(): Promise ### Example -To see an example of how to use the `accept()` method, check out the [Manage invitations](/docs/organizations/manage-invitations) custom flow guide. +To see an example of how to use the `accept()` method, see the [custom flow guide for managing invitations](/docs/organizations/manage-invitations). diff --git a/docs/references/javascript/user/create-metadata.mdx b/docs/references/javascript/user/create-metadata.mdx index 5de8c66d96..8080f26df5 100644 --- a/docs/references/javascript/user/create-metadata.mdx +++ b/docs/references/javascript/user/create-metadata.mdx @@ -34,7 +34,7 @@ The following example adds `test@test.com` as an email address for the user. If ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -85,7 +85,7 @@ The following example adds `15551234567` as a phone number for the user. If the ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -136,7 +136,7 @@ The following example adds `0x0123456789ABCDEF0123456789ABCDEF01234567` as a Web ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -232,7 +232,7 @@ The following example demonstrates how to add a Notion account as an external ac ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' - // Initialize Clerk with your Clerk publishable key + // Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) diff --git a/docs/references/javascript/user/password-management.mdx b/docs/references/javascript/user/password-management.mdx index 2a2725bbb8..1e911c499f 100644 --- a/docs/references/javascript/user/password-management.mdx +++ b/docs/references/javascript/user/password-management.mdx @@ -67,7 +67,7 @@ function updatePassword(params: UpdateUserPasswordParams): Promise ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' - // Initialize Clerk with your Clerk publishable key + // Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -142,7 +142,7 @@ function removePassword(params: RemoveUserPasswordParams): Promise ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' - // Initialize Clerk with your Clerk publishable key + // Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) diff --git a/docs/references/javascript/user/totp.mdx b/docs/references/javascript/user/totp.mdx index ccf2b096a9..14b5890bd6 100644 --- a/docs/references/javascript/user/totp.mdx +++ b/docs/references/javascript/user/totp.mdx @@ -10,7 +10,7 @@ Clerk supports multi-factor authentication (MFA) using Time-based One-time Passw These methods on the [`User`](/docs/references/javascript/user/user) object are related to TOTP functionality and allow you to generate and verify TOTP secrets, disable TOTP, and create backup codes for user authentication. -To see how all these methods work together, check out the [comprehensive example](#totp-example). +To see how all these methods work together, see the [comprehensive example](#totp-example). ## `createTOTP()` @@ -147,7 +147,7 @@ The following example demonstrates how to use the TOTP methods to create and ver The following example assumes: - you have followed the [quickstart](/docs/quickstarts/javascript) in order to add Clerk to your JavaScript application -- you have [enabled **Authenticator application** and **Backup codes** as multi-factor strategies in your Clerk Dashboard](/docs/authentication/configuration/sign-up-sign-in-options#authentication-strategies) +- you have [enabled **authenticator application** and **backup codes** as multi-factor strategies in the Clerk Dashboard](/docs/authentication/configuration/sign-up-sign-in-options#authentication-strategies) ```html {{ filename: 'index.html' }} @@ -193,7 +193,7 @@ The following example assumes: ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' - // Initialize Clerk with your Clerk publishable key + // Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) diff --git a/docs/references/javascript/user/user.mdx b/docs/references/javascript/user/user.mdx index e32470b17d..cde67c2864 100644 --- a/docs/references/javascript/user/user.mdx +++ b/docs/references/javascript/user/user.mdx @@ -248,7 +248,7 @@ The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to - `unsafeMetadata` - `{[string]: any} | null` - Metadata that can be read and set from the Frontend API. One common use case for this attribute is to implement custom fields that will be attached to the `User` object.
Please note that there is also an `unsafeMetadata` attribute in the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object. The value of that field will be automatically copied to the user's unsafe metadata once the sign up is complete. + Metadata that can be read and set from the Frontend API. One common use case for this attribute is to implement custom fields that will be attached to the `User` object.
There is also an `unsafeMetadata` attribute in the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object. The value of that field will be automatically copied to the user's unsafe metadata once the sign up is complete. --- @@ -285,7 +285,7 @@ The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to Updates the user's attributes. Use this method to save information you collected about the user. -The appropriate settings must be enabled in the Clerk Dashboard for the user to be able to update their attributes. For example, if you want to use the `update({ firstName })` method, you must enable the **Name** setting. It can be found in the the Clerk Dashboard under **User & Authentication > Email, Phone, Username > [Personal information](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username).** +The appropriate settings must be enabled in the Clerk Dashboard for the user to be able to update their attributes. For example, if you want to use the `update({ firstName })` method, you must enable the **Name** setting. It can be found on the [**Email, phone, username > Personal information**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) section in the Clerk Dashboard. ```ts function update(params: UpdateUserParams): Promise @@ -351,7 +351,7 @@ In the following example, the user's first name is updated to "Test". ```js {{ filename: 'main.js', mark: [10, 11] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -386,7 +386,7 @@ function delete(): Promise ```js {{ filename: 'main.js', mark: [10, 11] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -474,7 +474,7 @@ function setProfileImage(params: SetProfileImageParams): Promise ```js {{ filename: 'main.js' }} import { Clerk } from '@clerk/clerk-js' - // Initialize Clerk with your Clerk publishable key + // Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -525,7 +525,7 @@ function reload(p?: ClerkResourceReloadParams): Promise ```js {{ filename: 'main.js', mark: [9] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -553,7 +553,7 @@ function getSessions(): Promise ```js {{ filename: 'main.js', mark: [10, 11] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -655,7 +655,7 @@ function getOrganizationInvitations( ```js {{ filename: 'main.js', mark: [10, 11] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -721,7 +721,7 @@ function getOrganizationSuggestions( ```js {{ filename: 'main.js', mark: [10, 11] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) @@ -780,7 +780,7 @@ function getOrganizationMemberships( ```js {{ filename: 'main.js', mark: [10, 11] }} import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk publishable key +// Initialize Clerk with your Clerk Publishable Key const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY const clerk = new Clerk(pubKey) diff --git a/docs/references/nextjs/auth-object.mdx b/docs/references/nextjs/auth-object.mdx index ec8e995975..d32ad7e978 100644 --- a/docs/references/nextjs/auth-object.mdx +++ b/docs/references/nextjs/auth-object.mdx @@ -3,7 +3,7 @@ title: '`Auth` object' description: The Auth object contains information about the current user's session. --- -Both [`auth()`](/docs/references/nextjs/auth) and [`getAuth()`](/docs/references/nextjs/get-auth) return an `Auth` object. This JavaScript object contains important information like the current user's session ID, user ID, and organization ID. It also contains methods to check for permissions and retrieve the current user's session token. +The `Auth` object contains important information like the current user's session ID, user ID, and organization ID. It also contains methods to check for permissions and retrieve the current user's session token. It's returned by the [`useAuth()`](/docs/references/react/use-auth) hook, the [`auth()`](/docs/references/nextjs/auth) and [`getAuth()`](/docs/references/nextjs/get-auth) helpers, and the `request` object in server contexts. ## `Auth` object properties @@ -71,6 +71,13 @@ Both [`auth()`](/docs/references/nextjs/auth) and [`getAuth()`](/docs/reference --- + - `factorVerificationAge` + - `[number, number] | null` + + An array where each item represents the number of minutes since the last verification of a first or second factor: `[firstFactorAge, secondFactorAge]`. + + --- + - [`getToken()`](#get-token) - [`ServerGetToken`](#server-get-token) @@ -98,15 +105,7 @@ The `orgPermissions` property on the `Auth` object has the type `OrganizationCus ### `has()` -`has()` can be used on both the frontend and the backend to determine if the user _has_ a role or permission. - -You can use `has()` anywhere Clerk returns an [`Auth`](/docs/references/nextjs/auth-object) object: - -- [`auth()`](/docs/references/nextjs/auth) in Next.js App Router -- [`useAuth()`](/docs/references/react/use-auth) in Client Components, including during SSR -- [`getAuth(request)`](/docs/references/nextjs/get-auth) in server contexts outside of the App Router and SSR (Remix Loaders, Node, Express, Fastify, etc) - -`has()` has the following function signature: +`has()` determines if the user _has_ a role or permission. ```ts function has(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions): boolean @@ -128,9 +127,69 @@ function has(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions): - `string` The permission to check for. + + --- + + - `reverification?` + - [ReverificationConfig](#reverification-config) + + The reverification configuration to check for. This feature is currently in public beta. **It is not recommended for production use**. + + +##### `ReverificationConfig` + +```ts +type ReverificationConfig = + | SessionVerificationTypes + | { + level: SessionVerificationLevel + afterMinutes: SessionVerificationAfterMinutes + } + +type SessionVerificationTypes = 'strict_mfa' | 'strict' | 'moderate' | 'lax' +``` + +The `ReverificationConfig` type has the following properties: + + + - `strict_mfa` + + Requires the user to verify their credentials within the past 10 minutes. If not verified, prompt for both the first and second factors. + + --- + + - `strict` + + Requires the user to verify their credentials within the past 10 minutes. If not verified, prompt for the second factor. + + --- + + - `moderate` + + Requires the user to verify their credentials within the past hour. If not verified, prompt for the second factor. + + --- + + - `lax` + + Requires the user to verify their credentials within the past day. If not verified, prompt for the second factor. + + --- + + - `level` + - `"first_factor" | "second_factor" | "multi_factor"` + + The reverification level of credentials to check for. + + --- + + - `afterMinutes` + - `number` + + The age of the factor level to check for. Value should be greater than or equal to 1 and less than 99,999. -#### `has()` example +#### `has()` permissions example You can use `has()` to check if a user is authorized to access a component. @@ -153,6 +212,15 @@ export default async function Page() { } ``` +#### `has()` reverification example + +> [!IMPORTANT] +> This example demonstrates how to handle reverification **server-side**. For information on how to handle reverification on the **client-side**, see the [guide on reverification](/docs/guides/reverification). + +You can use `has()` to check if a user has verified their credentials within a certain time frame. + + + ### `getToken()` You can use `getToken()` on an `Auth` object to retrieve the user's session token. You can also use this method to retrieve a custom JWT template. @@ -185,14 +253,14 @@ The `Auth` object is not available in the frontend. To use the `getToken()` meth #### Use `getToken()` in the backend - + To use the `getToken()` method in the backend: - In App Router applications, use the [`auth()`](/docs/references/nextjs/auth) helper. - In Pages Router applications, use the [`getAuth()`](/docs/references/nextjs/get-auth) helper. - + ```js {{ filename: 'app/api/get-token-example/route.ts' }} import { auth } from '@clerk/nextjs/server' @@ -275,8 +343,8 @@ The following is an example of the `Auth` object without an active organization: ```js {{ prettier: false }} { - sessionId: 'sess_2GaMqUCB3Sc1WNAkWuNzsnYVVEy', - userId: 'user_2F2u1wtUyUlxKgFkKqtJNtpJJWj', + sessionId: 'sess_123', + userId: 'user_123', orgId: null, orgRole: null, orgSlug: null, @@ -289,8 +357,8 @@ The following is an example of the `Auth` object without an active organization: iat: 1666622547, iss: 'https://clerk.quiet.muskox-85.lcl.dev', nbf: 1666622537, - sid: 'sess_2GaMqUCB3Sc1WNAkWuNzsnYVVEy', - sub: 'user_2F2u1wtUyUlxKgFkKqtJNtpJJWj', + sid: 'sess_123', + sub: 'user_123', }, } ``` @@ -301,9 +369,9 @@ The following is an example of the `Auth` object with an active organization: ```js {{ prettier: false }} { - sessionId: 'sess_2GaMqUCB3Sc1WNAkWuNzsnYVVEy', - userId: 'user_2F2u1wtUyUlxKgFkKqtJNtpJJWj', - orgId: 'org_2ZVFfVAkt4ocVjHL0KTdL94AhXK', + sessionId: 'sess_123', + userId: 'user_123', + orgId: 'org_123', orgRole: 'org:admin', orgSlug: undefined, orgPermissions: ['org:team_settings:manage'], // Custom permissions @@ -315,8 +383,58 @@ The following is an example of the `Auth` object with an active organization: iat: 1666622547, iss: 'https://clerk.quiet.muskox-85.lcl.dev', nbf: 1666622537, - sid: 'sess_2GaMqUCB3Sc1WNAkWuNzsnYVVEy', - sub: 'user_2F2u1wtUyUlxKgFkKqtJNtpJJWj', + sid: 'sess_123', + sub: 'user_123', + }, +} +``` + +## `Auth` object example with valid factor age + +```js {{ mark: [8], prettier: false }} +{ + sessionId: 'sess_123', + userId: 'user_123', + orgId: null, + orgRole: null, + orgSlug: null, + orgPermissions: null, + factorVerificationAge: [0,0], + has: [Function (anonymous)], + getToken: [AsyncFunction (anonymous)], + claims: { + azp: 'http://localhost:3000', + exp: 1666622607, + iat: 1666622547, + iss: 'https://clerk.quiet.muskox-85.lcl.dev', + nbf: 1666622537, + sid: 'sess_123', + sub: 'user_123', + }, +} +``` + +## `Auth` object example of a user without an MFA method registered + +```js {{ mark: [8], prettier: false }} +{ + sessionId: 'sess_123', + userId: 'user_123', + orgId: null, + orgRole: null, + orgSlug: null, + orgPermissions: null, + factorVerificationAge: [0, -1], + has: [Function (anonymous)], + getToken: [AsyncFunction (anonymous)], + claims: { + azp: 'http://localhost:3000', + exp: 1666622607, + iat: 1666622547, + iss: 'https://clerk.quiet.muskox-85.lcl.dev', + nbf: 1666622537, + sid: 'sess_123', + sub: 'user_123', }, } ``` diff --git a/docs/references/nextjs/auth.mdx b/docs/references/nextjs/auth.mdx index 9cf89c08bd..d4558edaca 100644 --- a/docs/references/nextjs/auth.mdx +++ b/docs/references/nextjs/auth.mdx @@ -66,7 +66,7 @@ The following table describes how `auth.protect()` behaves based on user authent ### Examples -`auth.protect()` can be used to check if a user is authenticated or authorized to access certain parts of your application or even entire routes. See detailed examples in [the dedicated guide.](/docs/organizations/verify-user-permissions) +`auth.protect()` can be used to check if a user is authenticated or authorized to access certain parts of your application or even entire routes. See detailed examples in the [dedicated guide](/docs/organizations/verify-user-permissions). ## `redirectToSignIn()` @@ -146,4 +146,4 @@ export async function GET() { ## Use `auth()` to protect your app -You can protect certain parts of your application or even entire routes based on a user's authentication and/or authorization status. See detailed examples in [the dedicated guide.](/docs/organizations/verify-user-permissions) +You can protect certain parts of your application or even entire routes based on a user's authentication and/or authorization status. See detailed examples in the [dedicated guide](/docs/organizations/verify-user-permissions). diff --git a/docs/references/nextjs/build-clerk-props.mdx b/docs/references/nextjs/build-clerk-props.mdx index 099a2d8263..7b06f5a61a 100644 --- a/docs/references/nextjs/build-clerk-props.mdx +++ b/docs/references/nextjs/build-clerk-props.mdx @@ -36,7 +36,9 @@ import { GetServerSideProps } from 'next' export const getServerSideProps: GetServerSideProps = async (ctx) => { const { userId } = getAuth(ctx.req) - const user = userId ? await clerkClient().users.getUser(userId) : undefined + const client = await clerkClient() + + const user = userId ? await client.users.getUser(userId) : undefined return { props: { ...buildClerkProps(ctx.req, { user }) } } } diff --git a/docs/references/nextjs/clerk-middleware.mdx b/docs/references/nextjs/clerk-middleware.mdx index c9b5e0adc1..827b1dae9c 100644 --- a/docs/references/nextjs/clerk-middleware.mdx +++ b/docs/references/nextjs/clerk-middleware.mdx @@ -334,7 +334,7 @@ The `clerkMiddleware()` function accepts an optional object. The following optio - `jwtKey` - `string` - Used to verify the session token in a networkless manner. Supply the PEM public key from the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section of the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt). + Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt). --- @@ -362,14 +362,14 @@ The `clerkMiddleware()` function accepts an optional object. The following optio - `publishableKey` - `string` - The Clerk publishable key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. + The Clerk Publishable 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. --- - `secretKey?` - `string` - The Clerk secret key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. The `CLERK_ENCRYPTION_KEY` environment variable must be set when providing `secretKey` as an option, refer to [Dynamic keys](#dynamic-keys). + 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. The `CLERK_ENCRYPTION_KEY` environment variable must be set when providing `secretKey` as an option, refer to [Dynamic keys](#dynamic-keys). It's also possible to dynamically set options based on the incoming request: diff --git a/docs/references/nextjs/current-user.mdx b/docs/references/nextjs/current-user.mdx index 4ba55fa768..c8ea1da5c5 100644 --- a/docs/references/nextjs/current-user.mdx +++ b/docs/references/nextjs/current-user.mdx @@ -8,8 +8,8 @@ The `currentUser` helper returns the [`Backend User`](/docs/references/backend/t Under the hood, this helper: - calls `fetch()`, so it is automatically deduped per request. -- uses the [`GET /v1/users/{user_id}`](https://clerk.com/docs/reference/backend-api/tag/Users#operation/GetUser) endpoint. -- counts towards the [Backend API Request Rate Limit](/docs/backend-requests/resources/rate-limits#rate-limits). +- uses the [`GET /v1/users/{user_id}`](/docs/reference/backend-api/tag/Users#operation/GetUser){{ target: '_blank' }} endpoint. +- counts towards the [Backend API request rate limit](/docs/backend-requests/resources/rate-limits#rate-limits). ```tsx {{ filename: 'app/page.tsx' }} import { currentUser } from '@clerk/nextjs/server' diff --git a/docs/references/nextjs/custom-signup-signin-pages.mdx b/docs/references/nextjs/custom-signup-signin-pages.mdx index a6f77e7b4a..14a2899bb8 100644 --- a/docs/references/nextjs/custom-signup-signin-pages.mdx +++ b/docs/references/nextjs/custom-signup-signin-pages.mdx @@ -5,64 +5,44 @@ description: Learn how to add custom sign-in and sign-up pages to your Next.js a This guide shows you how to use the [``](/docs/components/authentication/sign-in) and [``](/docs/components/authentication/sign-up) components with the [Next.js optional catch-all route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes#catch-all-segments) in order to build custom sign-in and sign-up pages for your Next.js app. -If the 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 the 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). > [!NOTE] > Watch the video version of this guide on the Clerk YouTube channel → [YouTube (4 minutes)](https://youtu.be/fsuHLafTYyg). > [!NOTE] -> Just getting started with Clerk and Next.js? Check out the [quickstart tutorial](/docs/quickstarts/nextjs)! +> Just getting started with Clerk and Next.js? See the [quickstart tutorial](/docs/quickstarts/nextjs)! {/* TODO: Update these Steps once Steps component accepts other headings types. These headings should be H2s. */} ### Build a sign-up page - Create a new file that will be used to render the sign-up page. In the file, import the [``](/docs/components/authentication/sign-up) component from `@clerk/nextjs` and render it. + The following example demonstrates how to render the [``](/docs/components/authentication/sign-up) component. - - ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx' }} - import { SignUp } from '@clerk/nextjs' + ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx' }} + import { SignUp } from '@clerk/nextjs' - export default function Page() { - return - } - ``` - - ```tsx {{ filename: '/pages/sign-up/[[...index]].tsx' }} - import { SignUp } from '@clerk/nextjs' - - export default function Page() { - return - } - ``` - + export default function Page() { + return + } + ``` ### Build a sign-in page - Create a new file that will be used to render the sign-in page. In the file, import the [``](/docs/components/authentication/sign-in) component from `@clerk/nextjs` and render it. + The following example demonstrates how to render the [``](/docs/components/authentication/sign-in) component. - - ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }} - import { SignIn } from '@clerk/nextjs' + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }} + import { SignIn } from '@clerk/nextjs' - export default function Page() { - return - } - ``` - - ```tsx {{ filename: '/pages/sign-in/[[...index]].tsx' }} - import { SignIn } from '@clerk/nextjs' - - export default function Page() { - return - } - ``` - + export default function Page() { + return + } + ``` ### Make the sign-up and sign-in routes public - By default, `clerkMiddleware()` makes all routes public. This step is specifically for applications that have configured `clerkMiddleware()` to make [all routes protected](/docs/references/nextjs/clerk-middleware#protect-all-routes). If you have not configured `clerkMiddleware()` to protect all routes, you can skip this step. + By default, `clerkMiddleware()` makes all routes public. **This step is specifically for applications that have configured `clerkMiddleware()` to make [all routes protected](/docs/references/nextjs/clerk-middleware#protect-all-routes).** If you have not configured `clerkMiddleware()` to protect all routes, you can skip this step. To make the sign-up and sign-in routes public: @@ -93,9 +73,7 @@ If the prebuilt components don't meet your specific needs or if you require more ### Update your environment variables - In the previous steps, a `path` prop is passed to the `` and `` components. This is because the components need to know which route they are originally mounted on. - - In Next.js applications, you can either pass the `path` prop, _or_ you can define the `NEXT_PUBLIC_CLERK_SIGN_IN_URL` and `NEXT_PUBLIC_CLERK_SIGN_UP_URL` environment variables, like so: + Update your environment variables to point to your custom sign-in and sign-up pages. Learn more about the available [environment variables](/docs/deployments/clerk-environment-variables). ```env {{ filename: '.env.local' }} NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in @@ -104,7 +82,7 @@ If the prebuilt components don't meet your specific needs or if you require more ### Visit your new pages - Run your project with the following terminal command from the root directory of your project: + Run your project with the following command: ```bash {{ filename: 'terminal' }} @@ -131,7 +109,7 @@ If the prebuilt components don't meet your specific needs or if you require more --- - - [Client Side Helpers](/docs/references/nextjs/overview#client-side-helpers) + - [Client-side helpers](/docs/references/nextjs/overview#client-side-helpers) - Learn more about Next.js client-side helpers and how to use them. --- diff --git a/docs/references/nextjs/get-auth.mdx b/docs/references/nextjs/get-auth.mdx index f100536fdb..4f6fe83407 100644 --- a/docs/references/nextjs/get-auth.mdx +++ b/docs/references/nextjs/get-auth.mdx @@ -21,7 +21,7 @@ The `getAuth()` helper retrieves authentication state from the request object. An optional object that can be used to configure the behavior of the `getAuth()` function. It accepts the following properties: - - `secretKey?`: A string that represents the secret key used to sign the session token. If not provided, the secret key is retrieved from the environment variable `CLERK_SECRET_KEY`. + - `secretKey?`: A string that represents the Secret Key used to sign the session token. If not provided, the Secret Key is retrieved from the environment variable `CLERK_SECRET_KEY`. ## Returns @@ -90,7 +90,7 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse) ### Usage with `clerkClient` -`clerkClient` is used to access the [Backend SDK](/docs/references/backend/overview), which exposes Clerk's backend API resources. You can use `getAuth()` to pass authentication information that many of the Backend SDK methods require, like in the following example: +`clerkClient` is used to access the [Backend SDK](/docs/references/backend/overview), which exposes Clerk's Backend API resources. You can use `getAuth()` to pass authentication information that many of the Backend SDK methods require, like in the following example: ```tsx {{ filename: 'app/api/example/route.ts' }} import { clerkClient, getAuth } from '@clerk/nextjs/server' @@ -99,7 +99,9 @@ import type { NextApiRequest, NextApiResponse } from 'next' export default async function handler(req: NextApiRequest, res: NextApiResponse) { const { userId } = getAuth(req) - const user = userId ? await clerkClient().users.getUser(userId) : null + const client = await clerkClient() + + const user = userId ? await client.users.getUser(userId) : null return res.status(200).json({}) } diff --git a/docs/references/nextjs/read-session-data.mdx b/docs/references/nextjs/read-session-data.mdx index 370f7678b3..11d9cb5134 100644 --- a/docs/references/nextjs/read-session-data.mdx +++ b/docs/references/nextjs/read-session-data.mdx @@ -132,7 +132,9 @@ Under the hood, `currentUser()` uses the [`clerkClient`](/docs/references/backen return res.status(401).json({ error: 'Unauthorized' }) } - const user = await clerkClient().users.getUser(userId) + const client = await clerkClient() + + const user = await client.users.getUser(userId) // use the user object to decide what data to return @@ -145,7 +147,7 @@ Under the hood, `currentUser()` uses the [`clerkClient`](/docs/references/backen You can access the active session and user data in your `getServerSideProps` using the `getAuth()` helper. > [!NOTE] - > Please note the addition of `buildClerkProps` in the return statement, which informs the Clerk React helpers of the authentication state during server-side rendering (like `useAuth()`, ``, and ``). + > Note the addition of `buildClerkProps` in the return statement, which informs the Clerk React helpers of the authentication state during server-side rendering (like `useAuth()`, ``, and ``). ```tsx {{ filename: 'pages/example.tsx' }} import { getAuth, buildClerkProps } from '@clerk/nextjs/server' @@ -173,7 +175,9 @@ Under the hood, `currentUser()` uses the [`clerkClient`](/docs/references/backen export const getServerSideProps: GetServerSideProps = async (ctx) => { const { userId } = getAuth(ctx.req) - const user = userId ? await clerkClient.users.getUser(userId) : undefined + const client = await clerkClient() + + const user = userId ? await client.users.getUser(userId) : undefined return { props: { ...buildClerkProps(ctx.req, { user }) } } } diff --git a/docs/references/nextjs/route-handlers.mdx b/docs/references/nextjs/route-handlers.mdx index 50763c4633..2e300201ad 100644 --- a/docs/references/nextjs/route-handlers.mdx +++ b/docs/references/nextjs/route-handlers.mdx @@ -3,7 +3,7 @@ title: Route Handlers description: Learn how to use Clerk with your Route Handlers. --- -Clerk provides helpers that allow you to protect your Route Handlers, fetch the current user, and interact with the Clerk backend API. +Clerk provides helpers that allow you to protect your Route Handlers, fetch the current user, and interact with the Clerk Backend API. ## Protect your Route Handlers @@ -12,8 +12,8 @@ If you aren't protecting your Route Handler using [`clerkMiddleware()`](/docs/re - Use [`auth.protect()`](/docs/references/nextjs/auth#protect) if you want Clerk to return a `404` error when there is no signed in user. - Use [`auth().userId`](/docs/references/nextjs/auth#retrieving-user-id) if you want to customize the behavior or error message. - - ```tsx {{ filename: '/app/api/route.ts' }} + + ```tsx {{ filename: 'app/api/route.ts' }} import { auth } from '@clerk/nextjs/server' export async function GET() { @@ -104,7 +104,9 @@ export async function POST(req: NextRequest) { const params = { firstName: 'John', lastName: 'Wick' } - const user = await clerkClient().users.updateUser(userId, params) + const client = await clerkClient() + + const user = await client.users.updateUser(userId, params) return NextResponse.json({ user }) } diff --git a/docs/references/nodejs/available-methods.mdx b/docs/references/nodejs/available-methods.mdx index 302e23f705..c43b94770e 100644 --- a/docs/references/nodejs/available-methods.mdx +++ b/docs/references/nodejs/available-methods.mdx @@ -4,7 +4,7 @@ description: Learn how to use the Clerk Node.js SDK to interact with the Clerk A --- > [!CAUTION] -> On January 8, 2025, the Node SDK will no longer be available. [Upgrade to the Express SDK.](/docs/upgrade-guides/node-to-express) +> On January 8, 2025, the Node SDK will no longer be available. [Upgrade to the Express SDK](/docs/upgrade-guides/node-to-express). All resource operations are mounted as sub-APIs on the `clerkClient` object. You can find the full list of available operations in the [JavaScript Backend SDK](/docs/references/backend/overview) documentation. To access a resource, you must first instantiate a `clerkClient` instance. @@ -38,7 +38,7 @@ If you would like to use the default instance of `clerkClient` provided by the S If you would like to customize the behavior of the SDK, you can instantiate a `clerkClient` instance yourself by calling `createClerkClient` and passing in [options](#customizing-resources). -The example below shows how to use `createClerkClient` to create a `clerkClient` instance and pass a Clerk secret key _instead of_ setting a `CLERK_SECRET_KEY` environment variable. +The example below shows how to use `createClerkClient` to create a `clerkClient` instance and pass a Clerk Secret Key _instead of_ setting a `CLERK_SECRET_KEY` environment variable. ```js @@ -70,7 +70,7 @@ The following options are available for you to customize the behaviour of the `c | Option | Description | Default | Environment variable | | - | - | - | - | -| `secretKey` | Server key for `api.clerk.com`. Can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. | none | `CLERK_SECRET_KEY` | +| `secretKey` | Server key for `api.clerk.com`. Can be found on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. | none | `CLERK_SECRET_KEY` | | `apiVersion` | API version to use | `v4` | `CLERK_API_VERSION` | | `apiUrl` | For debugging | `https://api.clerk.com` | `CLERK_API_URL` | | `httpOptions` | HTTP client options | `{}` | N/A | diff --git a/docs/references/nodejs/overview.mdx b/docs/references/nodejs/overview.mdx index 9642e5de41..2b21bfe02e 100644 --- a/docs/references/nodejs/overview.mdx +++ b/docs/references/nodejs/overview.mdx @@ -4,14 +4,14 @@ description: Learn how to integrate Node.js into your Clerk application. --- > [!CAUTION] -> On January 8, 2025, the Node SDK will no longer be available. [Upgrade to the Express SDK.](/docs/upgrade-guides/node-to-express) +> On January 8, 2025, the Node SDK will no longer be available. [Upgrade to the Express SDK](/docs/upgrade-guides/node-to-express). ## Set up Clerk Node.js ### Create a Clerk application - You need to create a Clerk application in your Clerk Dashboard before you can set up Clerk Node.js. For more information, check out our [Set up your application](/docs/quickstarts/setup-clerk) guide. + You need to create a Clerk application in the Clerk Dashboard before you can set up Clerk Node.js. For more information, see the [setup guide](/docs/quickstarts/setup-clerk). ### Install `@clerk/clerk-sdk-node` @@ -35,7 +35,7 @@ description: Learn how to integrate Node.js into your Clerk application. Below is an example of an `.env.local` file. - **Pro tip!** If you are signed into your Clerk Dashboard, your secret key should become visible by clicking on the eye icon. Otherwise, you can find your keys in the Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. + **Pro tip!** If you are signed into the Clerk Dashboard, your Secret Key should become visible by clicking on the eye icon. Otherwise, you can find your keys on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. ```env {{ filename: '.env.local' }} CLERK_PUBLISHABLE_KEY={{pub_key}} diff --git a/docs/references/react/add-react-router.mdx b/docs/references/react/add-react-router.mdx index 9af1ce6d8f..469ba35c67 100644 --- a/docs/references/react/add-react-router.mdx +++ b/docs/references/react/add-react-router.mdx @@ -32,7 +32,7 @@ description: Learn how to add React Router to your React application using their > [!WARNING] -> [Loaders](https://reactrouter.com/en/main/route/loader) and [Actions](https://reactrouter.com/en/main/route/action) are currently not supported by Clerk with React Router. +> This tutorial is written for [React Router 6](https://reactrouter.com/6.28.0/home) and doesn't support [loaders](https://reactrouter.com/6.28.0/route/loader) and [actions](https://reactrouter.com/6.28.0/route/action). Learn how to add React Router to your application using React Router's new Data API router. This tutorial will cover configuring layouts and setting up protected routes. @@ -312,7 +312,7 @@ Learn how to add React Router to your application using React Router's new Data - The `` is child of the root layout, renders nothing, and has a check to see if the `userId` exists. This will confirm that a user is signed in. If the `userId` is not truthy, then the user will be redirected to the `/sign-in` route to sign-in. That protects all pages in the `/dashboard` route. All children of `/dashboard` will be mounted inside of the `` component in the dashboard layout. -Your application is setup with `react-router-dom` and ready for you to add more layouts and routes as needed! If you want to get started using a template from this guide, please clone the following repository and then checkout the `integrate-react-router-dom-using-data-router-method` branch. +Your application is setup with `react-router-dom` and ready for you to add more layouts and routes as needed! If you want to get started using a template from this guide, clone the following repository and then checkout the `integrate-react-router-dom-using-data-router-method` branch. - [Clerk + React Quickstart](https://github.com/clerk/clerk-react-quickstart) diff --git a/docs/references/react/overview.mdx b/docs/references/react/overview.mdx index bea8f589fb..50b72d2f59 100644 --- a/docs/references/react/overview.mdx +++ b/docs/references/react/overview.mdx @@ -14,6 +14,6 @@ Clerk React provides a suite of [custom hooks](/docs/references/react/use-user). ## Setting up Clerk React -You need to create a Clerk application in your Clerk Dashboard before you can set up Clerk React. For more information, check out [the dedicated guide.](/docs/quickstarts/setup-clerk) +You need to create a Clerk application in the Clerk Dashboard before you can set up Clerk React. For more information, see the [setup guide](/docs/quickstarts/setup-clerk). Once a Clerk application has been created, you can install and start using Clerk React in your application. [The quickstart guide](/docs/quickstarts/react) will have all the information you need to get started. diff --git a/docs/references/react/use-reverification.mdx b/docs/references/react/use-reverification.mdx new file mode 100644 index 0000000000..5a804acb24 --- /dev/null +++ b/docs/references/react/use-reverification.mdx @@ -0,0 +1,100 @@ +--- +title: '`useReverification()`' +description: Clerk's useReverification() hook enhances a fetcher function to handle a session's reverification flow. +--- + +> [!WARNING] +> This feature is currently in public beta. **It is not recommended for production use**. +> +> Depending on the SDK you're using, this feature requires `@clerk/nextjs@6.5.0` or later, `@clerk/clerk-react@5.17.0` or later, and `@clerk/clerk-js@5.35.0` or later. + +The `useReverification()` hook is used to handle a session's reverification flow. If a request requires reverification, a modal will display, prompting the user to verify their credentials. Upon successful verification, the original request will automatically retry. + +## Parameters + + + - `fetcher` + - `Fetcher extends (...args: any[]) => Promise` + + The fetcher function. + + --- + + - `options?` + - [`UseReverificationOptions`](#use-reverification-options) + + The optional options object. + + +### `UseReverificationOptions` + + + - `onCancel?` + - `() ⇒ void` + + A callback function that is invoked when the user cancels the reverification process. + + --- + + - `throwOnCancel?` + - `boolean` + + Determines if an error should throw when the user cancels the reverification process. Defaults to `false`. + + +## Returns + +The `useReverification()` hook returns an array with the "enhanced" fetcher. + +## How to use the `useReverification()` hook + +### Handle cancellation of the reverification process + +The following example demonstrates how to handle scenarios where a user cancels the reverification flow, such as closing the modal, which might result in `myData` being `null`. + +In this example, `myFetcher` would be a function in your backend that fetches data from the route that requires reverification. See the [guide on how to require reverification](/docs/guides/reverification) for more information. + +```tsx {{ filename: 'MyButton.tsx' }} +import { useReverification } from '@clerk/react' + +export function MyButton() { + const [enhancedFetcher] = useReverification(myFetcher) + + const handleClick = async () => { + const myData = await enhancedFetcher() + // If `myData` is null, the user canceled the reverification process + // You can choose how your app responds. This example returns null. + if (!myData) return + } + + return +} +``` + +### Handle `throwOnCancel` + +When `throwOnCancel` is set to `true`, the fetcher will throw a `ClerkRuntimeError` with the code `"reverification_cancelled"` if the user cancels the reverification flow (for example, by closing the modal). This error can be caught and handled according to your app's needs. For example, by displaying a toast notification to the user or silently ignoring the cancellation. + +In this example, `myFetcher` would be a function in your backend that fetches data from the route that requires reverification. See the [guide on how to require reverification](/docs/guides/reverification) for more information. + +```tsx {{ filename: 'MyButton.tsx' }} +import { useReverification } from '@clerk/clerk-react' +import { isClerkRuntimeError } from '@clerk/clerk-react/errors' + +export function MyButton() { + const [enhancedFetcher] = useReverification(myFetcher, { throwOnCancel: true }) + + const handleClick = async () => { + try { + const myData = await enhancedFetcher() + } catch (e) { + // Handle if user cancels the reverification process + if (isClerkRuntimeError(e) && e.code === 'reverification_cancelled') { + console.error('User cancelled reverification', e.code) + } + } + } + + return +} +``` diff --git a/docs/references/react/use-sign-in.mdx b/docs/references/react/use-sign-in.mdx index 2d8cfe4c4a..c178a6a80d 100644 --- a/docs/references/react/use-sign-in.mdx +++ b/docs/references/react/use-sign-in.mdx @@ -3,7 +3,7 @@ title: '`useSignIn()`' description: Clerk's useSignIn() hook provides access to the SignIn object, which allows you to check the current state of a sign-in. --- -The `useSignIn()` hook provides access to the [`SignIn`](/docs/references/javascript/sign-in/sign-in) object, which allows you to check the current state of a sign-in. This is also useful for creating a [custom sign-in flow.](#create-a-custom-sign-in-flow-with-use-sign-in) +The `useSignIn()` hook provides access to the [`SignIn`](/docs/references/javascript/sign-in/sign-in) object, which allows you to check the current state of a sign-in. This is also useful for creating a [custom sign-in flow](#create-a-custom-sign-in-flow-with-use-sign-in). ## `useSignIn()` returns @@ -84,4 +84,4 @@ The `status` property of the `SignIn` object can be one of the following values: ### Create a custom sign-in flow with `useSignIn()` -The `useSignIn()` hook can also be used to build fully custom sign-in flows, if Clerk's prebuilt components don't meet your specific needs or if you require more control over the authentication flow. Different sign-in flows include email and password, email and phone codes, email links, and multifactor (MFA). To learn more about using the `useSignIn()` hook to create custom flows, check out the [custom flow guides](/docs/custom-flows/overview). +The `useSignIn()` hook can also be used to build fully custom sign-in flows, if Clerk's prebuilt components don't meet your specific needs or if you require more control over the authentication flow. Different sign-in flows include email and password, email and phone codes, email links, and multifactor (MFA). To learn more about using the `useSignIn()` hook to create custom flows, see the [custom flow guides](/docs/custom-flows/overview). diff --git a/docs/references/react/use-sign-up.mdx b/docs/references/react/use-sign-up.mdx index 00a7b85240..adceefd302 100644 --- a/docs/references/react/use-sign-up.mdx +++ b/docs/references/react/use-sign-up.mdx @@ -3,7 +3,7 @@ title: '`useSignUp()`' description: Clerk's useSignUp() hook gives you access to the SignUp object, which allows you to check the current state of a sign-up. --- -The `useSignUp()` hook gives you access to the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object, which allows you to check the current state of a sign-up. This is also useful for creating a [custom sign-up flow.](#create-a-custom-sign-up-flow-with-use-sign-up) +The `useSignUp()` hook gives you access to the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object, which allows you to check the current state of a sign-up. This is also useful for creating a [custom sign-up flow](#create-a-custom-sign-up-flow-with-use-sign-up). ## `useSignUp()` returns @@ -78,8 +78,8 @@ The `status` property of the `SignUp` object can be one of the following values: | - | - | | `complete` | The user has been created and custom flow can proceed to `setActive()` to create session. | | `abandoned` | The sign-up attempt will be abandoned if it was started more than 24 hours previously. | -| `missing_requirements` | A requirement from the [Email, Phone, Username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) settings is missing. For example, in the Clerk Dashboard, the Password setting is required but a password was not provided in the custom flow. | +| `missing_requirements` | A requirement from the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) settings is missing. For example, in the Clerk Dashboard, the password setting is required but a password was not provided in the custom flow. | ### Create a custom sign-up flow with `useSignUp()` -The `useSignUp()` hook can also be used to build fully custom sign-up flows, if Clerk's prebuilt components don't meet your specific needs or if you require more control over the authentication flow. Different sign-up flows include email and password, email and phone codes, email links, and multifactor (MFA). To learn more about using the `useSignUp()` hook to create custom flows, check out the [custom flow guides](/docs/custom-flows/overview). +The `useSignUp()` hook can also be used to build fully custom sign-up flows, if Clerk's prebuilt components don't meet your specific needs or if you require more control over the authentication flow. Different sign-up flows include email and password, email and phone codes, email links, and multifactor (MFA). To learn more about using the `useSignUp()` hook to create custom flows, see the [custom flow guides](/docs/custom-flows/overview). diff --git a/docs/references/redwood/overview.mdx b/docs/references/redwood/overview.mdx index 3b0c01d3fb..938bd3f4b0 100644 --- a/docs/references/redwood/overview.mdx +++ b/docs/references/redwood/overview.mdx @@ -26,7 +26,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user Below is an example of an `.env.local` file. - **Pro tip!** If you are signed into your Clerk Dashboard, your secret key should become visible by clicking on the eye icon. Otherwise, you can find your keys in the Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. + **Pro tip!** If you're signed into the Clerk Dashboard, your Secret Key should become visible by clicking on the eye icon. Otherwise, you can find your keys on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. ```env {{ filename: '.env.local' }} CLERK_PUBLISHABLE_KEY={{pub_key}} diff --git a/docs/references/remix/clerk-app.mdx b/docs/references/remix/clerk-app.mdx index 640f879ada..d165a65a56 100644 --- a/docs/references/remix/clerk-app.mdx +++ b/docs/references/remix/clerk-app.mdx @@ -52,7 +52,7 @@ export default ClerkApp(App) - `publishableKey` - `string` - Clerk publishable key for your instance. This can be found in your Clerk Dashboard on the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page. + Clerk Publishable 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. --- diff --git a/docs/references/remix/custom-signup-signin-pages.mdx b/docs/references/remix/custom-signup-signin-pages.mdx index 3943858c38..3157c9702e 100644 --- a/docs/references/remix/custom-signup-signin-pages.mdx +++ b/docs/references/remix/custom-signup-signin-pages.mdx @@ -5,12 +5,12 @@ description: Learn how to add custom sign-in and sign-up pages to your Remix app This guide shows you how to use the [``](/docs/components/authentication/sign-in) and [``](/docs/components/authentication/sign-up) components with the [Remix optional route](https://reactrouter.com/en/main/route/route#optional-segments) in order to build custom sign-in and sign-up pages for your Remix app. -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, check out the [custom flows](/docs/custom-flows/overview) guides. +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). -The functionality of the components are controlled by the instance settings you specify in your [Clerk Dashboard](https://dashboard.clerk.com). +The functionality of the components are controlled by the instance settings you specify in the [Clerk Dashboard](https://dashboard.clerk.com). > [!NOTE] -> Just getting started with Clerk and Remix? Check out the [quickstart tutorial](/docs/quickstarts/remix)! +> Just getting started with Clerk and Remix? See the [quickstart tutorial](/docs/quickstarts/remix)! ## Build your sign-up page diff --git a/docs/references/remix/spa-mode.mdx b/docs/references/remix/spa-mode.mdx index b6c68cd7c5..3c92e3c79b 100644 --- a/docs/references/remix/spa-mode.mdx +++ b/docs/references/remix/spa-mode.mdx @@ -45,18 +45,21 @@ description: Clerk supports Remix SPA mode out-of-the-box. ### Set your environment variables - 1. If you don't have an `.env` file in the root directory of your React project, create one now. - 1. Find your Clerk publishable key. If you're signed into Clerk, the `.env` snippet below will contain your key. Otherwise: - - Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys) and select your application. - - In the navigation sidebar, select **API Keys**. - - You can copy your key from the **Quick Copy** section. - 1. Add your key to your `.env` file. + + Add your Clerk Publishable Key to your `.env` file. It can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. + + + + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable Key. + 1. Paste your key into your `.env` file. + + The final result should resemble the following: + > [!WARNING] > You will not need the Clerk Secret Key in Remix SPA mode, as it should never be used on the client-side. - The final result should look as follows: - ```env {{ filename: '.env' }} VITE_CLERK_PUBLISHABLE_KEY={{pub_key}} ``` @@ -87,7 +90,7 @@ description: Clerk supports Remix SPA mode out-of-the-box. ) } - // Import your publishable key + // Import your Publishable Key const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY export default ClerkApp(App, { diff --git a/docs/references/ruby/overview.mdx b/docs/references/ruby/overview.mdx index 3820bf6764..71b1475fe9 100644 --- a/docs/references/ruby/overview.mdx +++ b/docs/references/ruby/overview.mdx @@ -6,7 +6,7 @@ description: Learn how to integrate Ruby into your Clerk application. ### Create a Clerk application - You need to create a Clerk application in your Clerk Dashboard before you can set up Clerk Ruby. For more information, check out our [Set up your application](/docs/quickstarts/setup-clerk) guide. + You need to create a Clerk application in the Clerk Dashboard before you can set up Clerk Ruby. For more information, see the [setup guide](/docs/quickstarts/setup-clerk). ### Install Ruby @@ -34,9 +34,9 @@ description: Learn how to integrate Ruby into your Clerk application. To access all [Backend API endpoints](/docs/reference/backend-api){{ target: '_blank' }}, you need to instantiate a `Clerk::SDK` instance. - You will need your Clerk secret key to instantiate an instance. Go to the Clerk Dashboard and navigate to the **[API Keys](https://dashboard.clerk.com/last-active?path=api-keys)** page and copy your secret key. + You will need your Clerk Secret Key to instantiate an instance. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page and copy your Secret Key. - This examples shows how to instantiate an instance of `Clerk::SDK` with your secret key and then send your first user a welcome email. + This examples shows how to instantiate an instance of `Clerk::SDK` with your Secret Key and then send your first user a welcome email. ```ruby clerk = Clerk::SDK.new(api_key: `{{secret}}`) @@ -92,7 +92,7 @@ description: Learn how to integrate Ruby into your Clerk application. end ``` - Refer to the [Faraday documentation](https://lostisland.github.io/faraday/#/) for details. + For more information, see [Faraday's documentation](https://lostisland.github.io/faraday/#/). #### Environment variables @@ -101,7 +101,7 @@ description: Learn how to integrate Ruby into your Clerk application. | Variable name | Usage | | - | - | | `CLERK_API_BASE` | Overrides the default API base URL: `https://api.clerk.com/v1/` | - | `CLERK_SECRET_KEY` | The Secret key of your instance (required) | + | `CLERK_SECRET_KEY` | The Secret Key of your instance (required) | | `CLERK_SIGN_IN_URL` | Rails view helper: `clerk_sign_in_url` | | `CLERK_SIGN_IN_UP` | Rails view helper: `clerk_sign_up_url` | | `CLERK_USER_PROFILE_URL` | Rails view helper: `clerk_user_profile_url` | diff --git a/docs/references/sdk/backend-only.mdx b/docs/references/sdk/backend-only.mdx index 788b53c43f..26ed2bbd9b 100644 --- a/docs/references/sdk/backend-only.mdx +++ b/docs/references/sdk/backend-only.mdx @@ -3,13 +3,13 @@ title: Backend-only SDK description: A reference for implementing a backend-only Clerk SDK --- -When creating a backend-only SDK, you have two options for implementing the [BAPI](/docs/references/sdk/terminology) endpoints: either [develop a backend SDK that encompasses all BAPI endpoints](#implementation-bapi) or [create an SDK tailored for an existing backend framework.](#implementation-node-js-backend-framework) +When creating a backend-only SDK, you have two options for implementing the [BAPI](/docs/references/sdk/terminology) endpoints: either [develop a backend SDK that encompasses all BAPI endpoints](#implementation-bapi) or [create an SDK tailored for an existing backend framework](#implementation-node-js-backend-framework). -The source of truth for all BAPI endpoints is the [BAPI OpenAPI spec](https://clerk.com/docs/reference/backend-api). For Node.js backend frameworks, you can build on top of the [JavaScript Backend SDK](/docs/references/backend/overview). +The source of truth for all BAPI endpoints is the [BAPI reference docs](/docs/reference/backend-api){{ target: '_blank' }}. For Node.js backend frameworks, you can build on top of the [JavaScript Backend SDK](/docs/references/backend/overview). ## Expected features -- User only needs to provide their [secret key](/docs/references/sdk/terminology) +- User only needs to provide their [Secret Key](/docs/references/sdk/terminology) - Centralized request authentication (e.g. in a middleware or plugin) - Give access to the instance of BAPI client (so that users can use all methods) - User should be able to limit access to routes by checking for [roles and permissions](/docs/organizations/roles-permissions) @@ -116,7 +116,7 @@ You can manually create a wrapper library around the [BAPI OpenAPI](https://cler ``` > [!TIP] - > Check out the Next.js [`getAuth()`](/docs/references/nextjs/get-auth) reference to see how it's implemented. + > See the Next.js [`getAuth()`](/docs/references/nextjs/get-auth) reference to see how it's implemented. ### Create a `requireAuth` helper diff --git a/docs/references/sdk/conventions.mdx b/docs/references/sdk/conventions.mdx index 646e918a62..2a63295009 100644 --- a/docs/references/sdk/conventions.mdx +++ b/docs/references/sdk/conventions.mdx @@ -19,7 +19,7 @@ Add **“Clerk”** as a prefix or postfix into the name as it’ll make the SDK ## Environment variables -Any environment variable used in the context of Clerk should be prefixed with `CLERK_`. [Learn more about Clerk environment variables.](/docs/deployments/clerk-environment-variables) +Any environment variable used in the context of Clerk should be prefixed with `CLERK_`. [Learn more about Clerk environment variables](/docs/deployments/clerk-environment-variables). > [!NOTE] > Depending on your framework, you’ll need to add a prefix to environment variables that should be available on the frontend. For example, `PUBLIC_`, `VITE_` or `NEXT_PUBLIC`. These alterations are fine. @@ -55,7 +55,7 @@ Use the template below to setup your own README. ### Prerequisites -- If you haven't already, [sign up for an account](https://dashboard.clerk.com/sign-up) and create a new application. Go to your [API keys](https://dashboard.clerk.com/last-active?path=api-keys) page and retrieve the publishable key and/or secret key. +- If you haven't already, [sign up for an account](https://dashboard.clerk.com/sign-up) and create a new application. Go to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page to retrieve your Publishable Key and/or Secret Key. @@ -67,7 +67,7 @@ Use the template below to setup your own README. ## Usage - + @@ -123,4 +123,4 @@ Your SDK will require your users to have Node.js installed and use the framework Security is important at Clerk and thus all Clerk SDKs are published with provenance statements. This allows you to publicly establish where a package was built and who published a package, which can increase supply-chain security for your packages. -Please read npm's guide on [generating provenance statements](https://docs.npmjs.com/generating-provenance-statements). +Read npm's guide on [generating provenance statements](https://docs.npmjs.com/generating-provenance-statements). diff --git a/docs/references/sdk/frontend-only.mdx b/docs/references/sdk/frontend-only.mdx index 3ed76b02fe..90cc2df444 100644 --- a/docs/references/sdk/frontend-only.mdx +++ b/docs/references/sdk/frontend-only.mdx @@ -9,7 +9,7 @@ In non-browser environments, you’ll need to re-implement the [Clerk class](/do ## Expected features -- User only needs to provide their [publishable key](/docs/references/sdk/terminology) +- User only needs to provide their [Publishable Key](/docs/references/sdk/terminology) - User only needs to adjust one or two files to add Clerk to their app (e.g. adding Clerk to the configuration file of that framework) - User can use [Clerk’s components](/docs/components/overview) in their choice of framework (e.g. in a React-based framework you import these components as React components) - Give users access to [`Client`](/docs/references/javascript/client){{ target: '_blank' }}, [`Session`](/docs/references/javascript/session){{ target: '_blank' }}, [`User`](/docs/references/javascript/user/user){{ target: '_blank' }}, and [`Organization`](/docs/references/javascript/organization/organization){{ target: '_blank' }} properties through the framework’s choice of state management diff --git a/docs/references/sdk/fullstack.mdx b/docs/references/sdk/fullstack.mdx index 1de5c99fe9..de63c85293 100644 --- a/docs/references/sdk/fullstack.mdx +++ b/docs/references/sdk/fullstack.mdx @@ -7,7 +7,7 @@ A fullstack SDK combines the [frontend-only SDK](/docs/references/sdk/frontend-o ## Expected features -- User only needs to provide their [publishable key](/docs/references/sdk/terminology) and [secret key](/docs/references/sdk/terminology) +- User only needs to provide their [Publishable Key](/docs/references/sdk/terminology) and [Secret Key](/docs/references/sdk/terminology) - User only needs to adjust one or two files to add Clerk to their app (e.g. adding Clerk to the configuration file of that framework) - User can use [Clerk’s components](/docs/components/overview) in their choice of framework (e.g. in a React-based framework you import these components as React components) - Give users access to [`Client`](/docs/references/javascript/client){{ target: '_blank' }}, [`Session`](/docs/references/javascript/session){{ target: '_blank' }}, [`User`](/docs/references/javascript/user/user){{ target: '_blank' }}, and [`Organization`](/docs/references/javascript/organization/organization){{ target: '_blank' }} properties through the framework’s choice of state management @@ -23,7 +23,7 @@ A fullstack SDK combines the [frontend-only SDK](/docs/references/sdk/frontend-o ## Implementation -Please check out the respective [frontend-only SDK](/docs/references/sdk/frontend-only) and [backend-only SDK](/docs/references/sdk/backend-only) implementation instructions. +See the respective [frontend-only SDK](/docs/references/sdk/frontend-only) and [backend-only SDK](/docs/references/sdk/backend-only) implementation instructions. In addition to these instructions, you'll need to go through the following steps to support all required features. diff --git a/docs/references/sdk/terminology.mdx b/docs/references/sdk/terminology.mdx index 8a4768e864..c4912e80b5 100644 --- a/docs/references/sdk/terminology.mdx +++ b/docs/references/sdk/terminology.mdx @@ -13,9 +13,9 @@ A consistent terminology should be used across all user interactions with Clerk' | Organization | An [organization](/docs/references/javascript/organization/organization){{ target: '_blank' }} represents the current organization of the session. Users can belong to many organizations. One of them will be the [active organization](/docs/organizations/overview#active-organization) of the session. | | FAPI | [Frontend API of Clerk](/docs/reference/frontend-api){{ target: '_blank' }}. Example: `https://random-name.clerk.accounts.dev` (Production example: `https://clerk.yourdomain.com`). FAPI is the primary API for Clerk’s UI components. Every Clerk development/production instance has a dedicated FAPI. This is the authentication, session, user & organization management API you or your users will interact with. | | BAPI | [Backend API of Clerk](/docs/reference/backend-api){{ target: '_blank' }}. Currently set to `https://api.clerk.com`. A restful CRUD API for the server-side. | -| Secret key | Your app’s secret key for use in the backend. Do not expose this on the frontend with a public environment variable. Allows for CRUD operations. | -| Publishable key | Your app’s publishable key for use in the frontend. | -| Instances | When creating an app, you’re provided with two instances: Development and Production. [Learn more.](/docs/deployments/environments) | +| Secret Key | Your app’s Secret Key for use in the backend. Do not expose this on the frontend with a public environment variable. Allows for CRUD operations. | +| Publishable Key | Your app’s Publishable Key for use in the frontend. | +| Instances | When creating an app, you’re provided with two instances: Development and Production. [Learn more](/docs/deployments/environments). | | Hotloading ClerkJS | `@clerk/clerk-js`, or ClerkJS, is the foundational JavaScript library for all frontend JS SDKs, e.g. used in `@clerk/clerk-react`. When you install `@clerk/clerk-react` through npm, you don’t install `@clerk/clerk-js`. Instead, once the React code is executed in the browser, the React SDK adds a `