(social-connections/hubspot) update guide (#1859)

Co-authored-by: victoria <[email protected]>

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>