(social-connections/bitbucket) update guide (#1864)

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

docs/authentication/social-connections/bitbucket.mdx

@@ -1,61 +1,70 @@
 ---
 title: Add Bitbucket as a social connection
-description: Learn how to set up social connection with Bitbucket.
+description: Learn how to allow users to sign up and sign in to your Clerk app with their Bitbucket account with OAuth.
 ---
 
-How to set up social connection with Bitbucket
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "A Clerk app is required.",
+      link: "/docs/quickstarts/setup-clerk",
+      icon: "clerk",
+    },
+    {
+      title: "A Bitbucket account is required.",
+      link: "https://bitbucket.org/account/signup",
+      icon: "user-circle",
+    }
+  ]}
+>
+  - Use Bitbucket to authenticate users with OAuth
+</TutorialHero>
 
-## Overview
+Enabling OAuth with [Bitbucket](https://developer.atlassian.com/cloud/bitbucket/oauth-2) allows your users to sign up and sign in to your Clerk application with their Bitbucket account.
 
-Adding social connection with Bitbucket 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 Consumer Key and Consumer Secret using your Bitbucket 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 **Bitbucket**.
+1. Select **Add connection**.
 
-> [!NOTE]
-> The purpose of this guide is to help you create a Bitbucket account and a Bitbucket OAuth Consumer - 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 Bitbucket account. To create one, [click here](https://bitbucket.org/account/signup).
+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 [Bitbucket Workspaces](https://bitbucket.org/account/workspaces/) page.
 
-## Configuring Bitbucket social connection
+<Steps>
+  ### Enable Bitbucket as a social connection in Clerk
 
-Firstly, you will need to have a Bitbucket workspace.
+  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 **Bitbucket**.
+  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 the modal and page open.
 
-You can navigate to the [list of all your workspaces](https://bitbucket.org/account/workspaces/) to select an existing workspace or create a new one:
+  ### Create a Bitbucket OAuth Consumer
 
-![Bitbucket workspace listing](/docs/images/authentication-providers/bitbucket/005f4b20222a0641a443f750e24d26fd088324db-3360x1896.png)
+  1. On a separate page, go to the [Bitbucket Workspaces](https://bitbucket.org/account/workspaces/) page and sign in.
+  1. Under **Workspaces**, find your workspace and select **Manage**.
+  1. In the sidebar, scroll down and select **OAuth consumers**.
+  1. Select **Add consumer**.
+  1. Complete the required fields. In  **Permissions** , under **Account**, select **Email** and **Read**.
+  1. Select **Save**. You'll be redirected to the **OAuth consumers** page.
+  1. Select your consumer and save the **Key** and **Secret** values somewhere secure.
 
-From there, click on the desired existing workspace or create a new one, then navigate to:
+  ### Set the Key and Secret in the Clerk Dashboard
 
-**Settings** > **Oauth Consumers**
+  1. Navigate back to the Clerk Dashboard where the modal should still be open. Paste the **Key** and **Secret** values that you saved into the respective fields.
+  1. Select **Add connection**.
 
-![Bitbucket OAuth Consumer list](/docs/images/authentication-providers/bitbucket/b072d3a9f269a46468e651646d08522aa253fdaf-3360x1782.png)
+  > [!NOTE]
+  > If the modal or page is no longer 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**, paste the values into their respective fields.
 
-You will need to create a consumer if you don't have one already.
+  ### Test your connection
 
-The first important setting for the connection to work is the **Callback URL**. Paste the **Redirect URI** from your Clerk Bitbucket settings in this field:
-
-![OAuth consumer creation](/docs/images/authentication-providers/bitbucket/3c3f5f49188f740839a9e0f348ffe4d34a5300c3-3360x1782.png)
-
-The rest of the form fields (**Name, Description, URL, Privacy Policy URL,  EULA URL**) can be set to match your application settings.
-
-The second important setting is the selection of scopes that Clerk should request from Bitbucket upon connecting.
-
-![Bitbucket OAuth Consumer scopes](/docs/images/authentication-providers/bitbucket/65aee792cbde8564897d5f1110caf090789bf532-1304x942.png)
-
-Under **Account**, the **Email** & **Read** scopes should be enabled so that Clerk can use your basic Bitbucket account info when creating your Clerk user.
-
-After saving the Oauth Consumer, Bitbucket will generate a **Consumer Key** and **Consumer Secret** for you. These can be displayed by clicking on the **Consumer** entry in your OAuth Consumer list.
-
-You will need to copy:
-
-- The Bitbucket Client **Key** to the **Client ID** input on Clerk
-- The Bitbucket Client **Secret** to the **Client Secret** input on Clerk
-
-![Client ID and Client Secret inputs for Bitbucket connection](/docs/images/authentication-providers/bitbucket/c29fd970821d0746e7637f69bf8f411695638834-1220x784.png)
-
-Congratulations! Social connection with Bitbucket is now configured for your instance.
+  <Include src="_partials/authentication/test-your-connection" />
+</Steps>