diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4136a9f280..398002e105 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -439,18 +439,18 @@ console.log('ignored') ### `` -The `` component is used to number a set of instructions with an outcome. It uses the highest heading available in the component to denote each step. Can be used with `h3` headings. +The `` component is used to number a set of instructions with an outcome. It uses the highest heading available in the component to denote each step. Can be used with `h2` and `h3` headings. ```mdx -### Step 1 +## Step 1 Do these actions to complete Step 1. -### Another step +## Another step -#### A heading inside a step +### A heading inside a step Do these actions to complete Step 2. diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index 3ae5b0ce3f..ffe342ec81 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -25,7 +25,7 @@ This guide explains how to use a custom [OpenID Connect (OIDC)](https://openid.n 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 Identity Provider (IdP). - ### Set up an enterprise connection in Clerk + ## Set up an enterprise 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. Select **Add connection** and select **For specific domains**. @@ -35,14 +35,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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**. You will be redirected to the connection's configuration page. Keep this page open. - ### Configure your IdP + ## Configure your IdP 1. If necessary, create a new application in your IdP. 1. In the connection's configuration page of the Clerk Dashboard, copy the **Authorized redirect URI**. 1. Add the value to your IdP's whitelisted URLs. 1. Find your application's **Discovery Endpoint**, **Client ID**, and **Client Secret** and copy them. - ### Set the Discovery Endpoint, Client ID, and Client Secret in Clerk + ## Set the Discovery Endpoint, Client ID, and Client Secret in Clerk 1. In your IdP settings, copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**. 1. In the connection's configuration page in the Clerk Dashboard, paste these values in their respective fields. @@ -52,7 +52,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open > [!NOTE] > Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, in the connection's configuration page in the Clerk Dashboard, find the **Identity Provider Configuration** section and select **Use Manual Configuration** to manually configure the connection. - ### Configure attribute mapping (optional) + ## Configure attribute mapping (optional) Clerk expects the claims returned by your IdP to follow the [OIDC Standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. @@ -61,7 +61,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open > > If the IdP doesn't return this claim, you can leave the **Email address verified** field blank and set the **Default value** to **True**. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth). - ### Allow additional identifiers (optional) + ## Allow additional identifiers (optional) User profile information is sourced from the IdP. To allow users to add new identifiers (e.g., email address or phone number) to their profiles: @@ -69,14 +69,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Enable **Allow additional identifiers**. 1. Select **Save**. - ### Enable the connection for Clerk + ## Enable the connection for Clerk 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. At the top of the page, toggle on **Enable connection** and select **Save**. - ### Test your connection + ## Test your connection The simplest way to test your enterprise connection 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. diff --git a/docs/authentication/enterprise-connections/saml/azure.mdx b/docs/authentication/enterprise-connections/saml/azure.mdx index 87a7039fc4..67a08b2cbd 100644 --- a/docs/authentication/enterprise-connections/saml/azure.mdx +++ b/docs/authentication/enterprise-connections/saml/azure.mdx @@ -25,7 +25,7 @@ Enabling single sign-on (SSO) with **Microsoft Azure Entra ID** (formerly [Activ 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 + ## Set up an enterprise connection in Clerk To create a SAML connection in Clerk: @@ -38,7 +38,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Find the **Service Provider Configuration** section. 1. Save the **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step. Leave this page open. - ### Create a new enterprise app in Microsoft + ## Create a new enterprise app in Microsoft To create a new enterprise app in Microsoft: @@ -52,7 +52,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open - Ensure the option **Integrate any other application you don't find in the gallery (Non-gallery)** is selected. - Select **Create**. - ### Assign selected user or group in Microsoft + ## Assign selected user or group in Microsoft Now that you have created the enterprise app, you need to assign users or groups to the app. For example, if you were part of the Clerk organization, you would have access to users and groups within the Clerk organization. In this case, you could assign individual users or entire groups to the enterprise app you just created. @@ -63,14 +63,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Select** at the bottom of the page. You'll be redirected to the **Add Assignment** page. 1. Select **Assign** at the bottom of the page. - ### Configure SSO in Microsoft + ## Configure SSO in Microsoft After assigning the user or group to the enterprise app, you need to configure the SSO settings to enable SAML SSO. 1. In the navigation sidebar, open the **Manage** dropdown and select **Single sign-on**. 1. In the **Select a single sign-on method** section, select **SAML**. - ### Configure your service provider + ## Configure your service provider To configure Clerk as your service provider, add these two fields to your IdP's application: @@ -84,7 +84,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Paste the **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)** values you saved earlier into their respective fields. These values will be saved automatically. 1. Select **Save** at the top of the panel. Close the panel. - ### Configure your identity provider + ## Configure your identity provider To configure Microsoft Entra ID as your identity provider, add the following fields to your app: @@ -93,7 +93,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Navigate back to the **Clerk Dashboard**. In the **Identity Provider Configuration** section, under **App Federation Metadata Url**, paste the **App Federation Metadata URL**. 1. Select **Fetch & save**. - ### Map Microsoft claims to Clerk attributes + ## Map Microsoft claims to Clerk attributes Mapping the claims in your IdP to the attributes in Clerk ensures that the data from your IdP is correctly mapped to the data in Clerk. @@ -112,7 +112,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Next to **Source attribute**, search for and select `user.userprincipalname` in the dropdown. 1. Select **Save** at the top of the page. - ### Enable the connection for Clerk + ## Enable the connection for Clerk To make the connection available for your users to authenticate with: diff --git a/docs/authentication/enterprise-connections/saml/custom-provider.mdx b/docs/authentication/enterprise-connections/saml/custom-provider.mdx index b717cfa88e..e0dbd4a0d6 100644 --- a/docs/authentication/enterprise-connections/saml/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/saml/custom-provider.mdx @@ -22,10 +22,8 @@ description: Learn how to integrate an Identity Provider with Clerk using SAML S 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 - - ### Set up an enterprise connection in Clerk + ## Set up an enterprise connection in Clerk To create a SAML connection in Clerk: @@ -36,23 +34,23 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth 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 enterprise application in your IdP 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 + ## Configure your Identity Provider There are two options for configuring your IdP: - [**Metadata configuration**](#metadata-configuration) - This is where you can download your IdP's metadata file or input the metadata URL that you got from your IdP. This is the recommended way to configure your IdP, but not all IdPs support this method. - [**Custom configuration**](#custom-configuration) - This is where you can manually input the configuration settings for your IdP. - #### Metadata configuration + ### Metadata configuration 1. In your IdP dashboard, find where you can download the metadata file or copy the metadata URL. 1. In the Clerk Dashboard on the connection's configuration page, under **Identity Provider Configuration**,select **Add via metadata**. Input the metadata URL or upload the metadata file that you got from your IdP. - #### Custom configuration + ### Custom configuration If you choose to manually input the configuration settings for your IdP, you will need to fill these three fields in the Clerk Dashboard: diff --git a/docs/authentication/enterprise-connections/saml/google.mdx b/docs/authentication/enterprise-connections/saml/google.mdx index 010d286a92..4ec7423f1c 100644 --- a/docs/authentication/enterprise-connections/saml/google.mdx +++ b/docs/authentication/enterprise-connections/saml/google.mdx @@ -20,10 +20,8 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. - Use Google Workspace to enable single sign-on (SSO) via SAML for your Clerk application. -## Tutorial - - ### Set up an enterprise connection in Clerk + ## Set up an enterprise connection in Clerk To create a SAML connection in Clerk: @@ -34,7 +32,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. 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'll be redirected to the connection's configuration page. - ### Create a new enterprise application in Google + ## Create a new enterprise application in Google To create a new enterprise application in Google: @@ -45,20 +43,20 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. 1. In the **App details** section, an **App name** is required. 1. Select the **Continue** button. - ### Configure your identity provider + ## Configure your identity provider There are two options for configuring your IdP: - [**Metadata configuration**](#metadata-configuration) - This is where you can input the URL to your IdP's metadata file. This is the recommended way to configure your IdP. - [**Custom configuration**](#custom-configuration) - This is where you can manually input the configuration settings for your IdP. - #### Metadata configuration + ### Metadata configuration 1. In the Google Admin Console, under **Option 1: Download IdP Metadata**, select the **Download Metadata** button. 1. Navigate back to the Clerk Dashboard and in the **Identity Provider Configuration** section, select the **Upload file** button. 1. Upload the metadata file you downloaded from Google. - #### Custom configuration + ### Custom configuration If you choose to manually input the configuration settings for your IdP, you must add these three fields to your Clerk settings: @@ -71,7 +69,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. 1. Fill in the **SSO URL**, **Entity ID**, and upload the **Certificate**. Don't forget to select **Save**. 1. In the Google Admin Console, select the **Continue** button. - ### Configure your service provider + ## Configure your service provider To configure your service provider (Clerk), you will need to add these two fields to your IdP's application: @@ -85,7 +83,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. 1. In the Google Admin Console, paste these values into their respective fields. 1. Under the **Name ID** section, select the dropdown for **Name ID format** and select **Email**. - ### Map Google claims to Clerk attributes + ## Map Google claims to Clerk attributes Mapping the claims in your IdP to the attributes in Clerk ensures that the data from your IdP is correctly mapped to the data in Clerk. @@ -103,7 +101,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. 1. Enter `mail` in the field. 1. If you have additional claims that you would like to map to Clerk, you can do so by following the steps in the [Map other claims](#map-other-claims-optional) section. Otherwise, select the **Finish** button. - #### Map other claims (optional) + ### Map other claims (optional) In Clerk, the [`User`](/docs/users/overview#user-object) object has a `publicMetadata` property that you can use to store additional information about your users. @@ -121,7 +119,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. Learn more about [how to access the metadata from our APIs](/docs/users/metadata). - ### Enable the connection on Google + ## Enable the connection on Google Once the configuration is complete, you will be redirected to the app details page. @@ -129,7 +127,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. 1. In the **Service status** section, select **ON for everyone**. 1. Select the **Save** button. - ### Enable the connection for Clerk + ## Enable the connection for Clerk To make the connection available for your users to authenticate with: diff --git a/docs/authentication/enterprise-connections/saml/okta.mdx b/docs/authentication/enterprise-connections/saml/okta.mdx index f530a92eae..2ba9589b4c 100644 --- a/docs/authentication/enterprise-connections/saml/okta.mdx +++ b/docs/authentication/enterprise-connections/saml/okta.mdx @@ -20,10 +20,8 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. - Use Okta Workforce to enable single sign-on (SSO) via SAML for your Clerk application. -## Tutorial - - ### Set up an enterprise connection in Clerk + ## Set up an enterprise connection in Clerk To create a SAML connection in Clerk: @@ -37,7 +35,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. 1. Save the **Single sign-on URL** and the **Audience URI (SP Entity ID)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step. 1. Leave this page open. - ### Create a new enterprise application in Okta + ## Create a new enterprise application in Okta To create a new enterprise application in Okta: @@ -49,7 +47,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. 1. Once redirected to the **Create SAML Integration** page, fill in the **General Settings** fields. An **App name** is required. 1. Select the **Next** button to continue. - ### Configure your service provider + ## Configure your service provider Once you have moved forward from the **General Settings** instructions, you will be presented with the **Configure SAML** page. @@ -62,7 +60,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. 1. Paste the **Single sign-on URL** and the **Audience URI (SP Entity ID)** values that you saved earlier into their respective fields. - ### Map Okta claims to Clerk attributes + ## Map Okta claims to Clerk attributes Mapping the claims in your IdP to the attributes in Clerk ensures that the data from your IdP is correctly mapped to the data in Clerk. @@ -84,7 +82,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. 1. Scroll to the bottom of the page and select the **Next** button to continue. 1. You will be redirected to the **Feedback** page. Fill out the feedback however you would like and select the **Finish** button to complete the setup. - ### Assign selected user or group in Okta + ## Assign selected user or group in Okta You need to assign your users/user groups to your enterprise application. For example, if you were part of the Clerk organization, you would have access to users and groups in the Clerk organization. In this case, you could assign one or more users or entire groups to the enterprise application you just created. @@ -94,7 +92,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. 1. Select the **Assign** button next to the user or group that you want to assign. 1. Select the **Done** button to complete the assignment. - ### Configure your identity provider + ## Configure your identity provider Once you have completed the setup in Okta, you will be redirected to the application instances page with the **Sign On** tab selected. @@ -103,7 +101,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. 1. Under the **Metadata configuration** option, paste the **Metadata URL**. 1. Select the **Fetch & save** button to complete the setup. - ### Enable the connection for Clerk + ## Enable the connection for Clerk To make the connection available for your users to authenticate with: diff --git a/docs/authentication/social-connections/spotify.mdx b/docs/authentication/social-connections/spotify.mdx index 14bf02bde1..93023f25ab 100644 --- a/docs/authentication/social-connections/spotify.mdx +++ b/docs/authentication/social-connections/spotify.mdx @@ -28,7 +28,7 @@ Enabling OAuth with [Spotify](https://developer.spotify.com/documentation/web-ap 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 + ## 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. Select **Add connection** and select **For all users**. @@ -36,7 +36,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. 1. Save the **Redirect URI** somewhere secure. Keep the modal and page open. - ### Create your app in Spotify + ## Create your app in Spotify 1. On a separate page, go to the [Spotify Developer Dashboard](https://developer.spotify.com/) and sign in. 1. In the top-right, select your profile button and select [**Dashboard**](https://developer.spotify.com/dashboard). @@ -45,7 +45,7 @@ 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 the 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 the Clerk Dashboard where the modal should still be open and paste these values into the respective fields. diff --git a/docs/authentication/social-connections/x-twitter.mdx b/docs/authentication/social-connections/x-twitter.mdx index 296986e1c3..4610f5a6d9 100644 --- a/docs/authentication/social-connections/x-twitter.mdx +++ b/docs/authentication/social-connections/x-twitter.mdx @@ -23,15 +23,13 @@ description: Learn how to set up a social connection with X/Twitter v2 in your C - Set X/Twitter's **Client ID** and **Client Secret** in the Clerk Dashboard -## Overview - Clerk does not currently support preconfigured shared OAuth credentials for X/Twitter on development instances. This means you will have to provide custom credentials for both development _and_ production instances, which involves generating your own **Client ID** and **Client Secret** using your X/Twitter Developer account. This tutorial will walk you through that process in just a few simple steps. > [!WARNING] > X/Twitter v2 is currently not providing email addresses of users. The user will have to fill in their email address manually when they return to your application after authenticating with X/Twitter. - ### Create an X/Twitter application + ## Create an X/Twitter application If you don't have an existing X/Twitter application you've set up for social connection, you need to register a new one at the [X/Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard). Note that the process requires approval from X/Twitter before your new application can be used. @@ -40,7 +38,7 @@ Clerk does not currently support preconfigured shared OAuth credentials for X/Tw 1. Navigate to the X/Twitter Developer Portal and go to [**Projects & Apps**](https://developer.twitter.com/en/portal/projects-and-apps). 1. Select **+ Add App**. After entering a name, you will be presented with your app's credentials. However, for setting up the X/Twitter v2 social connection with Clerk, **you won't need these credentials**. This is because you will be utilizing the OAuth 2.0 flow, which relies on different authentication details. - ### Enable X/Twitter as a social connection + ## Enable X/Twitter as a social connection To enable X/Twitter as a social connection for your Clerk application: @@ -49,7 +47,7 @@ Clerk does not currently support preconfigured shared OAuth credentials for X/Tw 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. - ### Set the Redirect URI in your X/Twitter application + ## Set the Redirect URI in your X/Twitter application 1. Navigate back to the X/Twitter Developer portal. 1. On the application settings screen, scroll down to the **User authentication settings** section and select **Set up**. You'll be presented with the **User authentication settings** page. @@ -58,7 +56,7 @@ 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 the 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**. @@ -67,7 +65,7 @@ Clerk does not currently support preconfigured shared OAuth credentials for X/Tw > [!NOTE] > 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 + ## 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. diff --git a/docs/backend-requests/making/custom-session-token.mdx b/docs/backend-requests/making/custom-session-token.mdx index ee28e7e925..4b4973f87e 100644 --- a/docs/backend-requests/making/custom-session-token.mdx +++ b/docs/backend-requests/making/custom-session-token.mdx @@ -11,10 +11,8 @@ This guide will show you how to customize a session token to include additional -{/* TODO: Update the H3 to an H2 when the Steps component can accept headings other than H3. */} - - ### Add custom claims to your session token + ## Add custom claims to your session token 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. @@ -24,7 +22,7 @@ This guide will show you how to customize a session token to include additional ![Clerk Dashboard showing the custom claim modal](/docs/images/advance/session-tokens/custom-session-example.png) - ### Use the custom claims in your application + ## Use the custom claims in your application The [`Auth`](/docs/references/nextjs/auth-object) object in the `@clerk/nextjs` package includes a `sessionClaims` property that contains the custom claims you added to your session token. @@ -64,7 +62,7 @@ This guide will show you how to customize a session token to include additional ``` - ### Add global TypeScript type for custom session claims + ## Add global TypeScript type for custom session claims To get auto-complete and prevent TypeScript errors when working with custom session claims, you can define a global type. diff --git a/docs/custom-flows/bot-sign-up-protection.mdx b/docs/custom-flows/bot-sign-up-protection.mdx index 20bf49b4cc..e6c63a18b5 100644 --- a/docs/custom-flows/bot-sign-up-protection.mdx +++ b/docs/custom-flows/bot-sign-up-protection.mdx @@ -8,12 +8,12 @@ description: Learn how to add Clerk's bot protection to your custom sign-up flow Clerk provides the ability to add a CAPTCHA widget to your sign-up flows to protect against bot sign-ups. The [``](/docs/components/authentication/sign-up) component handles this flow out-of-the-box. However, if you're building a custom user interface, this guide will show you how to add the CAPTCHA widget to your custom sign-up flow. - ### Enable bot sign-up protection + ## Enable bot sign-up 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 + ## Add the CAPTCHA widget to your custom sign-up form To render the CAPTCHA widget in your custom sign-up form, you need to include a specific element in your DOM. Specifically, there should be a `
` element by the time you call `signUp.create()`. This element acts as a placeholder onto which the widget will be rendered. diff --git a/docs/custom-flows/email-password-mfa.mdx b/docs/custom-flows/email-password-mfa.mdx index d4861d8c4a..2296237854 100644 --- a/docs/custom-flows/email-password-mfa.mdx +++ b/docs/custom-flows/email-password-mfa.mdx @@ -11,10 +11,8 @@ Clerk supports second factor verification through **SMS verification code**, **A This guide will walk you through how to build a custom email/password sign-in flow that supports **Authenticator application** and **Backup codes** as the second factor. -{/* TODO: Update these Steps when the Steps component can accept other headings. As of right now, Steps can only accept H3s. */} - - ### Enable email and password authentication + ## Enable email and password authentication 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. @@ -22,7 +20,7 @@ This guide will walk you through how to build a custom email/password sign-in fl 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. - ### Enable multi-factor authentication + ## Enable multi-factor authentication 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. @@ -30,7 +28,7 @@ This guide will walk you through how to build a custom email/password sign-in fl 1. For the purpose of this guide, toggle on both the **Authenticator application** and **Backup codes** strategies. 1. Select **Save**. - ### Sign-in flow + ## Sign-in flow Signing in to an MFA-enabled account is identical to the regular sign-in process. However, in the case of an MFA-enabled account, a sign-in won't convert until both first factor and second factor verifications are completed. diff --git a/docs/custom-flows/email-password.mdx b/docs/custom-flows/email-password.mdx index 91d7f95dda..d22ac988ff 100644 --- a/docs/custom-flows/email-password.mdx +++ b/docs/custom-flows/email-password.mdx @@ -10,7 +10,7 @@ This guide will walk you through how to build a custom email/password sign-up an {/* TODO: Update these Steps when the Steps component can accept other headings. As of right now, Steps can only accept H3s. */} - ### Enable email and password authentication + ## Enable email and password authentication 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. @@ -21,7 +21,7 @@ This guide will walk you through how to build a custom email/password sign-up an > [!NOTE] > By default, the [verification method](/docs/authentication/configuration/sign-up-sign-in-options#verification-methods) for the **Email address** strategy is set to **Email verification code**. This means that when a user signs up using their email address and password, Clerk sends a one-time code to their email address. The user must then enter this code to verify their email and complete the sign-up process. - ### Sign-up flow + ## Sign-up flow To sign up a user using their email, password, and email verification code, you must: @@ -467,7 +467,7 @@ This guide will walk you through how to build a custom email/password sign-up an - ### Sign-in flow + ## Sign-in flow To authenticate a user using their email and password, you must: diff --git a/docs/custom-flows/email-sms-otp.mdx b/docs/custom-flows/email-sms-otp.mdx index 363d863d34..9eaec44650 100644 --- a/docs/custom-flows/email-sms-otp.mdx +++ b/docs/custom-flows/email-sms-otp.mdx @@ -9,10 +9,8 @@ Clerk supports passwordless authentication, which lets users sign in and sign up This guide will walk you through how to build a custom SMS OTP sign-up and sign-in flow. The process for using email OTP is similar, and the differences will be highlighted throughout. -{/* TODO: Update these Steps when the Steps component can accept other headings. As of right now, Steps can only accept H3s. */} - - ### Enable SMS OTP + ## Enable SMS OTP To use SMS OTP as an authentication strategy, you first need to enable it in the Clerk Dashboard. @@ -20,7 +18,7 @@ This guide will walk you through how to build a custom SMS OTP sign-up and sign- 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. - ### Sign-up flow + ## Sign-up flow To sign up a user using an OTP, you must: @@ -306,7 +304,7 @@ This guide will walk you through how to build a custom SMS OTP sign-up and sign- To create a sign-up flow for email OTP, use the [`prepareEmailAddressVerification`](/docs/references/javascript/sign-up/email-verification#prepare-email-address-verification) and [`attemptEmailAddressVerification`](/docs/references/javascript/sign-up/email-verification#attempt-email-address-verification). These helpers work the same way as their phone number counterparts do in the previous example. You can find all available methods in the [`SignUp`](/docs/references/javascript/sign-in/sign-in) object documentation. - ### Sign-in flow + ## Sign-in flow To authenticate a user with an OTP, you must: diff --git a/docs/custom-flows/embedded-email-links.mdx b/docs/custom-flows/embedded-email-links.mdx index a7c6a6a6e9..2af4535257 100644 --- a/docs/custom-flows/embedded-email-links.mdx +++ b/docs/custom-flows/embedded-email-links.mdx @@ -15,7 +15,7 @@ Common use cases include: This guide will demonstrate how to generate a sign-in token and use it to sign in a user. - ### Generate a sign-in token + ## Generate a sign-in token [Sign-in tokens](/docs/reference/backend-api/tag/Sign-in-Tokens#operation/CreateSignInToken){{ target: '_blank' }} are JWTs that can be used to sign in to an application without specifying any credentials. A sign-in token can be used **once**, and can be consumed from the Frontend API using the [`ticket`](/docs/references/javascript/sign-in/sign-in#sign-in-create-params) strategy, which is demonstrated in the following example. @@ -40,7 +40,7 @@ This guide will demonstrate how to generate a sign-in token and use it to sign i Then, you can embed this link anywhere, such as an email. - ### Build a custom flow for signing in with a sign-in token + ## Build a custom flow for signing in with a sign-in token To handle email links with sign-in tokens, you must set up a page in your frontend that detects the token, signs the user in, and performs any additional actions you need. diff --git a/docs/custom-flows/google-one-tap.mdx b/docs/custom-flows/google-one-tap.mdx index 0023351877..d072ead81d 100644 --- a/docs/custom-flows/google-one-tap.mdx +++ b/docs/custom-flows/google-one-tap.mdx @@ -10,11 +10,11 @@ description: Learn how to build a custom Google One Tap authentication flow usin This guide will walk you through how to build a custom Google One Tap authentication flow. - ### Enable Google as a social connection + ## 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. - ### Create the Google One Tap authentication flow + ## Create the Google One Tap authentication flow To authenticate users with Google One Tap, you must: diff --git a/docs/custom-flows/manage-sms-based-mfa.mdx b/docs/custom-flows/manage-sms-based-mfa.mdx index a16224c6fa..34d75f7092 100644 --- a/docs/custom-flows/manage-sms-based-mfa.mdx +++ b/docs/custom-flows/manage-sms-based-mfa.mdx @@ -13,14 +13,14 @@ One of the options that Clerk supports for MFA is **SMS verification codes**. Th > To learn how to build a custom flow for managing authenticator app (TOTP) MFA, see the [dedicated guide](/docs/custom-flows/manage-totp-based-mfa). - ### Enable multi-factor authentication + ## Enable multi-factor authentication 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. 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 + ## Create the multi-factor management flow This example is written for Next.js App Router but it can be adapted for any React meta framework, such as Remix. diff --git a/docs/custom-flows/manage-totp-based-mfa.mdx b/docs/custom-flows/manage-totp-based-mfa.mdx index 62fee0ab1a..9710cfe585 100644 --- a/docs/custom-flows/manage-totp-based-mfa.mdx +++ b/docs/custom-flows/manage-totp-based-mfa.mdx @@ -13,7 +13,7 @@ One of the options that Clerk supports for MFA is **Authenticator applications ( > To learn how to build a custom flow for managing SMS MFA, see the [dedicated guide](/docs/custom-flows/manage-sms-based-mfa). - ### Enable multi-factor authentication + ## Enable multi-factor authentication 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. @@ -21,7 +21,7 @@ One of the options that Clerk supports for MFA is **Authenticator applications ( 1. Enable **Authenticator application** and **Backup codes**. 1. Select **Save**. - ### Create the multi-factor management flow + ## Create the multi-factor management flow @@ -306,7 +306,7 @@ One of the options that Clerk supports for MFA is **Authenticator applications ( - #### Force MFA (optional) + ### Force MFA (optional) While Clerk does not natively enforce MFA for all users, you can implement this functionality by using `clerkMiddleware()` to check whether a user has MFA enabled. diff --git a/docs/customization/elements/guides/sign-in.mdx b/docs/customization/elements/guides/sign-in.mdx index a2d83b1440..003a318b7d 100644 --- a/docs/customization/elements/guides/sign-in.mdx +++ b/docs/customization/elements/guides/sign-in.mdx @@ -34,7 +34,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. > - Clerk Elements currently only works with Next.js App Router and [Clerk Core 2](/changelog/2024-04-19){{ target: '_blank' }}. As it gets closer to a stable release, support for additional frameworks will be added. - ### Add a sign-in route + ## Add a sign-in route Create a new route in your Next.js application. The route needs to be an [optional catch-all route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) so the sign-in flow can handled nested paths, as shown in the following example: @@ -54,7 +54,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. > [!TIP] > If you're getting TypeScript errors on the `@clerk/elements` imports you probably have forgotten to set your [`moduleResolution`](https://www.typescriptlang.org/tsconfig/#moduleResolution) in `tsconfig.json` to `bundler`. - ### Add the start step + ## Add the start step The Clerk authentication flows are made up of **steps**. Steps handle rendering the UI for each part of the flow. To allow users to create a sign-in attempt, the `start` step needs to be rendered. The following example does so with the `` component: @@ -75,7 +75,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. } ``` - ### Add form fields + ## Add form fields Make it functional by adding input fields. The following example uses the `` component to render an `identifier` field, as well as the `` component to allow users to sign in with a social connection, like Google: @@ -111,7 +111,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. > [!NOTE] > If your Clerk instance supports signing in with Google and doesn't require multi-factor authentication (MFA), you should be able to complete a sign-in with the components rendered so far. - ### Add verification + ## Add verification As users progress through a sign-in attempt, they may be asked to **verify** a number of authentication factors in the `verifications` step. You can render a form for the user to complete verification, but each [verification strategy](/docs/customization/elements/reference/sign-in#strategy) requires different fields. You must render the form fields conditionally for each authentication strategy your instance supports using the `` component. @@ -163,7 +163,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. Verification is the final step in the sign-in flow. When a user has verified all required factors, the sign-in attempt will be complete and they will be signed in. - ### Add password support + ## Add password support If your instance is configured to support authenticating with passwords, you must add a few additional steps and verification strategies. You can choose if you want to support providing a password in the `start` step with an additional field, or as an additional verification strategy. For this guide, add it as a standalone verification strategy. @@ -276,7 +276,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. > [!NOTE] > If your instance isn't configured to use passwords, or any of the strategies outlined here, Clerk Elements will log a warning to the console during development. - ### Customize and add styling + ## Customize and add styling Learn how to style your Clerk Elements components with the [styling guide](/docs/customization/elements/guides/styling). diff --git a/docs/customization/elements/guides/sign-up.mdx b/docs/customization/elements/guides/sign-up.mdx index eb9e04d147..85e41b892d 100644 --- a/docs/customization/elements/guides/sign-up.mdx +++ b/docs/customization/elements/guides/sign-up.mdx @@ -34,7 +34,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. > - Clerk Elements currently only works with Next.js App Router and [Clerk Core 2](/changelog/2024-04-19){{ target: '_blank' }}. As it gets closer to a stable release, support for additional frameworks will be added. - ### Add a sign-up route + ## Add a sign-up route Create a new route in your Next.js application. The route needs to be an [optional catch-all route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) so the sign-up flow can handled nested paths, as shown in the following example: @@ -54,7 +54,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. > [!TIP] > If you're getting TypeScript errors on the `@clerk/elements` imports you probably have forgotten to set your [`moduleResolution`](https://www.typescriptlang.org/tsconfig/#moduleResolution) in `tsconfig.json` to `bundler`. - ### Add the start step + ## Add the start step The Clerk authentication flows are made up of **steps**. Steps handle rendering the UI for each part of the flow. To allow users to create a sign-up attempt, the `start` step needs to be rendered. The following example does so with the `` component: @@ -75,7 +75,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. } ``` - ### Add form fields + ## Add form fields Make it functional by adding input fields. The following example uses the `` component to render the `emailAddress` and `username` fields, as well as the `` component to allow users to sign up with a social connection, like Google: @@ -122,7 +122,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. `` takes care of wiring up the input with the label element, and `` will render any field-specific errors that get returned from Clerk's API. The `` component provides common actions that are used throughout the flows. In this case, using the `submit` action to render a submit button for the start form. - ### Add verification + ## Add verification As users progress through a sign-up attempt, they may be asked to **verify** a number of authentication factors in the `verifications` step. You can render a form for the user to complete verification, but each [verification strategy](/docs/customization/elements/reference/sign-in#strategy) requires different fields. You must render the form fields conditionally for each authentication strategy your instance supports using the `` component. @@ -195,7 +195,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. Verification is the final step in the sign-up flow. When a user has verified all required factors, the sign-up attempt will be complete, their account will be created, and they will be signed in. - ### Accept additional fields + ## Accept additional fields Should a user attempt to sign up via Google while a username is a required field, the `continue` step will be necessary to accept the username. The `` component will display any additional required fields. @@ -281,7 +281,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. > [!NOTE] > Under the hood, Clerk Elements will conditionally render the fields that are necessary to complete the sign up attempt, so there's no need to check the state of the sign up attempt yourself. - ### Customize and add styling + ## Customize and add styling Learn how to style your Clerk Elements components with the [styling guide](/docs/customization/elements/guides/styling). diff --git a/docs/deployments/migrate-from-firebase.mdx b/docs/deployments/migrate-from-firebase.mdx index 9a7971d49b..bb12619e42 100644 --- a/docs/deployments/migrate-from-firebase.mdx +++ b/docs/deployments/migrate-from-firebase.mdx @@ -6,9 +6,9 @@ description: Migrating your user base from Firebase to Clerk is a 2-part process Migrating your user base from Firebase to Clerk is a 2-part process that can be accomplished with just a few steps. - ### Export your Firebase users + ## Export your Firebase users - #### Install the Firebase CLI + ### Install the Firebase CLI If you haven't already, install the Firebase CLI: @@ -16,7 +16,7 @@ Migrating your user base from Firebase to Clerk is a 2-part process that can be npm install -g firebase-tools ``` - #### Log in to Firebase + ### Log in to Firebase Login to your Firebase account via the CLI. @@ -24,7 +24,7 @@ Migrating your user base from Firebase to Clerk is a 2-part process that can be firebase login ``` - #### Find your Firebase project ID + ### Find your Firebase project ID Use the firebase CLI to list your projects and find the project ID you want to export. @@ -32,7 +32,7 @@ Migrating your user base from Firebase to Clerk is a 2-part process that can be firebase projects:list ``` - #### Export your Firebase users using the CLI + ### Export your Firebase users using the CLI Use the firebase CLI to export your users to a JSON file. @@ -52,7 +52,7 @@ Migrating your user base from Firebase to Clerk is a 2-part process that can be You should now have a JSON file called `firebase-users.json` that contains all your Firebase users. - ### Retrieve your password hash parameters + ## Retrieve your password hash parameters In your Firebase project’s dashboard, navigate to **Authentication** and click on the 3 vertical dots at the top of the user's list, then click on **Password hash parameters**. @@ -60,23 +60,23 @@ Migrating your user base from Firebase to Clerk is a 2-part process that can be You can find more information about this page and the values above on [Firebase's documentation](https://firebaseopensource.com/projects/firebase/scrypt/). - ### Create a Node.js script + ## Create a Node.js script Now you have all the information you need to import your Firebase users into Clerk. This example uses Node.js, but you can use any other language or method if you so wish. - #### init npm + ### init npm ```bash {{ filename: 'terminal' }} npm init -y ``` - #### Install dependencies + ### Install dependencies ```bash {{ filename: 'terminal' }} npm i node-fetch@2 ``` - #### Create a script + ### Create a script ```js {{ filename: 'migrate-to-clerk.js' }} const fetch = require('node-fetch') @@ -134,7 +134,7 @@ Migrating your user base from Firebase to Clerk is a 2-part process that can be Here, body will either hold the necessary information to migrate a password-based user or in the case of an OAuth-based user, it'll skip the password check. It will also have the previous user ID as `external_id`, so you can link the newly created users with their existing data. - ### Run the script + ## Run the script ```bash {{ filename: 'terminal' }} node migrate-to-clerk.js diff --git a/docs/guides/authjs-migration.mdx b/docs/guides/authjs-migration.mdx index 0ff9014a9e..7f881daa42 100644 --- a/docs/guides/authjs-migration.mdx +++ b/docs/guides/authjs-migration.mdx @@ -33,12 +33,10 @@ description: Learn how to migrate an application using Auth.js to use Clerk for - Find further support -## Introduction - This guide shows how to migrate an application using Auth.js (formerly NextAuth.js) to use Clerk for authentication. - ### Install `@clerk/nextjs` + ## Install `@clerk/nextjs` Clerk's Next.js SDK gives you access to prebuilt [components](/docs/components/overview), [hooks](/docs/references/nextjs/overview#client-side-helpers), and [helpers](/docs/references/nextjs/overview) for Next.js Server Components, Route Handlers and Middleware. Run the following command to install it: @@ -56,7 +54,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. ``` - ### Set environment variables + ## Set environment variables Add the following code to your `.env.local` file to set your public and Secret Keys. @@ -67,7 +65,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. CLERK_SECRET_KEY={{secret}} ``` - ### Wrap your Next.js app in `` + ## Wrap your Next.js app in `` Remove the `` provider from Auth.js and replace it with ``. @@ -104,26 +102,26 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. ``` - ### Set up sign-up and sign-in UI + ## Set up sign-up and sign-in UI - #### Account Portal + ### Account Portal Account Portal is the fastest way to authenticate your app. Clerk's Account Portal hosts the ``, ``, ``, and other components for your application. Read more about [Account Portal](/docs/customization/account-portal/getting-started). To use the Account Portal, remove the routes that mount the Auth.js sign-in and sign-up UI. Replace the links to those routes with the [``](/docs/components/unstyled/sign-in-button) or [``](/docs/components/unstyled/sign-out-button) components. - #### Self-hosted UI + ### Self-hosted UI If Clerk's Account Portal pages aren't a good fit your app, you can build a custom sign-in and sign-up UI in one of two ways: - use the [prebuilt components](/docs/references/nextjs/custom-signup-signin-pages), such as the [``](/docs/components/authentication/sign-in) and [``](/docs/components/authentication/sign-up) components - build a [fully custom UI using the Clerk API](/docs/custom-flows/overview), leveraging Clerk's React hooks such as [`useSignIn()`](/docs/references/react/use-sign-in) and [`useSignUp()`](/docs/references/react/use-sign-up) - ### Protect your app + ## Protect your app With Clerk, you can control access to your application in a few different ways. One way is to use Clerk's Middleware to protect your entire application, or specific routes. Another way is to use Clerk's components to conditionally render UI based on the user's authentication state. You can hide or show UI based on whether the user is signed in or not. - #### Control access to your app with Clerk Middleware + ### Control access to your app with Clerk Middleware You will need to remove the Auth.js Middleware from your application, and replace it with the Clerk's Middleware helper, `clerkMiddleware()`. @@ -147,7 +145,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. } ``` - #### Control access to your app with Clerk's components + ### Control access to your app with Clerk's components To conditionally render UI when the user is signed in, wrap it with [``](/docs/components/control/signed-in). @@ -170,9 +168,9 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. } ``` - ### Read user and session data + ## Read user and session data - #### Server-side + ### Server-side Replace any Auth.js `getServerSession(req, res, authOptions)` with Clerk's helpers. @@ -205,7 +203,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. - #### Client Side + ### Client Side Replace Auth.js's `useSession()` hook with Clerk's hooks. @@ -224,14 +222,14 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. } ``` - ### User IDs as Foreign Keys + ## User IDs as Foreign Keys When you migrate to Clerk, you will likely need to resolve the foreign key that you used in your database. If you used the `userId` from NextAuth.js, you could resolve this issue with one of the following two options: - [Use Clerk's `externalId` field](#use-clerks-external-id-field) - [Update your Auth.js database](#update-your-database) - #### Use Clerk's `externalId` field + ### Use Clerk's `externalId` field When you migrate user data from Auth.js to Clerk, Clerk generates new user IDs for each user. If you are using existing user IDs as foreign keys in your database (e.g. in a `user_id` column), you can save those IDs as the user's `externalId` in Clerk. This `externalId` can be included in the session token by adding the following [customization](/docs/backend-requests/making/custom-session-token). The following example will set the user's ID to be `externalId` if one is present, otherwise, it will use the Clerk's user ID. @@ -287,19 +285,19 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. > [!NOTE] > You can not access the above from the client-side. If you are using one of Clerk's hooks, then you will need to check if `externalID` exists. If it doesn't, then read the `userId`. - #### Update your database + ### Update your database Alternatively, after the data migration, you can update all the user IDs stored in your database as a foreign key to the new Clerk user IDs. You can read more about user IDs and user data migration in the [Migration Script README](https://github.com/clerk/migration-script?tab=readme-ov-file#handling-the-foreign-key-constraint). - ### Create a Clerk production instance + ## Create a Clerk production instance Every Clerk application has a `Development` and a `Production` instance. Before you start migrating user data, you need to configure your Clerk `Production` instance and migrate your Auth.js users directly into that instance. The [Deploying to Production](/docs/deployments/overview#deploying-to-production) page covers creating a `Production` instance. You can migrate a small set of users on the `Development` instance for testing/staging. To enable importing users to your `Development` instance, add `IMPORT_TO_DEV_INSTANCE=true` to the `.env` for the migration script. - ### Migrate user data from Auth.js to Clerk + ## Migrate user data from Auth.js to Clerk This walkthrough will help you move user data from your existing database to Clerk. @@ -340,7 +338,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. 1. Check for an error log for any users that were not migrated successfully. - ### Finding further support for migrating from Auth.js to Clerk + ## Finding further support for migrating from Auth.js to Clerk This guide covers the most common steps that you would take for the migration. If you have more complex integrations with Auth.js that are not covered here, don't hesitate to reach out in the [Clerk Discord](/discord){{ target: '_blank' }} by creating a post in the [Support channel](https://discord.gg/bmPVkeqKzZ). diff --git a/docs/guides/basic-rbac.mdx b/docs/guides/basic-rbac.mdx index c162efd9d8..10504d94c5 100644 --- a/docs/guides/basic-rbac.mdx +++ b/docs/guides/basic-rbac.mdx @@ -8,7 +8,7 @@ To control which users can access certain parts of your app, you can use the [ro This guide assumes that you're using Next.js App Router, but the concepts can be adapted to Next.js Pages Router and Remix. - ### Configure the session token + ## Configure the session token Clerk provides [user metadata](/docs/users/metadata#user-metadata), which can be used to store information, and in this case, it can be used to store a user's role. Since `publicMetadata` can only be read but not modified in the browser, it is the safest and most appropriate choice for storing information. @@ -26,7 +26,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be - ### Create a global TypeScript definition + ## Create a global TypeScript definition 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. @@ -46,7 +46,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - ### Set the admin role for your user + ## Set the admin role for your user 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. @@ -61,7 +61,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - ### Create a reusable function to check roles + ## Create a reusable function to check roles Create a helper function to simplify checking roles. @@ -81,7 +81,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be > [!NOTE] > You can customize the behavior of the `checkRole()` helper function to suit your needs. For example, you could modify it to return the roles a user has or create a `protectByRole()` function that handles role-based redirects. - ### Create the admin dashboard + ## Create the admin dashboard Now, it's time to create an admin dashboard. The first step is to create the `/admin` route. @@ -94,7 +94,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - ### Protect the admin dashboard + ## Protect the admin dashboard To protect the `/admin` route, choose **one** of the two following methods: @@ -104,7 +104,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be > [!IMPORTANT] > You only need to follow **one** of the following methods to secure your `/admin` route. - #### Option 1: Protect the `/admin` route using middleware + ### Option 1: Protect the `/admin` route using middleware 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. @@ -132,7 +132,7 @@ 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 + ### Option 2: Protect the `/admin` route at the page-level 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. @@ -151,7 +151,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - ### Create server actions for managing a user's role + ## Create server actions for managing 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. @@ -193,7 +193,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - ### Create a component for searching for users + ## Create a component for searching for users 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. @@ -226,7 +226,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - ### Refactor the admin dashboard + ## Refactor the admin dashboard With the server action and the search form set up, it's time to refactor the `app/admin/page.tsx`. @@ -298,7 +298,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be } ``` - ### Finished 🎉 + ## Finished 🎉 The foundation of a custom RBAC (Role-Based Access Control) system is now set up. Roles are attached directly to the user's session, allowing your application to access them without the need for additional network requests. The `checkRole()` helper function simplifies role checks and reduces code complexity. The final component is the admin dashboard, which enables admins to efficiently search for users and manage roles. diff --git a/docs/guides/force-organizations.mdx b/docs/guides/force-organizations.mdx index ecfef6948c..b3ca2eac15 100644 --- a/docs/guides/force-organizations.mdx +++ b/docs/guides/force-organizations.mdx @@ -23,14 +23,12 @@ description: Learn how to hide Personal Accounts and force organizations in your - Limit access to users with active organizations only -## Introduction - In this guide, you will learn how to hide a user's Personal Account in order to appear as if they only have access to organizations. You will also learn how to limit access to your application to only users with active organizations, further enforcing organization-centric access. This is useful for applications that are built for organizations only, such as B2B applications. This guide will be written for Next.js applications using App Router, but the same concepts can be applied to any application using Clerk. - ### Hide Personal Accounts from UI components + ## Hide Personal Accounts from UI components To begin forcing organizations in your application, you need to remove a user's Personal Account from the UI. A user's Personal Account cannot be disabled; it can only be hidden. @@ -68,11 +66,11 @@ This guide will be written for Next.js applications using App Router, but the sa - ### Detect and set an active organization + ## Detect and set an active organization With Clerk, a user can have many organization memberships, but only one of them can be active at a time. - #### Detect an active organization + ### Detect an active organization A session will always include an `orgId` via the [`Auth` object](/docs/references/nextjs/auth-object#auth-object-example-with-active-organization). This can be used to detect if a user has an active organization. @@ -109,7 +107,7 @@ This guide will be written for Next.js applications using App Router, but the sa - #### Set an active organization + ### Set an active organization In the case of [prebuilt components](/docs/components/overview), an organization will _automatically_ be set as active each time the user creates an organization, accepts an invitation, or selects a membership from the organization switcher. In the case of custom flows, you will need to implement the logic for setting an organization as active. The [`useOrganizationList()`](/docs/references/react/use-organization-list) hook provides a `setActive` method to help you with this. @@ -153,7 +151,7 @@ This guide will be written for Next.js applications using App Router, but the sa } ``` - #### Set an active organization based on the URL + ### Set an active organization based on the URL > [!WARNING] > This approach still depends on the `setActive` method, which only runs on the client. Due to this limitation, during SSR, it is possible that `orgId` from `auth()` returns an incorrect value that does not match the organization ID in the URL. @@ -213,7 +211,7 @@ This guide will be written for Next.js applications using App Router, but the sa } ``` - ### Limit access to users with active organizations only + ## Limit access to users with active organizations only Now that you have hidden Personal Accounts from the UI and can detect and set an active organization, you can limit access to your application to users with active organizations only. This will ensure that users without active organizations cannot access your application. @@ -229,7 +227,7 @@ This guide will be written for Next.js applications using App Router, but the sa Based on your use case, you can decide to limit users either in the entire app or a specific part of it. For example, a B2B application might need to limit access to only users with an active organization, whereas a B2B2C application might limit only the `/dashboard` path to users with an active organization. - #### Limit access using the `clerkMiddleware()` helper + ### Limit access using the `clerkMiddleware()` helper Clerk's [`clerkMiddleware()`](/docs/references/nextjs/clerk-middleware) helper can be used in both App Router and Pages Router applications to limit access to users with active organizations only. @@ -324,7 +322,7 @@ This guide will be written for Next.js applications using App Router, but the sa } ``` - #### Limit access using an App Router layout + ### Limit access using an App Router layout In Next.js App Router applications, instead of using `clerkMiddleware()`, you also have the option to use a layout to limit access to users with active organizations only. diff --git a/docs/guides/waitlist.mdx b/docs/guides/waitlist.mdx index cff59729a3..f4012afc5a 100644 --- a/docs/guides/waitlist.mdx +++ b/docs/guides/waitlist.mdx @@ -6,7 +6,7 @@ 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` + ## 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. @@ -26,7 +26,7 @@ In [**Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist) ``` - ### Set your Clerk API keys + ## Set your Clerk API keys @@ -51,7 +51,7 @@ In [**Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist) CLERK_SECRET_KEY={{secret}} ``` - ### Enable Waitlist mode + ## Enable Waitlist mode To enable **Waitlist** mode, follow these steps: @@ -64,7 +64,7 @@ In [**Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist) 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 + ## Add the `` component The [``](/docs/components/waitlist) component renders a form that allows users to join for early access to your app. @@ -78,7 +78,7 @@ In [**Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist) } ``` - ### Add `` to your app + ## Add `` to your app @@ -99,14 +99,14 @@ In [**Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist) } ``` - ### Add sign-in functionality + ## 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 + ### 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: @@ -134,7 +134,7 @@ In [**Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist) 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 + ### Add a sign-in page The following example demonstrates how to render the `` component. diff --git a/docs/integrations/databases/convex.mdx b/docs/integrations/databases/convex.mdx index 2c825606aa..bbce2b5bc4 100644 --- a/docs/integrations/databases/convex.mdx +++ b/docs/integrations/databases/convex.mdx @@ -24,14 +24,12 @@ description: Learn how to integrate Clerk into your Convex application. - Access user identity in Convex queries and mutations -## Introduction - Convex is the full-stack TypeScript development platform. With Convex you get to build a backend with a provided realtime database, file storage, text search, scheduling and more. Paired with Clerk's user authentication and management features, you can build a powerful application with minimal effort. 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. @@ -47,7 +45,7 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q 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. - ### Configure Convex with the Clerk issuer domain + ## Configure Convex with the Clerk issuer domain 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. @@ -68,11 +66,11 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q Replace the `domain` string with the **Issuer** URL you copied. - ### Deploy your changes to Convex + ## Deploy your changes to Convex Run `npx convex dev` to automatically sync your configuration to your backend. - ### Install `@clerk/clerk-react` + ## Install `@clerk/clerk-react` Run the following command to install Clerk's React SDK: @@ -90,7 +88,7 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q ``` - ### Set environment variables + ## Set environment variables 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. @@ -110,7 +108,7 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q VITE_CLERK_PUBLISHABLE_KEY={{pub_key}} ``` - ### Configure the Clerk and Convex providers + ## Configure the Clerk and Convex providers Both Clerk and Convex have provider components that are required to provide authentication and client context. @@ -149,7 +147,7 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q ) ``` - ### Access user identity in Convex queries and mutations + ## Access user identity in Convex queries and mutations You can access the user information from the JWT in Convex queries and mutations. Use the `ctx.auth.getUserIdentity()` which returns the parsed information from the JWT, or `null` if the client isn't authenticated. @@ -171,7 +169,7 @@ 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). - ### Finished! + ## 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, 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 40ed46991e..0e01ef4f9f 100644 --- a/docs/integrations/databases/fauna.mdx +++ b/docs/integrations/databases/fauna.mdx @@ -30,7 +30,7 @@ Integrating Fauna with Clerk gives you the benefits of using a Fauna database wh This guide will walk you through the steps to integrate Fauna with Clerk in your Next.js app. - ### Get your Clerk Frontend API URL and JWKS URL + ## 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 in the Clerk Dashboard. @@ -52,7 +52,7 @@ This guide will walk you through the steps to integrate Fauna with Clerk in your NEXT_PUBLIC_CLERK_JWKS_URL={{jwks_url}} ``` - ### Configure Fauna + ## Configure Fauna 1. Navigate to the [Fauna Dashboard](https://dashboard.fauna.com/) and select your database. 1. Select the **Access Providers** tab and select **Create Access Provider**. @@ -76,7 +76,7 @@ This guide will walk you through the steps to integrate Fauna with Clerk in your ``` 1. Select **Save**. - ### Create a JWT template in Clerk + ## Create a JWT template in Clerk Clerk's JWT templates allow you to generate a new valid Fauna authentication token (JWT) for each signed in user. These tokens allow authenticated users to access your data with Fauna's API. @@ -90,7 +90,7 @@ This guide will walk you through the steps to integrate Fauna with Clerk in your - In the **Claims** section, set the `aud` claim to the **Audience URL** you copied from Fauna in Step 2. The URL format should be `https://db.fauna.com/db/`. You can include additional claims if you’d like, but `aud` is the only required one. [Shortcodes](/docs/backend-requests/making/jwt-templates#shortcodes) are available to make adding dynamic user values easy. - Select **Save** from the notification bubble to complete setup. - ### Install the Fauna library + ## Install the Fauna library Add the Fauna library to your project. @@ -108,7 +108,7 @@ This guide will walk you through the steps to integrate Fauna with Clerk in your ``` - ### Authenticate Fauna queries in your Next.js app + ## Authenticate Fauna queries in your Next.js app You can now create Fauna JWTs in Clerk using the JWT template you created in the previous step. Generate the Fauna JWT by calling Clerk's [`useAuth().getToken`](/docs/references/react/use-auth) method, and use it to authenticate with Fauna as an end user, as shown in the following example: diff --git a/docs/integrations/databases/firebase.mdx b/docs/integrations/databases/firebase.mdx index 51c692f0eb..61219e5315 100644 --- a/docs/integrations/databases/firebase.mdx +++ b/docs/integrations/databases/firebase.mdx @@ -32,7 +32,7 @@ Integrating Firebase with Clerk gives you the benefits of using Firebase's featu > 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 + ## Configure the integration The Firebase integration enables you to use Clerk to generate a valid authentication token to send to Firebase Auth. This enables you to leverage Clerk's prebuilt components, auth provider options, and more, while accessing Firebase products like Firestore with a session validated by Firebase Auth. @@ -68,7 +68,7 @@ Integrating Firebase with Clerk gives you the benefits of using Firebase's featu - ### Enable authentication in Firebase + ## Enable authentication in Firebase To use Firebase auth, ensure authentication is enabled in your Firebase dashboard. To do so: @@ -77,7 +77,7 @@ Integrating Firebase with Clerk gives you the benefits of using Firebase's featu 1. Select **Get started**. 1. Enable any sign-in method you want, such as **Email/Password**. - ### Add a Security Rule to your Firestore database (optional) + ## Add a Security Rule to your Firestore database (optional) Adding the [Cloud Firestore](https://firebase.google.com/docs/firestore/quickstart) feature in your Firebase application is optional. @@ -93,7 +93,7 @@ Integrating Firebase with Clerk gives you the benefits of using Firebase's featu } ``` - ### Get your Firebase config object + ## Get your Firebase config object To connect to your Firebase app in your code, you need a config object from your Firebase project. To find it: @@ -115,7 +115,7 @@ Integrating Firebase with Clerk gives you the benefits of using Firebase's featu See [Google's Firebase documentation](https://support.google.com/firebase/answer/7015592) for more information on the config object. - ### Use Firebase with Clerk in your code + ## Use Firebase with Clerk in your code Now that you have configured the integration, and you have retrieved your Firebase config object, it's time to use Firebase with Clerk in your code. diff --git a/docs/integrations/databases/instantdb.mdx b/docs/integrations/databases/instantdb.mdx index 43522defff..b72937377c 100644 --- a/docs/integrations/databases/instantdb.mdx +++ b/docs/integrations/databases/instantdb.mdx @@ -35,7 +35,7 @@ Integrating [InstantDB](https://www.instantdb.com/) with Clerk gives you the ben This guide will walk you through the steps to integrate InstantDB with Clerk in your Next.js app. - ### Configure your Clerk session token + ## Configure your Clerk session token 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. @@ -50,12 +50,12 @@ 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. 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 + ## Configure InstantDB 1. In the InstantDB dashboard, navigate to the [**Auth**](https://www.instantdb.com/dash?t=auth) tab. 1. Select **Setup Clerk**. @@ -63,7 +63,7 @@ This guide will walk you through the steps to integrate InstantDB with Clerk in 1. Confirm the **The session token has the "email" claim.** message. 1. Select **Add Clerk app**. - ### Install the InstantDB library + ## Install the InstantDB library Run the following command to add the InstantDB library to your project. @@ -81,7 +81,7 @@ This guide will walk you through the steps to integrate InstantDB with Clerk in ``` - ### Integrate InstantDB to your Clerk application + ## Integrate InstantDB to your Clerk application To sign in to InstantDB with Clerk, you need to: diff --git a/docs/integrations/databases/neon.mdx b/docs/integrations/databases/neon.mdx index 56abd969e8..d62eba71b1 100644 --- a/docs/integrations/databases/neon.mdx +++ b/docs/integrations/databases/neon.mdx @@ -23,7 +23,7 @@ description: Learn how to integrate Clerk into your Neon application. This tutorial demonstrates how to integrate Neon Postgres with Clerk in a Next.js application, using `drizzle-orm` and `drizzle-kit` to interact with the database. The tutorial guides you through setting up a simple application that enables users to add, view, and delete messages using Server Actions and Middleware with Clerk. - ### Create a new Next.js project + ## Create a new Next.js project 1. Create a new Next.js project using the following command: ```sh {{ filename: 'terminal' }} @@ -37,11 +37,11 @@ This tutorial demonstrates how to integrate Neon Postgres with Clerk in a Next.j npm install -D drizzle-kit ``` - ### Integrate the Next.js Clerk SDK + ## Integrate the Next.js Clerk SDK Follow the [Next.js quickstart](/docs/quickstarts/nextjs) to integrate the Clerk Next.js SDK into your application. - ### Protect your application routes + ## Protect your application routes To ensure that only authenticated users can access your application, modify [`clerkMiddleware`](/docs/references/nextjs/clerk-middleware) to require authentication for every route. @@ -62,7 +62,7 @@ This tutorial demonstrates how to integrate Neon Postgres with Clerk in a Next.j } ``` - ### Set your neon connection string + ## Set your neon connection string Add the Neon connection string to your project's environment variables. You can find the Neon connection string in the [Neon console](https://console.neon.tech/) - see the [Neon docs](https://neon.tech/docs/connect/connect-from-any-app) for more information. @@ -74,7 +74,7 @@ This tutorial demonstrates how to integrate Neon Postgres with Clerk in a Next.j CLERK_SECRET_KEY={{secret}} ``` - ### Set up the application schema and database connection + ## Set up the application schema and database connection 1. Inside the `app/`, create a `db/` directory. @@ -110,7 +110,7 @@ This tutorial demonstrates how to integrate Neon Postgres with Clerk in a Next.j }) ``` - ### Push the schema to the database + ## Push the schema to the database 1. To load the schema into the database, create a `drizzle.config.ts` file at the root of your project and add the following configuration: @@ -139,7 +139,7 @@ This tutorial demonstrates how to integrate Neon Postgres with Clerk in a Next.j npx drizzle-kit push ``` - ### Create Server Actions to handle user interactions + ## Create Server Actions to handle user interactions To handle form submissions for adding and deleting user messages, create two Server Actions in `app/actions.ts`. Use Clerk's [`auth()` helper](/docs/references/nextjs/auth) to obtain the user ID, which will be used to interact with the database. @@ -170,7 +170,7 @@ This tutorial demonstrates how to integrate Neon Postgres with Clerk in a Next.j } ``` - ### Create the UI for the Home Page + ## Create the UI for the Home Page In your `app/page.tsx` file, add the following code to create the UI for the home page. If a message exists, the user can view and delete it; otherwise, they can add a new message. @@ -211,7 +211,7 @@ This tutorial demonstrates how to integrate Neon Postgres with Clerk in a Next.j } ``` - ### Run the application + ## Run the application Run your application and open `http://localhost:3000` in your browser. Sign in with Clerk and interact with the application to add and delete user messages. diff --git a/docs/quickstarts/astro.mdx b/docs/quickstarts/astro.mdx index f1767b7ed2..c46a85d9c8 100644 --- a/docs/quickstarts/astro.mdx +++ b/docs/quickstarts/astro.mdx @@ -31,7 +31,7 @@ description: Add authentication and user management to your Astro app with Clerk - ### Install `@clerk/astro` + ## Install `@clerk/astro` Clerk's [Astro SDK](/docs/references/astro/overview) provides a set of components, hooks, and stores that make it easy to build authentication and user management features in your Astro app. @@ -51,7 +51,7 @@ description: Add authentication and user management to your Astro app with Clerk ``` - ### Set your Clerk API keys + ## 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. @@ -70,7 +70,7 @@ description: Add authentication and user management to your Astro app with Clerk CLERK_SECRET_KEY={{secret}} ``` - ### Update `astro.config.mjs` + ## Update `astro.config.mjs` To configure Clerk in your Astro app, you will need to update your `astro.config.mjs`. @@ -90,7 +90,7 @@ description: Add authentication and user management to your Astro app with Clerk }) ``` - ### Add `clerkMiddleware()` to your app + ## Add `clerkMiddleware()` to your app [`clerkMiddleware()`](/docs/references/astro/clerk-middleware) grants you access to user authentication state throughout your app, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add `clerkMiddleware()` to your app, follow these steps: @@ -105,7 +105,7 @@ description: Add authentication and user management to your Astro app with Clerk ``` 1. By default, `clerkMiddleware()` will not protect any routes. All routes are public and you must opt-in to protection for routes. See the [`clerkMiddleware()` reference](/docs/references/astro/clerk-middleware) to learn how to require authentication for specific routes. - ### Add TypeScript declarations + ## Add TypeScript declarations Update the `env.d.ts` file in your `src/` directory to add type definitions for the `locals` added by the middleware. @@ -118,7 +118,7 @@ description: Add authentication and user management to your Astro app with Clerk /// ``` - ### Add Clerk components to your app + ## Add Clerk components to your app You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/components/overview#what-are-control-components). Create a header using the following components: @@ -170,7 +170,7 @@ description: Add authentication and user management to your Astro app with Clerk ``` - ### Create your first user + ## Create your first user Run your project with the following command: diff --git a/docs/quickstarts/chrome-extension.mdx b/docs/quickstarts/chrome-extension.mdx index f361d050e4..fef197f686 100644 --- a/docs/quickstarts/chrome-extension.mdx +++ b/docs/quickstarts/chrome-extension.mdx @@ -27,13 +27,13 @@ description: Add authentication and user management to your Chrome Extension wit - ### Configure your authentication options + ## 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 + ## 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. @@ -46,7 +46,7 @@ description: Add authentication and user management to your Chrome Extension wit cd clerk-chrome-extension ``` - ### Install `@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. @@ -56,7 +56,7 @@ description: Add authentication and user management to your Chrome Extension wit pnpm add @clerk/chrome-extension ``` - ### Set your Clerk API keys + ## 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. @@ -77,7 +77,7 @@ description: Add authentication and user management to your Chrome Extension wit CLERK_FRONTEND_API={{fapi_url}} ``` - ### Add `` to your app + ## Add `` to your app @@ -107,7 +107,7 @@ description: Add authentication and user management to your Chrome Extension wit export default IndexPopup ``` - ### Create a header with Clerk components + ## 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). @@ -157,7 +157,7 @@ description: Add authentication and user management to your Chrome Extension wit export default IndexPopup ``` - ### Update `` props for Chrome Extension navigation + ## 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. @@ -209,7 +209,7 @@ description: Add authentication and user management to your Chrome Extension wit export default IndexPopup ``` - ### Create a consistent CRX ID for your extension + ## 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: @@ -217,7 +217,7 @@ description: Add authentication and user management to your Chrome Extension wit 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 to store your public key Create an `.env.chrome` file and add your public key to it, as shown in the following example: @@ -225,7 +225,7 @@ description: Add authentication and user management to your Chrome Extension wit CRX_PUBLIC_KEY= ``` - ### Edit your `package.json` to use the new 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`. @@ -246,7 +246,7 @@ description: Add authentication and user management to your Chrome Extension wit } ``` - ### Use `pnpm dev` to start your development server and create a build + ## 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. @@ -256,7 +256,7 @@ description: Add authentication and user management to your Chrome Extension wit pnpm dev ``` - ### Load your Chrome Extension into your Chromium-based browser + ## Load your Chrome Extension into your Chromium-based browser To load your Chrome Extension, follow these steps: @@ -266,7 +266,7 @@ description: Add authentication and user management to your Chrome Extension wit 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 + ## 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. diff --git a/docs/quickstarts/expo.mdx b/docs/quickstarts/expo.mdx index c9d126d8cf..1ef8b7da8e 100644 --- a/docs/quickstarts/expo.mdx +++ b/docs/quickstarts/expo.mdx @@ -33,7 +33,7 @@ description: Add authentication and user management to your Expo app with Clerk. - ### Install `@clerk/clerk-expo` + ## Install `@clerk/clerk-expo` Clerk's [Expo SDK](/docs/references/expo/overview) gives you access to prebuilt components, hooks, and helpers to make user authentication easier. @@ -53,7 +53,7 @@ description: Add authentication and user management to your Expo app with Clerk. ``` - ### Install `@clerk/types` (optional) + ## Install `@clerk/types` (optional) Clerk's `@clerk/types` package provides TypeScript type definitions. @@ -73,7 +73,7 @@ description: Add authentication and user management to your Expo app with Clerk. ``` - ### Set your Clerk API keys + ## 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 in the Clerk Dashboard. @@ -91,7 +91,7 @@ description: Add authentication and user management to your Expo app with Clerk. EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} ``` - ### Add `` to your root layout + ## Add `` to your root layout @@ -122,7 +122,7 @@ description: Add authentication and user management to your Expo app with Clerk. } ``` - ### Configure the token cache + ## Configure the token cache Clerk stores the active user's session token in memory by default. In Expo apps, the recommended way to store sensitive data, such as tokens, is by using `expo-secure-store` which encrypts the data before storing it. @@ -201,11 +201,11 @@ description: Add authentication and user management to your Expo app with Clerk. > [!TIP] > When you sign a user out with [`signOut()`](/docs/references/react/use-auth#use-auth-returns), Clerk will remove the user's session JWT from the token cache. - ### Add sign-up and sign-in pages + ## Add sign-up and sign-in pages Clerk currently only supports [control components](/docs/components/overview#what-are-control-components) for Expo native. UI components are only available for Expo web. Instead, you must build [custom flows](/docs/custom-flows/overview) using Clerk's API. The following sections demonstrate how to build [custom email/password sign-up and sign-in flows](/docs/custom-flows/email-password). If you want to use different authentication methods, such as passwordless or OAuth, see the dedicated custom flow guides. - #### Layout page + ### Layout page First, protect your sign-up and sign-in pages. @@ -228,7 +228,7 @@ description: Add authentication and user management to your Expo app with Clerk. } ``` - #### Sign-up page + ### Sign-up page 1. In the `(auth)` group, create a `sign-up.tsx` file. 1. Paste the following code. The [`useSignUp()`](/docs/references/react/use-sign-up) hook is used to create a sign-up flow. The user can sign up using their email and password and will receive an email verification code to confirm their email. @@ -336,7 +336,7 @@ description: Add authentication and user management to your Expo app with Clerk. } ``` - #### Sign-in page + ### Sign-in page 1. In the `(auth)` group, create a `sign-in.tsx` file. 1. Paste the following code. The [`useSignIn()`](/docs/references/react/use-sign-in) hook is used to create a sign-in flow. The user can sign in using email address and password, or navigate to the sign-up page. @@ -410,7 +410,7 @@ description: Add authentication and user management to your Expo app with Clerk. For more information about building these custom flows, including guided comments in the code examples, see the [Build a custom email/password authentication flow](/docs/custom-flows/email-password) guide. - ### Conditionally render content + ## Conditionally render content You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/components/overview#what-are-control-components). For this quickstart, you'll use: @@ -459,7 +459,7 @@ description: Add authentication and user management to your Expo app with Clerk. } ``` - ### Create your first user + ## Create your first user Run your project with the following command: diff --git a/docs/quickstarts/express.mdx b/docs/quickstarts/express.mdx index dd3f092403..4ce49c5754 100644 --- a/docs/quickstarts/express.mdx +++ b/docs/quickstarts/express.mdx @@ -33,7 +33,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat Learn how to integrate Clerk into your Express backend for secure user authentication and management. This guide covers backend implementation only and requires a Clerk frontend SDK in order for any of this to work. - ### Install `@clerk/express` + ## Install `@clerk/express` Clerk's [Express SDK](/docs/references/express/overview) ships with a variety of helpers for the backend to make user authentication easier. @@ -53,7 +53,7 @@ Learn how to integrate Clerk into your Express backend for secure user authentic ``` - ### Set your Clerk API keys + ## 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 in the Clerk Dashboard. @@ -88,7 +88,7 @@ Learn how to integrate Clerk into your Express backend for secure user authentic ``` - ### Add `clerkMiddleware()` to your application + ## Add `clerkMiddleware()` to your application The [`clerkMiddleware()`](/docs/references/express/overview#clerk-middleware) function checks the request's cookies and headers for a session JWT and, if found, attaches the [`Auth`](/docs/references/nextjs/auth-object#auth-object){{ target: '_blank' }} object to the `request` object under the `auth` key. @@ -106,7 +106,7 @@ Learn how to integrate Clerk into your Express backend for secure user authentic }) ``` - ### Protect your routes using `requireAuth()` + ## Protect your routes using `requireAuth()` To protect your routes, use the [`requireAuth()`](/docs/references/express/overview#require-auth) middleware. This middleware functions similarly to `clerkMiddleware()`, but also protects your routes by redirecting unauthenticated users to the sign-in page. diff --git a/docs/quickstarts/fastify.mdx b/docs/quickstarts/fastify.mdx index 1d760b5f72..9e146a2029 100644 --- a/docs/quickstarts/fastify.mdx +++ b/docs/quickstarts/fastify.mdx @@ -39,7 +39,7 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic > This guide uses ECMAScript Modules (ESM). To use ESM in your project, you must include `"type": "module"` in your `package.json`. - ### Install `@clerk/fastify` + ## Install `@clerk/fastify` [Clerk's Fastify SDK](https://github.com/clerk/javascript/tree/main/packages/fastify) provides a range of backend utilities to simplify user authentication and management in your application. @@ -59,7 +59,7 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic ``` - ### Set your Clerk API keys + ## 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. @@ -78,7 +78,7 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic CLERK_SECRET_KEY={{secret}} ``` - ### Configure `clerkPlugin` for all routes + ## Configure `clerkPlugin` for all routes The `clerkPlugin` is a Fastify plugin provided by Clerk to integrate authentication into your Fastify application. To ensure that Clerk's authentication and user management features are applied across your Fastify application, configure the `clerkPlugin` to handle all routes or limit it to specific ones. @@ -108,7 +108,7 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic start() ``` - ### Use `getAuth()` to access the auth state and protect routes + ## Use `getAuth()` to access the auth state and protect routes The following example uses [`getAuth()`](/docs/references/nextjs/get-auth){{ target: '_blank' }} to retrieve the `userId`, which is used to protect the route and is passed to [`clerkClient.users.getUser()`](/docs/references/backend/user/get-user){{ target: '_blank' }} to retrieve the current user's `User` object. @@ -150,7 +150,7 @@ Learn how to integrate Clerk into your Fastify backend for secure user authentic ``` -### Configure `clerkPlugin` for specific routes +## Configure `clerkPlugin` for specific routes If you want to use Clerk for specific pages only, you can register the plugin for specific routes. In the following example, the routes are split into protected and public routes. diff --git a/docs/quickstarts/ios.mdx b/docs/quickstarts/ios.mdx index 0cb4ffdf5a..fd19fc1cd5 100644 --- a/docs/quickstarts/ios.mdx +++ b/docs/quickstarts/ios.mdx @@ -23,17 +23,17 @@ description: Add authentication and user management to your iOS app with Clerk. - ### Create an iOS Project + ## Create an iOS Project To get started using Clerk with iOS, create a new project in Xcode. Select SwiftUI as your interface and Swift as your language. See the [Xcode documentation](https://developer.apple.com/documentation/xcode/creating-an-xcode-project-for-an-app) for more information. - ### Install the Clerk iOS SDK + ## Install the Clerk iOS SDK Follow [the Swift Package Manager instructions](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app) to install Clerk as a dependency. When prompted for the package URL, enter [https://github.com/clerk/clerk-ios](https://github.com/clerk/clerk-ios). Be sure to add the package to your target. - ### Load Clerk + ## Load Clerk To use Clerk in your app, you must first configure and load `Clerk`. @@ -69,7 +69,7 @@ description: Add authentication and user management to your iOS app with Clerk. } ``` - ### Conditionally render content + ## Conditionally render content To render content based on whether a user is authenticated or not: @@ -97,9 +97,9 @@ description: Add authentication and user management to your iOS app with Clerk. } ``` - ### Create views for sign-up and sign-in + ## Create views for sign-up and sign-in - #### `SignUpView` + ### `SignUpView` The following example creates a `SignUpView` that allows users to sign up using their email address and password, and sends an email verification code to confirm their email address. @@ -165,7 +165,7 @@ description: Add authentication and user management to your iOS app with Clerk. } ``` - #### `SignInView` + ### `SignInView` The following example creates a `SignInView` that allows users to sign in using their email address and password. @@ -205,7 +205,7 @@ description: Add authentication and user management to your iOS app with Clerk. } ``` - #### `SignUpOrSignInView` + ### `SignUpOrSignInView` Finally, create a `SignUpOrSignInView` container view that allows users to switch between sign up and sign in. @@ -238,7 +238,7 @@ description: Add authentication and user management to your iOS app with Clerk. } ``` - ### Allow users to sign up or sign in + ## Allow users to sign up or sign in Go back to your `ContentView` and render your newly created `SignUpOrSignInView` when the user isn't signed in. @@ -261,7 +261,7 @@ description: Add authentication and user management to your iOS app with Clerk. } ``` - ### Allow users to sign out + ## Allow users to sign out Finally, provide users with a way to sign out of your app: diff --git a/docs/quickstarts/javascript.mdx b/docs/quickstarts/javascript.mdx index 9feb90d979..4d917d89bc 100644 --- a/docs/quickstarts/javascript.mdx +++ b/docs/quickstarts/javascript.mdx @@ -36,7 +36,7 @@ Use the following tabs to choose your preferred method. - ### Set up a JavaScript app using Vite + ## Set up a JavaScript app using Vite To install Clerk's JavaScript SDK, you need to use a bundler like [Vite](https://vitejs.dev/) or [Webpack](https://webpack.js.org/). @@ -65,7 +65,7 @@ Use the following tabs to choose your preferred method. ``` - ### Install `@clerk/clerk-js` + ## Install `@clerk/clerk-js` Run the following command to add the JavaScript SDK to your project: @@ -83,7 +83,7 @@ Use the following tabs to choose your preferred method. ``` - ### Set your Clerk API keys + ## 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). @@ -109,7 +109,7 @@ Use the following tabs to choose your preferred method. const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY ``` - ### Initialize Clerk + ## 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: @@ -127,7 +127,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, see the [reference documentation](/docs/references/javascript/clerk/clerk#load). - ### Add Clerk components to your app + ## Add Clerk components to your app Clerk's [prebuilt components](/docs/components/overview) are the easiest way to add authentication and user management to your app. They come styled out-of-the-box and are customizable to fit your app's design. @@ -183,7 +183,7 @@ Use the following tabs to choose your preferred method. ``` - ### Create your first user + ## Create your first user Run your project with the following command: @@ -209,7 +209,7 @@ Use the following tabs to choose your preferred method. - ### Add the SDK using a ` ``` - ### Listen for the `load` event + ## Listen for the `load` event Below the ` tag that initializes the SDK, create another ` ``` - ### Allow users to sign in or out + ## Allow users to sign in or out Clerk's [prebuilt components](/docs/components/overview) are the easiest way to add authentication and user management to your app. They come styled out-of-the-box and are customizable to fit your app's design. @@ -295,7 +295,7 @@ Use the following tabs to choose your preferred method. -### More resources +## More resources - [Clerk class reference](/docs/references/javascript/clerk/clerk) diff --git a/docs/quickstarts/nextjs.mdx b/docs/quickstarts/nextjs.mdx index 7c6a8bcda1..1c6e51bce7 100644 --- a/docs/quickstarts/nextjs.mdx +++ b/docs/quickstarts/nextjs.mdx @@ -25,7 +25,7 @@ description: Add authentication and user management to your Next.js app with Cle - ### Install `@clerk/nextjs` + ## 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. @@ -45,7 +45,7 @@ description: Add authentication and user management to your Next.js app with Cle ``` - ### Set your Clerk API keys + ## Set your Clerk API keys @@ -70,7 +70,7 @@ description: Add authentication and user management to your Next.js app with Cle CLERK_SECRET_KEY={{secret}} ``` - ### Add `clerkMiddleware()` to your app + ## 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: @@ -95,7 +95,7 @@ description: Add authentication and user management to your Next.js app with Cle ``` 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 `` and Clerk components to your app + ## Add `` and Clerk components to your app @@ -157,7 +157,7 @@ description: Add authentication and user management to your Next.js app with Cle ``` - ### Create your first user + ## Create your first user Run your project with the following command: diff --git a/docs/quickstarts/react-router.mdx b/docs/quickstarts/react-router.mdx index cdaab7e726..4f171e5652 100644 --- a/docs/quickstarts/react-router.mdx +++ b/docs/quickstarts/react-router.mdx @@ -34,7 +34,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat Clerk's [React Router SDK](/docs/references/react-router/overview) provides prebuilt components, hooks, and stores to make it easy to integrate authentication and user management in your React Router app. This guide assumes that you're using [React Router v7 or later](https://api.reactrouter.com/v7). - ### Install `@clerk/react-router` + ## Install `@clerk/react-router` Run the following command to install the SDK: @@ -52,7 +52,7 @@ Clerk's [React Router SDK](/docs/references/react-router/overview) provides preb ``` - ### Set your Clerk API keys + ## 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 in the Clerk Dashboard. @@ -71,7 +71,7 @@ Clerk's [React Router SDK](/docs/references/react-router/overview) provides preb CLERK_SECRET_KEY={{secret}} ``` - ### Configure `rootAuthLoader()` + ## Configure `rootAuthLoader()` The `rootAuthLoader()` function provides access to authentication state in any React Router route. @@ -153,7 +153,7 @@ Clerk's [React Router SDK](/docs/references/react-router/overview) provides preb } ``` - ### Add `` and Clerk components to your app + ## Add `` and Clerk components to your app @@ -198,7 +198,7 @@ Clerk's [React Router SDK](/docs/references/react-router/overview) provides preb // Rest of the root.tsx code ``` - ### Create your first user + ## Create your first user Run your project with the following command: diff --git a/docs/quickstarts/react.mdx b/docs/quickstarts/react.mdx index a7384e1c8d..c904071c13 100644 --- a/docs/quickstarts/react.mdx +++ b/docs/quickstarts/react.mdx @@ -28,7 +28,7 @@ description: Add authentication and user management to your React app with Clerk - ### Create a React app using Vite + ## Create a React app using Vite Run the following commands to create a new React app using [Vite](https://vitejs.dev/guide/#scaffolding-your-first-vite-project): @@ -55,7 +55,7 @@ description: Add authentication and user management to your React app with Clerk ``` - ### Install `@clerk/clerk-react` + ## Install `@clerk/clerk-react` Clerk's [React SDK](/docs/references/react/overview) gives you access to prebuilt components, hooks, and helpers to make user authentication easier. @@ -75,7 +75,7 @@ description: Add authentication and user management to your React app with Clerk ``` - ### Set your Clerk API keys + ## Set your Clerk API keys 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. @@ -93,7 +93,7 @@ description: Add authentication and user management to your React app with Clerk VITE_CLERK_PUBLISHABLE_KEY={{pub_key}} ``` - ### Import the Clerk Publishable Key + ## Import the Clerk Publishable Key In your `main.tsx` file, import your Clerk Publishable Key. You can add an `if` statement to check that it is imported and that it exists. This will prevent running the app without the Publishable Key, and will also prevent TypeScript errors. @@ -117,7 +117,7 @@ description: Add authentication and user management to your React app with Clerk ) ``` - ### Add `` to your app + ## Add `` to your app @@ -146,7 +146,7 @@ description: Add authentication and user management to your React app with Clerk ) ``` - ### Create a header with Clerk components + ## Create a header with Clerk components You can control which content signed-in and signed-out users can see with the [prebuilt control components](/docs/components/overview#what-are-control-components). The following example creates a header using the following components: @@ -172,7 +172,7 @@ description: Add authentication and user management to your React app with Clerk } ``` - ### Create your first user + ## Create your first user Run your project with the following command: diff --git a/docs/quickstarts/remix.mdx b/docs/quickstarts/remix.mdx index 419f7fa983..7b7909a905 100644 --- a/docs/quickstarts/remix.mdx +++ b/docs/quickstarts/remix.mdx @@ -38,7 +38,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user > If you are using Remix SPA mode, follow the [Remix SPA mode guide](/docs/references/remix/spa-mode). - ### Install `@clerk/remix` + ## Install `@clerk/remix` Clerk's Remix SDK gives you access to prebuilt components, hooks, and helpers to make user authentication easier. @@ -58,7 +58,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user ``` - ### Set your Clerk API keys + ## 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. @@ -77,7 +77,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user CLERK_SECRET_KEY={{secret}} ``` - ### Configure `rootAuthLoader` + ## Configure `rootAuthLoader` To configure Clerk in your Remix app, you will need to update your root loader. This will enable you to have access to authentication state in any Remix routes. @@ -138,7 +138,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user // Your additional app code ``` - ### Configure `ClerkApp` + ## Configure `ClerkApp` Clerk provides a `ClerkApp` wrapper to provide the authentication state to your React tree. This helper works with Remix SSR out-of-the-box and follows the "higher-order component" paradigm. @@ -186,9 +186,9 @@ Learn how to use Clerk to quickly and easily add secure authentication and user export default ClerkApp(App) ``` - ### Protect your pages + ## Protect your pages - #### Client-side + ### Client-side To protect your pages on the client-side, Clerk's [prebuilt control components](/docs/components/overview) control the visibility of content based on the user's authentication state. @@ -228,7 +228,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user } ``` - #### Server-side + ### Server-side To protect your routes, use the [`getAuth()`](/docs/references/nextjs/get-auth) function in your loader. This function retrieves the authentication state from the request object, returning an `Auth` object that includes the `userId`, allowing you to determine if the user is authenticated. @@ -256,7 +256,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user } ``` - ### Create your first user + ## Create your first user Run your project with the following command: diff --git a/docs/quickstarts/setup-clerk.mdx b/docs/quickstarts/setup-clerk.mdx index c3c056b1bd..6e22ce4582 100644 --- a/docs/quickstarts/setup-clerk.mdx +++ b/docs/quickstarts/setup-clerk.mdx @@ -9,23 +9,23 @@ Before you can start integrating Clerk into your application, you need to create > If you're migrating from another platform, see the [migration guides](/docs/deployments/migrate-overview) to learn how to move your data to Clerk. - ### Sign into Clerk + ## Sign into Clerk [Create a Clerk account](https://dashboard.clerk.com/sign-up) or [sign into the Clerk Dashboard](https://dashboard.clerk.com/). - ### Create a Clerk application + ## Create a Clerk application If you've just created an account for the first time, you'll be taken directly to the interactive authentication setup form. Otherwise, you'll be redirected to the [Clerk Dashboard](https://dashboard.clerk.com/). To create a new app, select the **Create application** card. You'll be redirected to the interactive authentication setup form. - ### Select identifiers and social providers + ## Select identifiers and social providers Once you are in the interactive authentication setup form, you will be asked to build your authentication flow. Here, Clerk provides various options for setting up your sign-up and sign-in flows. You can choose to use email, phone, or username as [identifiers](/docs/authentication/configuration/sign-up-sign-in-options#identifiers), and you can enable [social authentication providers](/docs/authentication/social-connections/overview). Once the application is created, you can also customize your authentication flow by selecting different authentication strategies, verification methods, and more. [Learn more about sign-up and sign-in options](/docs/authentication/configuration/sign-up-sign-in-options). - ### Integrate Clerk into your application + ## Integrate Clerk into your application Now that your application is created in the Clerk Dashboard, you can integrate it into your codebase. To integrate Clerk into your application, use one of our [quickstarts](/docs/quickstarts/overview): diff --git a/docs/quickstarts/tanstack-start.mdx b/docs/quickstarts/tanstack-start.mdx index 909bb5bc3e..0490284dca 100644 --- a/docs/quickstarts/tanstack-start.mdx +++ b/docs/quickstarts/tanstack-start.mdx @@ -31,7 +31,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat - ### Install `@clerk/tanstack-start` + ## Install `@clerk/tanstack-start` Clerk's [TanStack Start SDK](/docs/references/tanstack-start/overview) gives you access to prebuilt components, React hooks, and helpers to make user authentication easier. @@ -51,7 +51,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat ``` - ### Set your Clerk API keys + ## 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 in the Clerk Dashboard. @@ -70,7 +70,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat CLERK_SECRET_KEY={{secret}} ``` - ### Add `createClerkHandler()` + ## Add `createClerkHandler()` TanStack's [`createStartHandler()`](https://tanstack.com/router/latest/docs/framework/react/start/getting-started#the-server-entry-point) creates a server-side handler that determines which routes and loaders need to be executed when the user hits a given route. @@ -92,7 +92,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat )(defaultStreamHandler) ``` - ### Add `` to your app + ## Add `` to your app @@ -132,9 +132,9 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat } ``` - ### Protect your pages + ## Protect your pages - #### Client-side + ### Client-side To protect your pages on the client-side, you can use Clerk's [prebuilt control components](/docs/components/overview#what-are-control-components) that control the visibility of content based on the user's authentication state. @@ -177,7 +177,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat } ``` - #### Server-side + ### Server-side To protect your routes, create a [server function](https://tanstack.com/router/latest/docs/framework/react/start/server-functions) that checks the user's authentication state via the [`getAuth()`](/docs/references/tanstack-start/get-auth) method. If the user is not authenticated, they are redirected to a sign-in page. If authenticated, the user's `userId` is passed to the route, allowing access to the `` component, which welcomes the user and displays their `userId`. The [`beforeLoad()`](https://tanstack.com/router/latest/docs/framework/react/api/router/RouteOptionsType#beforeload-method) method ensures authentication is checked before loading the page, and the [`loader()`](https://tanstack.com/router/latest/docs/framework/react/api/router/RouteOptionsType#loader-method) method returns the user data for use in the component. @@ -219,7 +219,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat } ``` - ### Create your first user + ## Create your first user Run your project with the following command: diff --git a/docs/references/astro/react.mdx b/docs/references/astro/react.mdx index 38eeb6e23e..eb54d976b5 100644 --- a/docs/references/astro/react.mdx +++ b/docs/references/astro/react.mdx @@ -8,7 +8,7 @@ Astro provides an [integration](https://docs.astro.build/en/guides/integrations- If you have not set up your Astro application to work with Clerk, see the [quickstart guide](/docs/quickstarts/astro). - ### Install `@astrojs/react` + ## Install `@astrojs/react` Add the [Astro React integration](https://docs.astro.build/en/guides/integrations-guide/react/) to your project: @@ -26,7 +26,7 @@ If you have not set up your Astro application to work with Clerk, see the [quick ``` - ### Update `astro.config.mjs` + ## Update `astro.config.mjs` Add Clerk and React integrations to your Astro configuration: @@ -43,11 +43,11 @@ If you have not set up your Astro application to work with Clerk, see the [quick }) ``` - ### Use Clerk components + ## Use Clerk components You can use the [prebuilt components](/docs/components/overview) in your Astro pages or regular React components. - #### Astro pages + ### Astro pages The following example demonstrates how to use Clerk components in Astro pages. @@ -81,7 +81,7 @@ If you have not set up your Astro application to work with Clerk, see the [quick ``` - #### React components + ### React components The following example demonstrates how to use Clerk components in React components. @@ -103,7 +103,7 @@ If you have not set up your Astro application to work with Clerk, see the [quick } ``` - ### Use stores in your React components + ## Use stores in your React components Clerk Astro provides a set of useful [stores](/docs/references/astro/overview#client-side-helpers) that give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk){{ target: '_blank' }} object, and helper methods for signing in and signing up. diff --git a/docs/references/chrome-extension/add-react-router.mdx b/docs/references/chrome-extension/add-react-router.mdx index f50eec3a12..f678523a09 100644 --- a/docs/references/chrome-extension/add-react-router.mdx +++ b/docs/references/chrome-extension/add-react-router.mdx @@ -32,7 +32,7 @@ description: Learn how to add React Router to your React app using their Data AP This tutorial demonstrates how to integrate React Router into your Chrome Extension application using the [Data API router](https://reactrouter.com/en/main/routers/picking-a-router#using-v64-data-apis). - ### Install `react-router-dom` + ## Install `react-router-dom` React Router is a lightweight, fully-featured routing library. To install it in your project, run the following command: @@ -43,7 +43,7 @@ This tutorial demonstrates how to integrate React Router into your Chrome Extens > [!IMPORTANT] > This guide assumes you're using Plasmo to build your Chrome Extension, so you must use `pnpm` as your package manager. - ### Create routes + ## Create routes 1. In the `src/` directory, create a `popup/` directory. 1. In the `popup/` directory, create a `routes/` directory. @@ -101,7 +101,7 @@ This tutorial demonstrates how to integrate React Router into your Chrome Extens ``` - ### Create layouts + ## Create layouts 1. Delete your `src/popup.tsx` file. 1. In your `src/popup/` directory, create a `layouts/` directory. @@ -153,7 +153,7 @@ This tutorial demonstrates how to integrate React Router into your Chrome Extens ``` - ### Configure layouts and routes with `createMemoryRouter` + ## Configure layouts and routes with `createMemoryRouter` [React Router's `createMemoryRouter`](https://reactrouter.com/en/main/routers/create-memory-router) is a router that uses memory to store the state of the router instead of the browser's history. This is useful for creating a router in a non-browser environment like a Chrome Extension. @@ -192,7 +192,7 @@ This tutorial demonstrates how to integrate React Router into your Chrome Extens } ``` - ### Test the integration + ## Test the integration 1. Run your project with the following command: ```bash {{ filename: 'terminal' }} diff --git a/docs/references/chrome-extension/sync-host.mdx b/docs/references/chrome-extension/sync-host.mdx index f00e995923..547c22ecba 100644 --- a/docs/references/chrome-extension/sync-host.mdx +++ b/docs/references/chrome-extension/sync-host.mdx @@ -12,7 +12,7 @@ Clerk allows you to sync the authentication state from your web app to your Chro > This guide assumes assumes that you have followed the [Chrome Extension Quickstart](/docs/quickstarts/chrome-extension) and then the [Add React Router](/docs/references/chrome-extension/add-react-router) guide. - ### Add `PLASMO_PUBLIC_CLERK_SYNC_HOST` to your environment variables + ## Add `PLASMO_PUBLIC_CLERK_SYNC_HOST` to your environment variables The `PLASMO_PUBLIC_CLERK_SYNC_HOST` environment variable defines the host that the Chrome Extension will sync with. @@ -42,7 +42,7 @@ Clerk allows you to sync the authentication state from your web app to your Chro - ### Add `syncHost` prop to your `` + ## Add `syncHost` prop to your `` Add the `syncHost` prop to your Chrome Extension's `` component. This prop tells the `` which host to sync with. @@ -91,7 +91,7 @@ Clerk allows you to sync the authentication state from your web app to your Chro } ``` - ### Configure `host_permissions` + ## Configure `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. @@ -108,7 +108,7 @@ Clerk allows you to sync the authentication state from your web app to your Chro } ``` - ### Add the Extension's ID to your web app's `allowed_origins` + ## Add the Extension's ID to your web app's `allowed_origins` To allow your Chrome Extension to sync with your web app, you must add the extension's ID to your web app's `allowed_origins`. diff --git a/docs/references/expo/local-credentials.mdx b/docs/references/expo/local-credentials.mdx index ecd1ce0080..7c3b8f43ff 100644 --- a/docs/references/expo/local-credentials.mdx +++ b/docs/references/expo/local-credentials.mdx @@ -12,7 +12,7 @@ This guide shows you how to use the `useLocalCredentials()` hook to enhance your > Be aware that this works only for sign in attempts with the password strategy. - ### Install the necessary peer dependencies + ## Install the necessary peer dependencies These packages are required to be installed in order to use the `useLocalCredentials()` hook. @@ -30,14 +30,14 @@ This guide shows you how to use the `useLocalCredentials()` hook to enhance your ``` - ### Update `app.json` + ## Update `app.json` Update your app.json file as instructed in the Expo documentation: - [`expo-local-authentication`](https://docs.expo.dev/versions/latest/sdk/local-authentication/#configuration-in-appjsonappconfigjs) - [`expo-secure-store`](https://docs.expo.dev/versions/latest/sdk/securestore/#configuration-in-appjsonappconfigjs) - ### Securely store/access the user's credentials during sign in + ## Securely store/access the user's credentials during sign in The following example demonstrates how to use `useLocalCredentials()` in a custom flow for signing users in. @@ -113,7 +113,7 @@ This guide shows you how to use the `useLocalCredentials()` hook to enhance your } ``` - ### Delete credentials while user is logged in + ## Delete credentials while user is logged in The following example demonstrates how to use the `userOwnsCredentials` and `clearCredentials` properties of the `useLocalCredentials()` hook in order to remove the stored credentials if those belong to the signed in user. @@ -139,7 +139,7 @@ This guide shows you how to use the `useLocalCredentials()` hook to enhance your } ``` - ### Update credentials while user is logged in + ## Update credentials while user is logged in The following example demonstrates how to use `userOwnsCredentials` and `setCredentials` properties of the `useLocalCredentials()` hook in order to update the stored credentials if those belong to the signed in user. diff --git a/docs/references/expo/web-support/custom-signup-signin-pages.mdx b/docs/references/expo/web-support/custom-signup-signin-pages.mdx index 5890a38cdf..e0d47a0dd1 100644 --- a/docs/references/expo/web-support/custom-signup-signin-pages.mdx +++ b/docs/references/expo/web-support/custom-signup-signin-pages.mdx @@ -8,7 +8,7 @@ This guide shows you how to use the [``](/docs/components/authenticati This guide uses [Expo Router](https://docs.expo.dev/router/introduction/) and the [platform-specific extensions](https://docs.expo.dev/router/create-pages/#platform-specific-extensions) to build the sign-up and sign-in pages specifically for the **web** platform. - ### Build a sign-up page + ## Build a sign-up page The following example demonstrates how to render the [``](/docs/components/authentication/sign-up) component. @@ -20,7 +20,7 @@ This guide uses [Expo Router](https://docs.expo.dev/router/introduction/) and th } ``` - ### Build a sign-in page + ## Build a sign-in page The following example demonstrates how to render the [``](/docs/components/authentication/sign-in) component. @@ -32,7 +32,7 @@ This guide uses [Expo Router](https://docs.expo.dev/router/introduction/) and th } ``` - ### Visit your new pages + ## Visit your new pages To run your project, use the following command: diff --git a/docs/references/ios/sign-in-with-apple.mdx b/docs/references/ios/sign-in-with-apple.mdx index 6828cfb4cc..ae407fae2e 100644 --- a/docs/references/ios/sign-in-with-apple.mdx +++ b/docs/references/ios/sign-in-with-apple.mdx @@ -9,15 +9,15 @@ description: Learn how to use Clerk to natively Sign in with Apple. This guide will teach you how to add native Sign in with Apple to your Clerk apps on Apple platforms. - ### Configure the Apple social connection + ## Configure the Apple social connection To support native Sign in with Apple, you need to configure the Apple social connection in the Clerk Dashboard. To do so, follow the **native-specific instructions** in the [OAuth with Apple guide](/docs/authentication/social-connections/apple). - ### Add the Sign in with Apple capability to your app + ## Add the Sign in with Apple capability to your app [Add the Sign in with Apple capability to your app](https://developer.apple.com/documentation/xcode/configuring-sign-in-with-apple#Add-the-Sign-in-with-Apple-capability-to-your-app). - ### Obtain an Apple ID Credential + ## Obtain an Apple ID Credential To authenticate with Apple and Clerk, you need to obtain an [Apple ID Credential](https://developer.apple.com/documentation/authenticationservices/asauthorizationappleidcredential). @@ -29,7 +29,7 @@ This guide will teach you how to add native Sign in with Apple to your Clerk app > [!NOTE] > You must set the nonce property of the `ASAuthorizationAppleIDRequest` when requesting an Apple ID Credential in order to authenticate with Clerk. - ### Build your sign-in flow + ## Build your sign-in flow Once you have obtained your [Apple ID Credential](https://developer.apple.com/documentation/authenticationservices/asauthorizationappleidcredential), you can use it to authenticate with Clerk by calling [`SignIn.create(strategy:)`](https://swiftpackageindex.com/clerk/clerk-ios/main/documentation/clerksdk/signin/create\(strategy:\)) with a strategy of `.idToken` followed by `.authenticateWithIdToken()`. diff --git a/docs/references/nextjs/custom-signup-signin-pages.mdx b/docs/references/nextjs/custom-signup-signin-pages.mdx index 14a2899bb8..6b971df480 100644 --- a/docs/references/nextjs/custom-signup-signin-pages.mdx +++ b/docs/references/nextjs/custom-signup-signin-pages.mdx @@ -13,10 +13,8 @@ If the prebuilt components don't meet your specific needs or if you require more > [!NOTE] > 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 + ## Build a sign-up page The following example demonstrates how to render the [``](/docs/components/authentication/sign-up) component. @@ -28,7 +26,7 @@ If the prebuilt components don't meet your specific needs or if you require more } ``` - ### Build a sign-in page + ## Build a sign-in page The following example demonstrates how to render the [``](/docs/components/authentication/sign-in) component. @@ -40,7 +38,7 @@ If the prebuilt components don't meet your specific needs or if you require more } ``` - ### Make the sign-up and sign-in routes public + ## 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. @@ -71,7 +69,7 @@ If the prebuilt components don't meet your specific needs or if you require more } ``` - ### Update your environment variables + ## Update your environment variables 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). @@ -80,7 +78,7 @@ If the prebuilt components don't meet your specific needs or if you require more NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up ``` - ### Visit your new pages + ## Visit your new pages Run your project with the following command: diff --git a/docs/references/nextjs/trpc.mdx b/docs/references/nextjs/trpc.mdx index a8a7056a56..941b53f608 100644 --- a/docs/references/nextjs/trpc.mdx +++ b/docs/references/nextjs/trpc.mdx @@ -27,7 +27,7 @@ description: Learn how to integrate Clerk into your Next.js Pages Router applica - ### Create Clerk authentication context + ## Create Clerk authentication context Clerk's [`Auth`](/docs/references/nextjs/auth-object) object includes important authentication information like the current user's session ID, user ID, and organization ID. It also contains methods to check for the current user's permissions and to retrieve their session token. @@ -45,7 +45,7 @@ description: Learn how to integrate Clerk into your Next.js Pages Router applica export type Context = trpc.inferAsyncReturnType ``` - ### Create tRPC context + ## Create tRPC context Create the tRPC context to use the Clerk context in your tRPC queries. @@ -60,7 +60,7 @@ description: Learn how to integrate Clerk into your Next.js Pages Router applica }) ``` - ### Access the context data in your backend + ## Access the context data in your backend The tRPC context, or `ctx`, should now have access to the Clerk authentication context. Use `ctx` in your queries to access the context data in any procedure. @@ -78,7 +78,7 @@ description: Learn how to integrate Clerk into your Next.js Pages Router applica }) ``` - ### Create a protected procedure + ## Create a protected procedure In many applications, it's essential to restrict access to certain routes based on user authentication status. This ensures that sensitive data and functionality are only accessible to authorized users. tRPC middleware provides a powerful mechanism for implementing this protection within your application. @@ -116,7 +116,7 @@ description: Learn how to integrate Clerk into your Next.js Pages Router applica export const protectedProcedure = t.procedure.use(isAuthed) ``` - ### Use your protected procedure + ## Use your protected procedure Once you have created your procedure, you can use it in any router. diff --git a/docs/references/nextjs/usage-with-older-versions.mdx b/docs/references/nextjs/usage-with-older-versions.mdx index d5235b44c8..bb70cdf8ea 100644 --- a/docs/references/nextjs/usage-with-older-versions.mdx +++ b/docs/references/nextjs/usage-with-older-versions.mdx @@ -9,7 +9,7 @@ Clerk's [prebuilt components](/docs/components/overview) are exported from the ` > Clerk highly recommends updating your Next.js version as older versions won't receive any updates in the future. Read [their upgrade guides](https://nextjs.org/docs/pages/building-your-application/upgrading) to learn more. - ### Install `@clerk/nextjs` v4 + ## Install `@clerk/nextjs` v4 Install `^4.0.0` of `@clerk/nextjs`. Newer major versions of `@clerk/nextjs` only support Next.js 13+. @@ -27,7 +27,7 @@ Clerk's [prebuilt components](/docs/components/overview) are exported from the ` ``` - ### Change your `next.config.js` + ## Change your `next.config.js` As mentioned previously, the `@clerk/nextjs` components contain code for multiple Next.js versions, but depending on your version, only certain components will be used. Update your `next.config.js` to instruct webpack to ignore modules on code paths that won't be used. diff --git a/docs/references/react-router/custom-signup-signin-pages.mdx b/docs/references/react-router/custom-signup-signin-pages.mdx index 1bb6e01d6d..5a445e7093 100644 --- a/docs/references/react-router/custom-signup-signin-pages.mdx +++ b/docs/references/react-router/custom-signup-signin-pages.mdx @@ -8,7 +8,7 @@ This guide shows you how to use the [``](/docs/components/authenticati 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). - ### Build a sign-up page + ## Build a sign-up page The following example demonstrates how to render the [``](/docs/components/authentication/sign-up) component. @@ -25,7 +25,7 @@ If the prebuilt components don't meet your specific needs or if you require more } ``` - ### Build a sign-in page + ## Build a sign-in page The following example demonstrates how to render the [``](/docs/components/authentication/sign-in) component. @@ -42,7 +42,7 @@ If the prebuilt components don't meet your specific needs or if you require more } ``` - ### Configure routes + ## Configure routes React Router expects you to define routes in [`app/routes.ts`](https://reactrouter.com/start/framework/routing). Add the previously created sign-in and sign-up pages to your route configuration. @@ -56,7 +56,7 @@ If the prebuilt components don't meet your specific needs or if you require more ] satisfies RouteConfig ``` - ### Configure redirect behavior + ## Configure redirect behavior Update your environment variables to point to your custom sign-up and sign-in pages. Learn more about the available [environment variables](/docs/deployments/clerk-environment-variables). @@ -69,7 +69,7 @@ If the prebuilt components don't meet your specific needs or if you require more These values control the behavior of the `` and `` components and when you visit the respective links at the bottom of each component. - ### Visit your new pages + ## Visit your new pages Run your project with the following command: diff --git a/docs/references/react-router/library-mode.mdx b/docs/references/react-router/library-mode.mdx index 87e57aef0f..4d04824993 100644 --- a/docs/references/react-router/library-mode.mdx +++ b/docs/references/react-router/library-mode.mdx @@ -30,7 +30,7 @@ description: Learn how to use Clerk with React Router in library mode to add aut React Router can be used as a framework or as a standalone library. This guide explains how to add React Router authentication to an existing React application using library mode. To use React Router as a framework instead, see the [React Router quickstart](/docs/quickstarts/react-router). - ### Install `@clerk/react-router` + ## Install `@clerk/react-router` Clerk's [React Router SDK](/docs/references/react-router/overview) provides prebuilt components, hooks, and stores to make it easy to integrate authentication and user management in your React Router app. @@ -50,7 +50,7 @@ React Router can be used as a framework or as a standalone library. This guide e ``` - ### Set your Clerk API keys + ## Set your Clerk API keys > [!NOTE] > You will not need the Clerk Secret Key in React Router's library mode, as it should never be used on the client-side. @@ -71,7 +71,7 @@ React Router can be used as a framework or as a standalone library. This guide e VITE_CLERK_PUBLISHABLE_KEY={{pub_key}} ``` - ### Add `` to your app + ## Add `` to your app @@ -100,7 +100,7 @@ React Router can be used as a framework or as a standalone library. This guide e ) ``` - ### Create a header with Clerk components + ## Create a header with Clerk components You can control which content signed-in and signed-out users can see with the [prebuilt control components](/docs/components/overview#what-are-control-components). The following example creates a header using the following components: diff --git a/docs/references/redwood/overview.mdx b/docs/references/redwood/overview.mdx index 02fcd94e68..7c2d5837b7 100644 --- a/docs/references/redwood/overview.mdx +++ b/docs/references/redwood/overview.mdx @@ -6,7 +6,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat Learn how to use Clerk to quickly and easily add secure authentication and user management to your RedwoodJS application. - ### Create a RedwoodJS application + ## Create a RedwoodJS application ```bash {{ filename: 'terminal' }} @@ -22,7 +22,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user ``` - ### Set environment variables + ## Set environment variables Below is an example of an `.env.local` file. @@ -33,14 +33,14 @@ Learn how to use Clerk to quickly and easily add secure authentication and user CLERK_SECRET_KEY={{secret}} ``` - #### Update redwood.toml + ### Update redwood.toml ```toml {{ filename: 'redwood.toml' }} [web] includeEnvironmentVariables = ['CLERK_PUBLISHABLE_KEY'] ``` - ### Set up Redwood auth + ## Set up Redwood auth The next step is to run a Redwood CLI command to install the required packages and generate some boilerplate code: @@ -53,7 +53,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user You can now access Clerk functions through the Redwood `useAuth()` hook, which is exported from `src/web/auth.tsx`, or you can use the Clerk components directly. - ### Protecting your pages + ## Protecting your pages Below is an example of using the `useAuth()` hook to verify if the user is authenticated. This will open a modal for your user to sign in to their account. @@ -80,7 +80,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user export default HomePage ``` - ### Using Clerk components directly + ## Using Clerk components directly ```tsx {{ filename: 'index.tsx' }} import { SignInButton, UserButton } from '@clerk/clerk-react' @@ -105,7 +105,7 @@ Learn how to use Clerk to quickly and easily add secure authentication and user ``` -### Next steps +## Next steps Now that you have an application integrated with Clerk, you will want to read the following documentation: diff --git a/docs/references/remix/custom-signup-signin-pages.mdx b/docs/references/remix/custom-signup-signin-pages.mdx index f0a2cb40dd..3157c9702e 100644 --- a/docs/references/remix/custom-signup-signin-pages.mdx +++ b/docs/references/remix/custom-signup-signin-pages.mdx @@ -13,7 +13,7 @@ The functionality of the components are controlled by the instance settings you > Just getting started with Clerk and Remix? See the [quickstart tutorial](/docs/quickstarts/remix)! - ### Build your sign-up page + ## Build your sign-up page The following example demonstrates how to render the [``](/docs/components/authentication/sign-up) component. @@ -30,7 +30,7 @@ The functionality of the components are controlled by the instance settings you } ``` - ### Build your sign-in page + ## Build your sign-in page The following example demonstrates how to render the [``](/docs/components/authentication/sign-in) component. @@ -47,7 +47,7 @@ The functionality of the components are controlled by the instance settings you } ``` - ### Configure your sign-up and sign-in pages + ## Configure your sign-up and sign-in pages @@ -78,7 +78,7 @@ The functionality of the components are controlled by the instance settings you These values control the behavior of the components when you sign in or sign up and when you click on the respective links at the bottom of each component. - ### Visit your new pages + ## Visit your new pages Run your project with the following terminal command from the root directory of your project: diff --git a/docs/references/remix/spa-mode.mdx b/docs/references/remix/spa-mode.mdx index 3c92e3c79b..c0c6de3a04 100644 --- a/docs/references/remix/spa-mode.mdx +++ b/docs/references/remix/spa-mode.mdx @@ -25,7 +25,7 @@ description: Clerk supports Remix SPA mode out-of-the-box. > If you are using Remix with SSR, follow the [Remix quickstart](/docs/quickstarts/remix). - ### Install `@clerk/remix` + ## Install `@clerk/remix` Once you have a Remix application ready, you need to install Clerk's Remix SDK. This gives you access to our prebuilt components and hooks for Remix applications. @@ -43,7 +43,7 @@ description: Clerk supports Remix SPA mode out-of-the-box. ``` - ### Set your environment variables + ## Set your environment 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 in the Clerk Dashboard. @@ -64,7 +64,7 @@ description: Clerk supports Remix SPA mode out-of-the-box. VITE_CLERK_PUBLISHABLE_KEY={{pub_key}} ``` - ### Configure `ClerkApp` + ## Configure `ClerkApp` Clerk provides a `ClerkApp` wrapper to provide the authentication state to your React tree. @@ -98,7 +98,7 @@ description: Clerk supports Remix SPA mode out-of-the-box. }) ``` - ### Update your paths through ClerkApp options + ## Update your paths through ClerkApp options Next, add paths to your `ClerkApp` options to control the behavior of the components when you sign in or sign up and when you click on the respective links at the bottom of each component. @@ -110,7 +110,7 @@ description: Clerk supports Remix SPA mode out-of-the-box. }) ``` - ### Protecting your pages + ## Protecting your pages Clerk offers [Control Components](/docs/components/overview) that allow you to protect your pages. These components are used to control the visibility of your pages based on the user's authentication state. @@ -153,7 +153,7 @@ description: Clerk supports Remix SPA mode out-of-the-box. ``` -### Next steps +## Next steps Now that you have an application integrated with Clerk, you will want to read the following documentation: diff --git a/docs/references/ruby/overview.mdx b/docs/references/ruby/overview.mdx index 71b1475fe9..fb9b3491f7 100644 --- a/docs/references/ruby/overview.mdx +++ b/docs/references/ruby/overview.mdx @@ -4,11 +4,11 @@ description: Learn how to integrate Ruby into your Clerk application. --- - ### Create a Clerk application + ## Create a Clerk application 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 + ## Install Ruby Once a Clerk application has been created, you can install and then start using Clerk Ruby in your application. @@ -30,7 +30,7 @@ description: Learn how to integrate Ruby into your Clerk application. $ gem install clerk-sdk-ruby ``` - ### Instantiate a `Clerk::SDK` instance + ## Instantiate a `Clerk::SDK` instance To access all [Backend API endpoints](/docs/reference/backend-api){{ target: '_blank' }}, you need to instantiate a `Clerk::SDK` instance. @@ -59,7 +59,7 @@ description: Learn how to integrate Ruby into your Clerk application. ) ``` - ### Configuration + ## Configuration The SDK can be configured in three ways: environment variables, configuration singleton and constructor arguments. The priority goes like this: @@ -67,7 +67,7 @@ description: Learn how to integrate Ruby into your Clerk application. - Configuration object - Environment variables - #### Constructor arguments + ### Constructor arguments You can customize each instance of the `Clerk::SDK` object by passing keyword arguments to the constructor: @@ -79,7 +79,7 @@ description: Learn how to integrate Ruby into your Clerk application. ) ``` - #### Configuration object + ### Configuration object If an argument is not provided, the configuration object is looked up, which falls back to the associated environment variable. Here's an example with all supported configuration settings their environment variable equivalents: @@ -94,7 +94,7 @@ description: Learn how to integrate Ruby into your Clerk application. For more information, see [Faraday's documentation](https://lostisland.github.io/faraday/#/). - #### Environment variables + ### Environment variables Here's a list of all environment variables the SDK uses: diff --git a/docs/testing/cypress/overview.mdx b/docs/testing/cypress/overview.mdx index cf29c71c31..60c43969f2 100644 --- a/docs/testing/cypress/overview.mdx +++ b/docs/testing/cypress/overview.mdx @@ -14,7 +14,7 @@ This guide will help you set up your environment for creating Clerk-authenticate > Check out the [demo repo](https://github.com/clerk/clerk-cypress-nextjs) that tests a Clerk-powered application using [Testing Tokens](/docs/testing/overview#testing-tokens). - ### Install `@clerk/testing` + ## Install `@clerk/testing` Clerk's testing package provides integration helpers for popular testing frameworks. Run the following command to install it: @@ -32,7 +32,7 @@ This guide will help you set up your environment for creating Clerk-authenticate ``` - ### Set your API keys + ## Set your API keys In your test runner, set your Publishable and Secret Keys as the `CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` environment variables, respectively. @@ -45,7 +45,7 @@ This guide will help you set up your environment for creating Clerk-authenticate > [!WARNING] > Ensure you provide the Secret Key in a secure manner, to avoid leaking it to third parties. For example, if you are using GitHub Actions, refer to [_Using secrets in GitHub Actions_](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). - ### Global setup + ## Global setup To set up Clerk with Cypress, call the `clerkSetup()` function in your [`cypress.config.ts`](https://docs.cypress.io/guides/references/configuration) file. @@ -65,7 +65,7 @@ This guide will help you set up your environment for creating Clerk-authenticate `clerkSetup()` will retrieve a [Testing Token](/docs/testing/overview#testing-tokens) once the test suite starts, making it available for all subsequent tests. - ### Use Clerk Testing Tokens + ## Use Clerk Testing Tokens Now that Cypress is configured with Clerk, use the `setupClerkTestingToken()` function in your tests to integrate the Testing Token. See the following example: diff --git a/docs/testing/playwright/overview.mdx b/docs/testing/playwright/overview.mdx index db52bdaf37..dfa0dff650 100644 --- a/docs/testing/playwright/overview.mdx +++ b/docs/testing/playwright/overview.mdx @@ -9,7 +9,7 @@ description: Use Playwright to write end-to-end tests with Clerk. > See the [demo repo](https://github.com/clerk/clerk-playwright-nextjs) that demonstrates testing a Clerk-powered application using [Testing Tokens](/docs/testing/overview#testing-tokens). To run the tests, you'll need dev instance Clerk API keys, a test user with username and password, and have username and password authentication enabled in the Clerk Dashboard. - ### Install `@clerk/testing` + ## Install `@clerk/testing` Clerk's testing package provides integration helpers for popular testing frameworks. Run the following command to install it: @@ -27,7 +27,7 @@ description: Use Playwright to write end-to-end tests with Clerk. ``` - ### Set your API keys + ## Set your API keys In your test runner, set your Publishable and Secret Keys as the `CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` environment variables, respectively. @@ -39,7 +39,7 @@ description: Use Playwright to write end-to-end tests with Clerk. > [!WARNING] > Ensure that the Secret Key is provided securely to prevent exposure to third parties. For example, if you are using GitHub Actions, refer to [_Using secrets in GitHub Actions_](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). - ### Configure Playwright with Clerk + ## Configure Playwright with Clerk The `clerkSetup()` function obtains a Testing Token when your test suite starts, making it available for all subsequent tests to use. This ensures that you don't have to manually generate a Testing Token for each test. @@ -60,7 +60,7 @@ description: Use Playwright to write end-to-end tests with Clerk. > [!NOTE] > You can manually set the Testing Token by using the `CLERK_TESTING_TOKEN` environment variable instead of calling `clerkSetup()`. - ### Use `setupClerkTestingToken()` + ## Use `setupClerkTestingToken()` Now that Playwright is configured with Clerk, you can use the `setupClerkTestingToken()` function to include the Testing Token in individual test cases. This function injects the Testing Token for the specific test, ensuring the test can bypass Clerk's bot detection mechanisms. See the following example: diff --git a/docs/testing/playwright/test-authenticated-flows.mdx b/docs/testing/playwright/test-authenticated-flows.mdx index b3d1af2c4b..4c3054ef64 100644 --- a/docs/testing/playwright/test-authenticated-flows.mdx +++ b/docs/testing/playwright/test-authenticated-flows.mdx @@ -11,7 +11,7 @@ This guide demonstrates how to save the auth state globally and load it in your > See the [demo repo](https://github.com/clerk/clerk-playwright-nextjs) that demonstrates testing a Clerk-powered application using [Testing Tokens](/docs/testing/overview#testing-tokens). To run the tests, you'll need dev instance Clerk API keys, a test user with username and password, and have username and password authentication enabled in the Clerk Dashboard. - ### Create a storage directory + ## Create a storage directory Create a `playwright/.clerk` directory and add it to your `.gitignore`. Once the auth state is generated, it will be stored to a file in this directory. Later on, tests will reuse this state and start already authenticated. @@ -20,7 +20,7 @@ This guide demonstrates how to save the auth state globally and load it in your echo $'\nplaywright/.clerk' >> .gitignore ``` - ### Prepare auth state for your tests + ## Prepare auth state for your tests Authenticate and save the auth state in your [global setup file](https://playwright.dev/docs/test-global-setup-teardown). @@ -66,11 +66,11 @@ This guide demonstrates how to save the auth state globally and load it in your }) ``` - ### Load the stored auth state in your tests + ## Load the stored auth state in your tests You can either load the stored auth state [in the config](#-in-the-config) or directly [in a test file](#-in-a-test-file). Loading in the config is useful if you want to authenticate once and reuse the same auth state for all tests or groups of tests. Loading in a test file is useful if you want to authenticate for a specific test case. - #### In the config + ### In the config In your `playwright.config.ts`, create a `global setup` project and declare it as a [dependency](https://playwright.dev/docs/test-projects#dependencies) for all your testing projects. This means that the `global setup` project will always run before all the tests, and because it's where you prepared auth state, it will authenticate before all the tests. All testing projects should use the authenticated state as `storageState`. @@ -103,7 +103,7 @@ This guide demonstrates how to save the auth state globally and load it in your ] ``` - #### In a test file + ### In a test file To use the stored auth state in a test file, see the following example: diff --git a/docs/webhooks/loops.mdx b/docs/webhooks/loops.mdx index eae8cb1dc3..73bffcb29f 100644 --- a/docs/webhooks/loops.mdx +++ b/docs/webhooks/loops.mdx @@ -25,7 +25,7 @@ description: Learn how to add your Clerk users to your Loops audience, and send This tutorial demonstrates how to sync your Clerk users to Loops so you can email users with Loop's email marketing tools. You will also learn how to send email sequences to new Clerk users. - ### Create a Clerk webhook endpoint in Loops + ## Create a Clerk webhook endpoint in Loops Loops' [Incoming webhooks](https://loops.so/docs/integrations/incoming-webhooks) feature lets Loops accept webhooks directly from external platforms like Clerk. @@ -34,7 +34,7 @@ This tutorial demonstrates how to sync your Clerk users to Loops so you can emai 1. Navigate to the **Clerk** settings page in the [Loops dashboard](https://app.loops.so/settings?page=clerk). 1. Save the **Endpoint URL** somewhere secure; you're going to need it for Clerk's webhook configuration. - ### Create a webhook in the Clerk Dashboard + ## Create a webhook in the Clerk Dashboard You must create a new Clerk webhook endpoint so that it can send data to Loops. Here is where you will provide the **Endpoint URL** from the last step, and then choose the events you want to listen to. @@ -45,14 +45,14 @@ This tutorial demonstrates how to sync your Clerk users to Loops so you can emai 1. Select the **Create** button. 1. You will be redirected to your endpoint's settings page. Leave this page open. - ### Add your signing secret in Loops + ## Add your signing secret in Loops To keep communication secure between the two platforms: 1. On the Clerk 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. Back in the Loops dashboard, add the **Signing Secret**. - ### Configure Loops events + ## Configure Loops events The final step is to configure which events Loops should accept from Clerk and what Loops should do with the data. diff --git a/docs/webhooks/sync-data.mdx b/docs/webhooks/sync-data.mdx index 7f6267e2c5..a7024f6bf3 100644 --- a/docs/webhooks/sync-data.mdx +++ b/docs/webhooks/sync-data.mdx @@ -39,7 +39,7 @@ Clerk offers many events, but three key events include: These steps apply to any Clerk event. To make the setup process easier, it's recommended to keep two browser tabs open: one for your Clerk [**Webhooks**](https://dashboard.clerk.com/last-active?path=webhooks) page and one for your [ngrok dashboard](https://dashboard.ngrok.com). - ### Set up ngrok + ## Set up ngrok To test a webhook locally, you need to expose your local server to the internet. This guide uses [ngrok](https://ngrok.com/) which creates a **forwarding URL** that sends the webhook payload to your local server. @@ -51,7 +51,7 @@ These steps apply to any Clerk event. To make the setup process easier, it's rec 1. Paste the command in your terminal and change the port number to match your server's port. For this guide, replace `80` with `3000`, then run the command in your terminal. It will generate a **Forwarding** URL. It should resemble `https://fawn-two-nominally.ngrok-free.app`. 1. Save your **Forwarding** URL somewhere secure. Close the panel. - ### Set up a webhook endpoint + ## Set up a webhook endpoint 1. In the Clerk Dashboard, navigate to the [**Webhooks**](https://dashboard.clerk.com/last-active?path=webhooks) page. 1. Select **Add Endpoint**. @@ -59,7 +59,7 @@ These steps apply to any Clerk event. To make the setup process easier, it's rec 1. In the **Subscribe to events** section, scroll down and select `user.created`. 1. Select **Create**. You'll be redirected to your endpoint's settings page. Keep this page open. - ### Add your Signing Secret to `.env.local` + ## Add your Signing Secret to `.env.local` To verify the webhook payload, you'll need your endpoint's **Signing Secret**. Since you don't want this secret exposed in your codebase, store it as an environment variable in your `.env.local` file during local development. @@ -72,11 +72,11 @@ These steps apply to any Clerk event. To make the setup process easier, it's rec SIGNING_SECRET=whsec_123 ``` - ### Set the webhook route as public in your Middleware + ## Set the webhook route as public in your Middleware Incoming webhook events don't contain auth information. They come from an external source and aren't signed in or out, so the route must be public to allow access. If you're using `clerkMiddleware()`, ensure that the `/api/webhooks(.*)` route is set as public. For information on configuring routes, see the [`clerkMiddleware()` guide](/docs/references/nextjs/clerk-middleware). - ### Install `svix` + ## Install `svix` Clerk uses [`svix`](https://www.npmjs.com/package/svix) to deliver webhooks, so you'll use it to verify the webhook signature. Run the following command in your terminal to install the package: @@ -94,7 +94,7 @@ These steps apply to any Clerk event. To make the setup process easier, it's rec ``` - ### Create the endpoint + ## Create the endpoint Set up a Route Handler that uses `svix` to verify the incoming Clerk webhook and process the payload. @@ -239,7 +239,7 @@ These steps apply to any Clerk event. To make the setup process easier, it's rec - ### Narrow to a webhook event for type inference + ## Narrow to a webhook event for type inference `WebhookEvent` encompasses all possible webhook types. Narrow down the event type for accurate typing for specific events. @@ -265,7 +265,7 @@ These steps apply to any Clerk event. To make the setup process easier, it's rec - `SMSMessageJSON` - `UserJSON` - ### Test the webhook + ## Test the webhook 1. Start your Next.js server. 1. In your endpoint's settings page in the Clerk Dashboard, select the **Testing** tab. @@ -273,14 +273,14 @@ These steps apply to any Clerk event. To make the setup process easier, it's rec 1. Select **Send Example**. 1. In the **Message Attempts** section, confirm that the event is labeled with `Succeeded`. - #### Handling failed messages + ### Handling failed messages 1. In the **Message Attempts** section, select the event labeled with `Failed`. 1. Scroll down to the **Webhook Attempts** section. 1. Toggle the arrow next to the **Status** column. 1. Review the error. Solutions vary by error type. For more information, refer to the [Debug your webhooks](/docs/webhooks/debug-your-webhooks) guide. - ### Trigger the webhook + ## Trigger the webhook To trigger the `user.created` event, you can do either one of the following: @@ -290,7 +290,7 @@ These steps apply to any Clerk event. To make the setup process easier, it's rec 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-the-webhook). -### Configure your production instance +## Configure your production instance 1. When you're ready to deploy your app to production, follow [the guide on deploying your Clerk app to production](/docs/deployments/overview). 1. Create your production webhook by following the steps in the previous [Set up a webhook endpoint](#set-up-a-webhook-endpoint) section. In the **Endpoint URL** field, instead of pasting the ngrok URL, paste your production app URL. diff --git a/styleguides/SSO.STYLEGUIDE.MD b/styleguides/SSO.STYLEGUIDE.MD index d5dd940c85..24bd4998dd 100644 --- a/styleguides/SSO.STYLEGUIDE.MD +++ b/styleguides/SSO.STYLEGUIDE.MD @@ -38,7 +38,7 @@ These are the guidelines we use to write our SSO guides. - The `Test your OAuth` section should be included in the `` and formatted as follows: ```mdx - ### Test your OAuth + ## 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.