(/social-connections/box) update guide (#1854)

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

Author: alexisintech

docs/authentication/social-connections/box.mdx

@@ -1,36 +1,78 @@
 ---
 title: Add Box as a social connection
-description: Learn how to set up social connection with Box.
+description: Learn how to allow users to sign up and sign in to your Clerk app with their Box account using OAuth.
 ---
 
-How to set up social connection with Box
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "A Clerk app is required.",
+      link: "/docs/quickstarts/setup-clerk",
+      icon: "clerk",
+    },
+    {
+      title: "A Box account is required.",
+      link: "https://account.box.com/login",
+      icon: "user-circle",
+    }
+  ]}
+>
+  - Use Box to authenticate users with OAuth
+</TutorialHero>
 
-## Overview
+Enabling OAuth with Box allows your users to sign up and sign in to your Clerk app with their Box account.
 
-Adding social connection with Box 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 generate your own Client ID and Client secret using your Box 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 **Box**.
+1. Select **Add connection**.
 
-> [!NOTE]
-> The purpose of this guide is to help you create a Box developer account and a Box 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 Box 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 Box developer account. To create one, [click here](https://developer.box.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 [Box Developer Console](https://app.box.com/developers/console).
 
-## Configuring Box social connection
+<Steps>
+  ### Enable Box as a social connection
 
-First, you need to create a new OAuth2 Box app. You can find this option in your **Console > Create new app**. Choose **Custom App** and then select **User Authentication (OAuth 2.0)**.
+  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 **Box**.
+  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.
 
-You need to choose an app name and then click **Create application**.
+  ### Create a Box app
 
-![Adding a name and creating the application](/docs/images/authentication-providers/box/adding-name-and-creating-application.jpg)
+  1. On the homepage of the [Box Developer Console](https://app.box.com/developers/console), select **Custom App**. A modal will open.
+  1. Fill out the necessary information. Use Box's [guide on OAuth 2.0 setup](https://developer.box.com/guides/authentication/oauth2/oauth2-setup/#app-creation-steps) to help you.
+  1. Select **Next**.
+  1. In the list of authentication methods, select **User Authentication (OAuth 2.0)**.
+  1. Select **Create App**. You'll be redirected to the app's **Configuration** page.
+  1. In the **OAuth 2.0 Redirect URIs** section, paste the **Redirect URI** value you saved from the Clerk Dashboard.
+  1. In the **OAuth 2.0 Credentials** section, copy the **Client ID** and **Client Secret** somewhere secure. You'll need them to connect your Box app to your Clerk app.
 
-In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Box**. Toggle on **Use custom credentials** and copy **Redirect URIs**.
+  ### Set the Client ID and Client Secret in the Clerk Dashboard
 
-Copy the **Client ID** and **Client secret** as shown in the above image. Go back to the Clerk Dashboard and paste them into the respective fields.
+  1. Navigate back to the Clerk Dashboard where the modal should still be open. Paste the **Client ID** and **Client Secret** values into the respective fields.
+  1. Select **Add connection**.
 
-Don't forget to click **Apply** in the Clerk Dashboard. Congratulations! Social connection with Box is now configured for your instance.
+  > [!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 **Box** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields.
+
+  ### Test your OAuth
+
+  The simplest way to test your OAuth is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box.
+
+  1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page.
+  1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble:
+
+  - **For development** – `https://your-domain.accounts.dev/sign-in`
+  - **For production** – `https://accounts.your-domain.com/sign-in`
+
+  1. Sign in with your Box account.
+</Steps>