Merge branch 'main' into elef/keyless

docs/authentication/social-connections/atlassian.mdx

@@ -1,89 +1,82 @@
 ---
 title: Add Atlassian as a social connection
-description: Learn how to set up social connection with Atlassian.
+description: Learn how to allow users to sign up and sign in to your Clerk app with their Atlassian account using OAuth.
 ---
 
-How to set up social connection with Atlassian
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "A Clerk app is required.",
+      link: "/docs/quickstarts/setup-clerk",
+      icon: "clerk",
+    },
+    {
+      title: "An Atlassian account is required.",
+      link: "https://developer.atlassian.com/",
+      icon: "user-circle",
+    }
+  ]}
+>
+  - Use Atlassian to authenticate users with OAuth
+</TutorialHero>
 
-## Overview
+Enabling OAuth with Atlassian allows your users to sign up and sign in to your Clerk app with their Atlassian account.
 
-Adding social connection with Atlassian to your app with Clerk is done in a few steps - you will need to populate the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings.
+## Configure for your development instance
 
-To make the development flow as smooth as possible, Clerk uses  preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed.
+For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed.
 
-For production instances, you will need to generate your own Client ID and Client Secret using your Atlassian account.
+1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
+1. Select **Add connection** and select **For all users**.
+1. In the **Choose provider** dropdown, select **Atlassian**.
+1. Select **Add connection**.
 
-> [!NOTE]
-> The purpose of this guide is to help you create an Atlassian account and an Atlassian OAuth 2.0 Integration - if you're looking for step-by-step  instructions using Clerk to add social connection (OAuth) to your  application, follow the [Social connection (OAuth) guide](/docs/authentication/social-connections/oauth).
+## Configure for your production instance
 
-## Before you start
+For _production instances_, you must provide custom credentials.
 
-- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk).
-- You need to have a Atlassian developer account. To create one, [click here](https://developer.atlassian.com/).
+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 [Atlassian Developer console](https://developer.atlassian.com/console/myapps/).
 
-## Configuring an Atlassian OAuth 2.0 Integration
+<Steps>
+  ### Enable Atlassian as a social connection
 
-You can navigate to the [list of all your apps](https://developer.atlassian.com/console/myapps/) to select an existing app or create a new one:
+  1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
+  1. Select **Add connection** and select **For all users**.
+  1. In the **Choose provider** dropdown, select **Atlassian**.
+  1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on.
+  1. Save the **Callback URL** somewhere secure. Keep this modal and page open.
 
-![Atlassian app listing](/docs/images/authentication-providers/atlassian/37ec3daaa6d6eaa060ad7fecb112ae6d1ef46597-3456x1844.png)
+  ### Create an Atlassian workspace
 
-From there, click on the desired existing app or create a new one, which will take you to the app page.
+  > [!TIP]
+  > If you already have an Atlassian workspace you'd like to connect to Clerk, select your workspace from the [Atlassian Developer console](https://developer.atlassian.com/console/myapps/) and skip to [the next step in this tutorial](#configure-your-atlassian-app).
 
-![Atlassian OAuth 2.0 app page](/docs/images/authentication-providers/atlassian/597e9bdc5a6b521bcbf8223c04a1102683bf9231-3456x1730.png)
+  1. In the [Atlassian Developer console](https://developer.atlassian.com/console/myapps/), next to **My apps**, select **Create**. Then, select **OAuth 2.0 integration**. You'll be redirected to the **Create a new OAuth 2.0 (3LO) integration** page.
+  1. Fill out the necessary information. Then, select **Create**. Once the integration is created, you'll be redirected to the app's **Overview** page.
 
-While not necessary for the integration to work, you can edit your app name, description and set a logo for it in the **Settings** tab.
+  ### Configure your Atlassian app
 
-![Atlassian OAuth 2.0 settings page](/docs/images/authentication-providers/atlassian/b2762ea10eebe6f05f39aa9ed33c54ca41bc2f3d-3456x1730.png)
+  1. In the left sidebar of your app's **Overview** page, select **Permissions**. Configure the OAuth 2.0 scopes to request from your users when they connect with Atlassian. At a minimum, next to **User identity API**, select **Add**.
+  1. In the left sidebar, select **Authorization**.
+  1. Next to **OAuth 2.0 (3LO)**, select **Add**.
+  1. In the **Callback URL** field, paste the **Callback URL** you saved from the Clerk Dashboard.
+  1. Select **Save changes**.
+  1. In the left sidebar, select **Settings**.
+  1. Under **Authentication details**, save the **Client ID** and **Secret** somewhere secure.
+  1. In the left sidebar, select **Distribution**.
+  1. Select **Edit**.
+  1. Set the **Distribution Status** to **Sharing**.
+  1. Complete the required fields. For **Does your app store personal data?**, select **Yes**, as Clerk uses the user's personal data to authenticate them.
+  1. Select **Save changes**.
 
-From the app page, click on the **Permissions** tab in the sidebar menu.
+  ### Set the Client ID and Secret in the Clerk Dashboard
 
-![Atlassian OAuth 2.0 Integration permissions](/docs/images/authentication-providers/atlassian/04fa49b7d9ba58c0faf2c2b97f85b5ea17a9ebe6-3456x1730.png)
+  <Include src="_partials/authentication/set-client-id-secret" />
 
-Here, you will need to configure the OAuth 2.0 scopes that should be requested from your users when they attempt to connect with Atlassian.
+  ### Test your connection
 
-At the very minimum, you will need to enable the **User identity API**, which corresponds to the `read:me` OAuth 2.0 scope. This enables Clerk to retrieve basic user profile info when creating users for your app.
+  > [!WARNING]
+  > To be able to connect, the user must have access to at least one Atlassian site (e.g. JIRA, Confluence). Currently, the user can authorize access only to a single Atlassian site.
 
-Afterwards, you will need to set up the Callback URL so that Atlassian can redirect back to your Clerk app upon successful connection.
-
-This is done by navigating to the Authorization section and clicking on Add.
-
-![Atlassian OAuth 2.0 Authorization page](/docs/images/authentication-providers/atlassian/3d60a54bb48c03257afbf769f1f50cf45f18871c-3456x1730.png)
-
-In this section, you will need to paste the Redirect URI that Clerk has provided for you.
-
-![Atlassian OAuth 2.0 App callback URL settings](/docs/images/authentication-providers/atlassian/a6dc9bd0902359cad9c94de1bdcbd4c9112bff1d-3456x1730.png)
-
-After entering the callback URL, the Client ID & Client Secret will now be available in the **Settings** tab:
-
-![Atlassian OAuth 2.0 settings page with Client ID & Client Secret](/docs/images/authentication-providers/atlassian/fdc89459cdc6450c4dbde713e7b840d93b01c862-3456x1730.png)
-
-You will need to copy these values and paste:
-
-- The Atlassian Client ID to the **Client ID** input on Clerk
-- The Atlassian Client Secret to the **Client Secret** input on Clerk
-
-![Client ID and Client Secret inputs for Atlassian connection](/docs/images/authentication-providers/atlassian/6ef7100945fb68a379b35a5c295a76405a2cf10e-1156x1354.png)
-
-If you have enabled further scopes on Atlassian, you can add them in the  Clerk Atlassian configuration settings as well. This will affect the  tokens that Atlassian issues to you, so that you can access the intended Atlassian resources.
-
-Finally, you will need to make your Atlassian app publicly accessible, since it  starts out as private by default. This is done from the **Distribution** tab:
-
-![Atlassian OAuth 2.0 app distribution settings](/docs/images/authentication-providers/atlassian/83d5498c454f5ba0b92a76c4a1942e9a07cde48d-3456x1730.png)
-
-After clicking on **Edit**, you will need to provide the following information and save the form:
-
-- Set the distribution status to **Sharing**
-- Enter your vendor name
-- Enter a link to your privacy policy page
-- Enter a link to yout terms page
-- Add a contact page link (optional)
-- Indicate that your data _does_ store data, since at the very least the user profile info is used to create users on the Clerk end
-
-![Atlassian OAuth2 distribution sharing form](/docs/images/authentication-providers/atlassian/07c724b9a66773c94c169cc2a199a549c45d8fdd-3456x1730.png)
-
-Notes:
-
-- To be able to connect, the user must have access to at least one Atlassian site (e.g. JIRA, Confluence)
-- Currently the user can authorize access only to a single Atlassian site
-
-Congratulations! Social connection with Atlassian is now configured for your instance.
+  <Include src="_partials/authentication/test-your-connection" />
+</Steps>

docs/authentication/social-connections/coinbase.mdx

@@ -35,7 +35,7 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a
 
 For _production instances_, you must provide custom credentials.
 
-To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Coinbase's Developer Platform](https://portal.cdp.coinbase.com).
+To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Coinbase Developer Platform](https://portal.cdp.coinbase.com).
 
 <Steps>
   ### Enable Coinbase as a social connection in Clerk

docs/authentication/social-connections/github.mdx

@@ -45,15 +45,15 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   1. Select **Add connection** and choose **For all users**.
   1. In the **Choose provider** dropdown, select **GitHub**.
   1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on.
-  1. Save the **Redirect URI** somewhere secure. Keep the modal and page open.
+  1. Save the **Authorization Callback URL** somewhere secure. Keep the modal and page open.
 
   ### Create a GitHub app
 
   1. In the left sidebar of your [GitHub's Developer Settings](https://github.com/settings/apps), select **OAuth Apps**.
   1. Select **New OAuth app**. You'll be redirected to the **Register a new OAuth app** page.
-  1. Complete the required fields. In **Authorization callback URL**, paste the **Redirect URI** you saved from the Clerk Dashboard.
+  1. Complete the required fields. In **Authorization Callback URL**, paste the **Authorization Callback URL** you saved from the Clerk Dashboard.
   1. Select **Register application**. You'll be redirected to your app's **General** page.
-  1. Select **Generate a new client secret**. Save the **Client ID** and **Client secret** somewhere secure.
+  1. Select **Generate a new client secret**. Save the **Client ID** and **Client Secret** somewhere secure.
 
   ### Set the Client ID and Client Secret in the Clerk Dashboard
 

docs/authentication/social-connections/hubspot.mdx

@@ -1,36 +1,67 @@
 ---
 title: Add HubSpot as a social connection
-description: Learn how to setup social connection with HubSpot.
+description: Learn how to allow users to sign up and sign in to your Clerk app with their HubSpot account using OAuth.
 ---
 
-How to set up social connection with HubSpot
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "A Clerk application is required.",
+      link: "/docs/quickstarts/setup-clerk",
+      icon: "clerk",
+    },
+    {
+      title: "A HubSpot Developer account is required.",
+      link: "https://app.hubspot.com/signup-hubspot/developers",
+      icon: "user-circle",
+    }
+  ]}
+>
+  - Use HubSpot to authenticate users with OAuth
+</TutorialHero>
 
-## Overview
+Enabling OAuth with HubSpot allows your users to sign up and sign in to your Clerk application with their HubSpot account.
 
-Adding social connection with HubSpot to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings.
+## Configure for your development instance
 
-To make the development flow as smooth as possible, Clerk uses  preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed.
+For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed.
 
-For production instances, you will need to create your own developer account with **HubSpot** and generate your own Client ID and Client secret.
+1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
+1. Select **Add connection** and select **For all users**.
+1. In the **Choose provider** dropdown, select **HubSpot**.
+1. Select **Add connection**.
 
-> [!NOTE]
-> The purpose of this guide is to help you set up a HubSpot developer account and a HubSpot OAuth app - if you're looking for step-by-step instructions using Clerk to add social connection (OAuth) to your  application, follow the [Social connection (OAuth) guide](/docs/authentication/social-connections/oauth).
+## Configure for your production instance
 
-## Before you start
+For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your HubSpot Developer account.
 
-- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk).
-- You need to have a HubSpot Developer account. To create one, [click here](https://app.hubspot.com/signup/developers/step/existing-user?_ga=2.145169076.1430980384.1628431607-741498900.1628431607).
+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 [HubSpot developer account](https://app.hubspot.com/signup-hubspot/developers).
 
-## Configuring HubSpot social connection
+<Steps>
+  ### Enable HubSpot as a social connection
 
-First, you need to create a new HubSpot app and enable OAuth support. Follow the official HubSpot [Creating an App](https://developers.hubspot.com/docs/api/creating-an-app) guide.
+  1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
+  1. Select **Add connection** and select **For all users**.
+  1. In the **Choose provider** dropdown, select **HubSpot**.
+  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 this modal and page open.
 
-Once your app is created, click on the **Auth** tab and copy the **App Id** and **Client secret**, as shown below.
+  ### Create a HubSpot Developer project
 
-![Configuring a HubSpot app](/docs/images/authentication-providers/hubspot/02d8bf249b4a6debe85e66ea53b5f88817acdba0-1489x995.png)
+  1. Navigate to the [HubSpot account selection page](https://app.hubspot.com/myaccounts-beta) and select the **developer** account you want to use. You'll be redirected to the **Developer home** page.
+  1. Select **Create app**. You'll be redirected to the app's configuration settings.
+  1. In the **App Info** tab, complete the form. The **Public app name** is required.
+  1. Select the **Auth** tab.
+  1. In the **Redirect URLs** section, paste the **Redirect URI** value you saved from the Clerk Dashboard.
+  1. Select **Create app**. You'll be redirected back to the **App Info** tab.
+  1. Select the **Auth** tab.
+  1. Save the **Client ID** and **Client Secret** values somewhere secure.
 
-In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **HubSpot**. Toggle on **Use custom credentials** and paste the values you obtained during the previous step.
+  ### Set the Client ID and Client Secret in the Clerk Dashboard
 
-Before you close the modal, copy the **Redirect URI**. Go back to the HubSpot panel and paste it into the **Redirect URL** field and click **Save**.
+  <Include src="_partials/authentication/set-client-id-and-client-secret" />
 
-Finally, select **Add connection** so that the settings are applied. Congratulations! Social connection with HubSpot is now configured for your instance.
+  ### Test your connection
+
+  <Include src="_partials/authentication/test-your-connection" />
+</Steps>

docs/authentication/social-connections/notion.mdx

@@ -50,17 +50,13 @@ To make the setup process easier, it's recommended to keep two browser tabs open
 
   1. In the top-right of the [Notion Developer](https://developers.notion.com) home page, select **View my integrations**. You'll be redirected to the **Integrations** page.
   1. Select **New integration**.
-  1. Fill out the necessary information. In the **Type** dropdown, select **Public**. Under **Redirect URIs**, paste the **Authorization URL** value you saved from the Clerk Dashboard and then select it.
+  1. Fill out the necessary information. In the **Type** dropdown, select **Public**. Under **Authorization URL**, paste the **Authorization URL** value you saved from the Clerk Dashboard and then select it.
   1. Select **Save**. The **Integration successfully created** modal will open. Select **Configure integration settings**. You'll be redirected to the app's **Configuration** page.
   1. Save the **OAuth Client ID** and **OAuth Client Secret** somewhere secure.
 
   ### Set the Client ID and Client Secret in the Clerk Dashboard
 
-  1. Navigate back to the Clerk Dashboard where the modal should still be open. Paste the **OAuth Client ID** and **OAuth Client Secret** values that you saved into the respective fields.
-  1. Select **Add connection**.
-
-  > [!NOTE]
-  > If the modal or page is not still open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the connection. Under **Use custom credentials**, you can paste the **OAuth Client ID** and **OAuth Client Secret** into their respective fields.
+  <Include src="_partials/authentication/set-client-id-secret" />
 
   ### Test your connection
 

docs/references/backend/invitations/create-invitation.mdx

@@ -26,7 +26,7 @@ function createInvitation(params: CreateParams): Promise<Invitation>
   - `redirectUrl?`
   - `string`
 
-  The URL to redirect the user to when they visit the invitation link.
+  The URL where the user is redirected upon visiting the invitation link, where they can accept the invitation. Required if you have implemented a [custom flow for handling application invitations](/docs/custom-flows/invitations).
 
   ---
 

docs/references/react/use-auth.mdx

@@ -62,6 +62,8 @@ The `useAuth()` hook provides access to the current user's authentication state
 
   A function that signs out the current user. Returns a promise that resolves when complete. See the [reference doc](/docs/references/javascript/clerk/clerk#sign-out).
 
+  ---
+
   - `getToken()`
   - `(options?: GetTokenOptions) => Promise<string | null>`