(/social-connections/apple) update guide

docs/authentication/social-connections/apple.mdx

@@ -1,6 +1,6 @@
 ---
 title: Add Apple as a social connection
-description: Learn how to allow users to sign into your Clerk app with their Apple ID using OAuth.
+description: Learn how to allow users to sign up and sign in to your Clerk app with their Apple ID using OAuth.
 ---
 
 <TutorialHero
@@ -17,115 +17,111 @@ description: Learn how to allow users to sign into your Clerk app with their App
     }
   ]}
 >
-  - Use [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) to authenticate users with OAuth in your apps and websites.
+  - Use [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) to authenticate users with OAuth
 </TutorialHero>
 
-Enabling OAuth via [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) allows your users to sign in and sign up to your Clerk application with their Apple ID.
+Enabling OAuth via [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) allows your users to sign in and sign up to your Clerk app with their Apple ID.
 
 ## Configure for your development instance
 
 For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs. For **web based flows**, no other configuration is needed. For **native sign-in flows**, you must provide your app's [Bundle ID](https://developer.apple.com/documentation/appstoreconnectapi/bundle_ids).
 
 To configure your development instance, follow these steps:
 
-1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
-1. Select the **Add connection** button, and select **For all users**.
+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 **Apple**.
 1. Then,
-   - For **web based flows**, select **Add connection**.
+   - For **web-based flows**, select **Add connection**.
    - For **native sign-in flows**, enable **Use custom credentials** and provide the **Apple Bundle ID**. If you're unsure about how to find this value, see the [Get your Apple Bundle ID](#get-your-apple-bundle-id) section.
 
 ## Configure for your production instance
 
-In _production instances_, you must provide custom credentials.
+For _production instances_, you must provide custom credentials.
 
-For **web based browser originated flows**, you need to generate and provide your own **Apple Services ID**, **Apple Private Key**, **Apple Team ID**, and **Apple Key ID** using your Apple Developer account.
+For **web based browser originated flows**, you must generate and provide your own **Apple Services ID**, **Apple Private Key**, **Apple Team ID**, and **Apple Key ID** using your Apple Developer account.
 
 For **native sign in flows** (iOS, macOS, watchOS, tvOS), you must _at least_ provide your app's **Apple Bundle ID**. For better results, it's recommended to also provide the web based flow fields.
 
-To configure your production instance, follow these steps:
+To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Apple Developer dashboard](https://developer.apple.com/account).
 
 <Steps>
   ### Enable Apple as a social connection
 
-  To get started, you must enable Apple as a social connection in the Clerk Dashboard.
-
-  1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
-  1. Select the **Add connection** button, and select **For all users**.
+  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 **Apple**.
   1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on.
-  1. (For web based flows) Save the **Email Source for Apple Private Email Relay** and **Return URL** values somewhere secure, as you'll need to supply them to Apple later. Leave this page and modal open.
+  1. (For web-based flows) Save the **Email Source for Apple Private Email Relay** and **Return URL** values somewhere secure, as you'll supply them to Apple later. Keep this page and modal open.
 
   ### Get your Apple Team ID
 
-  The **Apple Team ID** is _required_ for web based OAuth flows and _recommended_ for native app flows.
+  The **Apple Team ID** is _required_ for web-based flows and _recommended_ for native app flows.
 
-  To get your **Apple Team ID**, you must create a new **App ID** in the Apple Developer portal.
+  To get your **Apple Team ID**, create a new **App ID** in the Apple Developer portal by following these steps:
 
-  1. In another tab, navigate to the [Apple Developer portal](https://developer.apple.com/account).
-  1. Under **Certificates, IDs and Profiles**, select **Identifiers**.
-  1. In the dropdown near the top-right of the page, select the **App IDs** option from the list.
-  1. Next to **Identifiers** at the top of the page, select the plus icon (+) to register a new identifier.
-  1. On the **Register a new identifier** page, select **App IDs**, then select **Continue**.
-  1. On the next page, you'll be prompted to **Select a type** for your application. Choose **App** and select **Continue.** You will be redirected to the **Register an App ID** page.
-  1. Fill in a description for your **App ID** and a **Bundle ID**. Any value is fine, such as "Clerk demo app" and "clerkdemoapp", respectively. Under **Capabilities**, ensure that **Sign In with Apple** is enabled. Then select **Continue**. You'll be redirected to the **Confirm your App ID** page.
-  1. At the top of the page, you'll see your **App ID Prefix**. Save this value somewhere secure, as you'll need it to configure your Clerk app. This is your **App Team ID** in Clerk.
-  1. Finally, select **Register**.
+  1. On a separate page, navigate to the [Apple Developer dashboard](https://developer.apple.com/account).
+  1. Under **Certificates, IDs and Profiles**, select [**Identifiers**](https://developer.apple.com/account/resources/identifiers/list).
+  1. In the top-right, select the dropdown and select **App IDs**.
+  1. Next to **Identifiers** at the top of the page, select the plus icon (+) to register a new identifier. You'll be redirected to the **Register a new identifier** page.
+  1. Select **App IDs**, then select **Continue**.
+  1. On the next page, you'll be prompted to **Select a type** for your app. Choose **App** and select **Continue**. You will be redirected to the **Register an App ID** page.
+  1. Fill in a description for your **App ID** and a **Bundle ID**. Under **Capabilities**, ensure that **Sign In with Apple** is enabled. Then select **Continue**. You'll be redirected to the **Confirm your App ID** page.
+  1. At the top of the page, you'll see your **App ID Prefix**. Save this value somewhere secure. This is your **Apple Team ID** in Clerk.
+  1. Finally, select **Register**. You'll be redirected to the **Identifiers** page.
 
   ### Get your Apple Services ID
 
-  The **Apple Services ID** is _required_ for web based OAuth flows and _recommended_ for native app flows.
+  The **Apple Services ID** is _required_ for web-based flows and _recommended_ for native app flows.
 
-  To get your **Apple Services ID**, you must create a new **Services ID** in the Apple Developer portal.
+  To get your **Apple Services ID**, create a new **Services ID** in the Apple Developer portal.
 
-  1. You should be back at the **Identifiers** page.
-  1. In the dropdown near the top-right of the page, select the **Services IDs** option from the list.
-  1. Next to **Identifiers** at the top of the page, select the plus icon (+) to register a new identifier.
-  1. On the **Register new identifier** page, select **Services IDs**, then select **Continue**. You'll be redirected to the **Register a Services ID** page.
-  1. Add a description for your **Services ID**, and set an **Identifier**. Any value is fine, such as "Clerk demo app" and "clerkdemoapp", respectively. Save the **Identifier** value somewhere secure, as you'll need it to configure your Clerk app. This is your **Services ID** in Clerk. Finally, select **Continue**.
+  1. On the **Identifiers** page, in the dropdown near the top-right of the page, select the **Services IDs** option from the list.
+  1. Next to **Identifiers** at the top of the page, select the plus icon (+) to register a new identifier. You'll be redirected to the **Register new identifier** page.
+  1. Select **Services IDs**, then select **Continue**. You'll be redirected to the **Register a Services ID** page.
+  1. Add a description for your **Services ID**, and set an **Identifier**. Save the **Identifier** value somewhere secure. This is your **Apple Services ID** in Clerk. Finally, select **Continue**.
   1. In the confirmation view, select **Register**.
   1. After the registration is finished, select the newly-created **Services ID**. Ensure the **Sign In with Apple** box is enabled and select **Configure**.
   1. Under **Primary App ID**, select the **App ID** you created in the previous step.
-  1. Under **Domains and subdomains**, add your `clerk.<INSERT-YOUR-DOMAIN>.com` domain. Under **Return URLS**, add the **Return URL** value you saved from the Clerk Dashboard. For example, if your domain is `myapp.com`, then you would add `clerk.myapp.com` to **Domains and subdomains** and `https://clerk.myapp.com/v1/oauth_callback` to **Return URLS**.
-  1. Select **Next**. You'll be redirect to the **Confirm your web authentication configuration** screen.
-  1. Select **Done**. You'll be taken back to the **Edit your Services ID Configuration** page.
-  1. Select **Continue**. You'll be taken to the confirmation page.
-  1. Select **Save**.
+  1. Under **Domains and subdomains**, add your Clerk **Frontend API URL** **without the protocol**. For example, if your domain is `https://myapp.com`, then your **Frontend API URL** is `https://clerk.myapp.com`, and you would add `clerk.myapp.com` to **Domains and subdomains**.
+  1. Under **Return URLS**, add the **Return URL** value you saved from the Clerk Dashboard.
+  1. Select **Next**. You'll be redirected to the **Confirm your web authentication configuration** screen.
+  1. Select **Done**. You'll be redirected to the **Edit your Services ID Configuration** page.
+  1. Select **Continue**. You'll be redirected to the confirmation page.
+  1. Select **Save**. You'll be redirected to the **Identifiers** page.
 
   ### Get your Apple Private Key and Key ID
 
-  The **Apple Private Key** and **Key ID** are _required_ for web based OAuth flows and _recommended_ for native app flows.
+  The **Apple Private Key** and **Key ID** are _required_ for web-based flows and _recommended_ for native app flows.
 
-  To get your **Apple Private Key** and **Key ID**, you must create a new **Key** in the Apple Developer portal.
+  To get your **Apple Private Key** and **Key ID**, create a new **Key** in the Apple Developer portal.
 
-  1. You should be back at the **Identifiers** page.
-  1. In the sidebar, select **Keys**.
-  1. Next to **Keys** at the top of the page, select the plus icon (+) to register a new key.
-  1. On the **Register a New Key** page, add a **Key Name** and ensure the **Sign In with Apple** box is enabled and select **Configure**. You'll be redirected to the **Configure Key** page.
-  1. Under **Primary App ID**, select the **App ID** you created in the first step of this guide. Then select **Save**. You'll be taken back to the previous **Register a New Key** page.
-  1. Select **Continue** and you'll be presented with the final confirmation screen. Verify that **Sign in with Apple** is checked and select **Register**. You'll be redirected to the **Download Your Key** page.
-  1. Save the **Key ID** value as you'll need to supply it to Clerk later.
-  1. Download the private key as a file (as the instructions point out, be sure to backup the key in a secure place as it cannot be redownloaded later).
-  1. Select **Done**.
+  1. On the **Identifiers** page, in the sidebar, select **Keys**.
+  1. Next to **Keys** at the top of the page, select the plus icon (+) to register a new key. You'll be redirected to the **Register a New Key** page.
+  1. Add a **Key Name** and ensure the **Sign In with Apple** box is enabled and select **Configure**. You'll be redirected to the **Configure Key** page.
+  1. Under **Primary App ID**, select the **App ID** you created in the first step of this guide. Then select **Save**. You'll be redirected to the previous **Register a New Key** page.
+  1. Select **Continue** and you'll be presented with the final confirmation screen. Verify that **Sign in with Apple** is checked. Select **Register**. You'll be redirected to the **Download Your Key** page.
+  1. Save the **Key ID** value somewhere secure. This is your **Apple Key ID** in Clerk.
+  1. Download the private key as a file. This is your **Apple Private Key** in Clerk. As the instructions point out, be sure to backup the key in a secure place as it cannot be redownloaded later.
+  1. Select **Done**. You'll be redirected to the **Keys** page.
 
   ### Configure Email Source for Apple Private Relay
 
-  This step is _required_ for web based OAuth flows only.
+  This step is _required_ for web-based flows only.
 
   Apple provides a privacy feature called [Hide My Email](https://support.apple.com/en-us/HT210425#hideemail), in which users can sign in to your app with Apple without revealing their real email addresses. Instead, your instance will receive an app-specific email address that will nevertheless forward any emails to the real user's address.
 
   To be able to send emails properly to users with hidden addresses, you must configure an additional setting in the Apple Developer portal.
 
-  1. Return to the **Certificates, Identifiers & Profiles** page.
   1. In the sidebar, select **Services**.
   1. Under **Sign in with Apple for Email Communication**, select **Configure**. You'll be redirected to the **Configure Sign in with Apple for Email Communication** page.
   1. Next to **Email sources** at the top of the page, select the plus icon (+) to add a new **Email Source**.
   1. In the **Register your email sources** modal that opened, under **Email Addresses**, add the **Email Source for Apple Private Email Relay** value that you saved from the Clerk Dashboard. It should look something like this: `[email protected]`.
-  1. Select **Next**. You'll be taken to the confirmation page.
-  1. Select **Register**.
-  1. On the completion page, select **Done**.
+  1. Select **Next**. The modal will redirect to the **Confirm your email sources** page.
+  1. Select **Register**. The modal will redirect to the **Email Source Registration Complete** page.
+  1. Select **Done**.
 
-  After this, you should now see the email address added to the list, and it should be marked as verified with a green check icon. If it does not appear as verified yet, DNS propagation may take some time to complete so wait before trying to select the **Reverify SPF** button.
+  After this, you should now see the email address added to the list, and it should be marked as verified with a green check icon. If it does not appear as verified yet, DNS propagation may take some time to complete so wait before trying to select **Reverify SPF**.
 
   For more info about Apple's Private Relay service, refer to the following documentation:
 
@@ -142,11 +138,11 @@ To configure your production instance, follow these steps:
   1. Under **Certificates, IDs and Profiles**, select **Identifiers**.
   1. In the dropdown near the top-right of the page, select the **App IDs** option from the list.
   1. If you've already set up your project in XCode, your Bundle ID should be already registered. Otherwise, follow the steps below to create a new identifier.
-  1. Next to **Identifiers** at the top of the page, select the plus icon (+) to register a new identifier.
-  1. On the **Register a new identifier** page, select **App IDs**, then select **Continue**.
-  1. On the next page, you'll be prompted to **Select a type** for your application. Choose **App** and select **Continue.** You will be redirected to the **Register an App ID** page.
-  1. Fill in a description for your **App ID** and a **Bundle ID**. Any value is fine, such as "Clerk demo app" and "clerkdemoapp", respectively. Under **Capabilities**, ensure that **Sign In with Apple** is enabled. Then select **Continue**. You'll be redirected to the **Confirm your App ID** page.
-  1. At the top of the page, you'll see your **Bundle ID**. Save this value somewhere secure, as you'll need it to configure your Clerk app. This is your **Apple Bundle ID** in Clerk.
+  1. Next to **Identifiers** at the top of the page, select the plus icon (+) to register a new identifier. You'll be redirected to the **Register a new identifier** page.
+  1. Select **App IDs**, then select **Continue**.
+  1. On the next page, you'll be prompted to **Select a type** for your app. Choose **App** and select **Continue**. You'll be redirected to the **Register an App ID** page.
+  1. Fill in a description for your **App ID** and a **Bundle ID**. Under **Capabilities**, ensure that **Sign In with Apple** is enabled. Then select **Continue**. You'll be redirected to the **Confirm your App ID** page.
+  1. At the top of the page, you'll see your **Bundle ID**. Save this value somewhere secure. This is your **Apple Bundle ID** in Clerk.
   1. Finally, select **Register**.
 
   ### Connect your Apple app to your Clerk app
@@ -161,17 +157,17 @@ To configure your production instance, follow these steps:
 
   Connect your Apple app to your Clerk app by adding these values to the Clerk Dashboard.
 
-  1. Navigate back to the tab where the Clerk Dashboard and your Apple configuration modal is open.
-  1. Add all the corresponding fields depending on your desired flow. For the **Apple Private Key** file, open it with a text editor and just copy/paste the contents.
+  1. Navigate back to the tab where the Apple configuration modal is open in the Clerk Dashboard.
+  1. Add all the corresponding fields depending on your desired flow. For the **Apple Private Key** file, open it with a text editor and copy/paste the contents.
   1. Select **Add connection**.
 
   ### 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.
+  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. On the sign-in page, you should see **Apple** as an option. Use it to sign in with your Apple account.
+     - **For development** - `https://your-domain.accounts.dev/sign-in`
+     - **For production** - `https://accounts.your-domain.com/sign-in`
+  1. Sign in with your Apple account.
 </Steps>