Skip to content

Refresh social connections overview page#3236

Open
SarahSoutoul wants to merge 14 commits intomainfrom
ss/DOCS-11450
Open

Refresh social connections overview page#3236
SarahSoutoul wants to merge 14 commits intomainfrom
ss/DOCS-11450

Conversation

@SarahSoutoul
Copy link
Copy Markdown
Contributor

@SarahSoutoul SarahSoutoul commented Mar 20, 2026 •
edited by manovotny
Loading

🔎 Previews:

What does this solve? What changed?

The social connections overview was written primarily for web SDKs, but social connections are now supported in the iOS and Android SDKs too. This PR refreshes the page so it reads well for every SDK, adds missing iOS/Android equivalents, and defers to the quickstarts for setup that's already covered elsewhere.

Multi-SDK rewrite

  • Replaced the "Before you start" prose with a <TutorialHero> and added an sdk: frontmatter entry covering web, iOS, Android, and Expo
  • Split the intro and post-auth-manage paragraphs into parallel web/native blocks — web points at prebuilt components and <UserProfile />, native points at prebuilt views and UserProfileView
  • Consolidated "Add a social connection after sign-up" and "Connecting to social providers while signed in" into a single section; preserved universal dashboard steps and Account Portal guidance
  • Unified anchor text on "build a custom OAuth flow" across the page to match the destination page title

New native content

  • Added an iOS-specific "Request additional OAuth scopes after sign-up" using the .userProfileOAuthConfig(_:) modifier on UserProfileView and UserButton, mirroring the web section's additionalOAuthScopes prop pattern
  • Added an Android-specific "Sign in with Google" section pointing to the native Credential Manager flow, mirroring the iOS "Sign in with Apple" section
  • Renamed the confusing sibling sections — "OAuth for native applications" → "Allowlist OAuth redirect URLs", "OAuth for Apple native applications" → "Sign in with Apple" — and fixed the <If> gate on Sign in with Apple so it's iOS-only (was incorrectly gated to iOS + Android)
  • Removed a stale claim that prebuilt components aren't supported in native applications

Cross-references

  • Added see [all providers] inline cross-links to the Sign in with OAuth and Sign up with OAuth sections in docs/reference/native-mobile/auth.mdx and auth.ios.mdx, matching the existing pattern used elsewhere in those files (per this discussion)
  • Updated manifest.json to group "Overview", "Sign in with Apple", and "Sign in with Google" under a new "Social connections" heading in the iOS/Android nav
  • Switched the Sign in with Apple section's link to the dedicated sign-in-with-apple guide, for parity with the new Google section

Drive-by fixes

  • Removed an invalid js-backend SDK and a duplicate expressjs from the overview frontmatter (was breaking the Vercel build), and corrected a /references/backend/ → /reference/backend/ typo in the Astro example
  • Added missing return statements to the Express tab's res.status(401).json(...) calls so the handler stops on auth/token failures
  • Guarded clerkResponse.data[0].token with optional chaining across all six backend tabs so the "Access token not found" branch is reachable when the user hasn't connected the provider
  • Fixed the Next.js tab returning HTTP 200 for unauthenticated requests (comment said the route was protected), and changed the React Router and TanStack tabs from 404 to 401 for auth failures, matching the other tabs
  • Modernized the React Router tab to import clerkClient and getAuth from @clerk/react-router/server (the ssr.server path is deprecated) and use clerkClient(args) from the request context instead of a statically-instantiated client
  • Removed an undefined json() call in the React Router tab and returned the plain object (correct React Router v7 loader pattern)
  • Tightened Sign in with Apple / Sign in with Google prose for correct terminology (ID token, authorization code) and added a Credential Manager link to Android's docs

Known gaps

  • No Android equivalent for "Request additional OAuth scopes after sign-up." The clerk-android SDK doesn't currently support passing additional scopes — CreateExternalAccountParams has no scopes field, ExternalAccount.reauthorize() takes no parameters, and the Android UI has no OAuthConfig equivalent to iOS's .userProfileOAuthConfig(_:). Adding a section here would promise a feature that doesn't exist; this is an SDK gap, not a doc gap.
  • "Get an OAuth access token" remains web-gated. It's inherently a server-side operation (the section itself notes "This method must be used in a server environment, and cannot be run on the client"), so native readers without a server wouldn't have a use for it. A native app with a Node backend can still use the @clerk/backend tab as-is. Broadening the gate raises a larger question about "which SDK owns server-side guidance" that's outside this ticket.
  • Expo readers see the web variant of gated blocks. expo is in the sdk: frontmatter but the <If notSdk={["ios","android"]}> gates keep web content visible for Expo. @clerk/expo supports the web-style prebuilt components referenced, so the guidance isn't wrong. A fuller Expo-specific pass (including expo/native-components/ pointers) is out of scope here.

Deadline

No rush

Other resources

@SarahSoutoul SarahSoutoul self-assigned this Mar 20, 2026
@vercel
Copy link
Copy Markdown

vercel Bot commented Mar 20, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
clerk-docs Ready Ready Preview Apr 24, 2026 7:58pm

Request Review

@manovotny manovotny changed the title (WIP) Refresh social connections overview page Refresh social connections overview page Apr 23, 2026
@manovotny
Merge remote-tracking branch 'origin/main' into ss/DOCS-11450
fedd7e5 
# Conflicts:
#	docs/guides/configure/auth-strategies/social-connections/overview.mdx
@manovotny @claude
Fix overview frontmatter and link native auth refs to providers
7fc9372 
Removes the invalid `js-backend` SDK and the duplicate `expressjs` from
the social connections overview frontmatter (unblocking the build), adds
`expo` to the SDK list, and fixes a `/references/backend/` typo in the
Astro example. Adds `see [all providers]` cross-links to the `Sign in
with OAuth` and `Sign up with OAuth` sections in the native-mobile auth
references, matching the existing pattern used elsewhere in those docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
manovotny and others added 4 commits April 24, 2026 11:42
@manovotny @claude
Make the intro and post-auth sections SDK-aware
8fac424 
Splits the intro into web and native variants so iOS/Android readers see
guidance about prebuilt views and the Clerk SDK instead of prebuilt
components and the Clerk API. Consolidates "Add a social connection
after sign-up" and "Connecting to social providers while signed in"
into a single section with SDK-gated closing guidance that points web
readers to `<UserProfile />` and native readers to `UserProfileView`.
Removes a stale claim that prebuilt components aren't supported in
native applications, and unifies anchor text on "build a custom OAuth
flow" to match the destination page title.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@manovotny @claude
Add iOS equivalent for requesting additional OAuth scopes
b367d3f 
Splits the combined `<If notSdk>` block so each post-sign-up section
can be gated independently, then adds an iOS-only section showing how
to request additional OAuth scopes via `prepareReauthorization` and
`reauthorize` on an existing `ExternalAccount`. Android currently has
no equivalent — `CreateExternalAccountParams` and `ExternalAccount.reauthorize()`
don't accept scope parameters — so no Android section is added.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@manovotny @claude
Disambiguate native section titles and add Android Sign in with Google
252bd3d 
Renames "OAuth for native applications" to "Allowlist OAuth redirect
URLs" and "OAuth for Apple native applications" to "Sign in with
Apple" so the two no longer read as near-duplicates. Splits the
enclosing `<If>` so Sign in with Apple is gated to `ios` only, not
`ios + android`. Adds a parallel Android "Sign in with Google" section
that links to the dedicated native-flow guide, and switches the Apple
section's link to its dedicated `sign-in-with-apple` guide for parity.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@manovotny @claude
Polish overview prose and fix Express return bug
78ce805 
Rewords the production-instances self-link to target the supported
providers list directly, tightens the "Add a social connection after
sign-up" example into a single sentence, unifies SDK array ordering on
`["ios", "android"]`, and tightens the Sign in with Apple and Sign in
with Google prose (correct terminology for ID token / authorization
code, active voice, and a link to Android's Credential Manager docs).
Adds a missing `return` before `res.status(401).json(...)` in the
Express tab so the handler stops executing on auth/token failures.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@manovotny manovotny changed the title Refresh social connections overview page Refresh social connections overview page Apr 24, 2026
@manovotny manovotny marked this pull request as ready for review April 24, 2026 18:09
@manovotny manovotny requested a review from a team as a code owner April 24, 2026 18:09
@manovotny @claude
Fix unsafe access and incorrect status codes in Notion examples
b68ed11 
Guards `clerkResponse.data[0].token` with optional chaining across all
six backend tabs so the "Access token not found" branch is reachable
when the user hasn't connected the provider. Fixes the Next.js tab
returning HTTP 200 for unauthenticated requests (comment says the
route is protected). Removes an undefined `json()` call in the React
Router tab and returns a plain object instead, which is the correct
React Router v7 loader pattern.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@manovotny @claude
Modernize React Router example and use 401 for unauthenticated
0c24a75 
Switches the React Router tab to import `clerkClient` and `getAuth`
from `@clerk/react-router/server` (the `ssr.server` path is
deprecated) and uses `clerkClient(args)` from the request context
instead of instantiating with a secret key. Changes the React Router
and TanStack React Start tabs to return 401 for unauthenticated
requests, matching the other tabs and the standard status for an
auth failure (was 404).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@manovotny @claude
Switch iOS additional-scopes example to the prebuilt view modifier
8b225a7 
Replaces the programmatic `prepareReauthorization` + `reauthorize`
example with the `.userProfileOAuthConfig(_:)` modifier on
`UserProfileView` and `UserButton`, which is the direct iOS parallel
to the web section's `additionalOAuthScopes` prop on `<UserProfile />`
and `<UserButton />`. Matches the web section's component-tab
structure. Custom-flow guidance is already covered by the page's
existing "build a custom OAuth flow" links.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@swolfand swolfand swolfand approved these changes

@seanperez29 seanperez29 seanperez29 approved these changes

At least 1 approving review is required to merge this pull request.

Assignees

@SarahSoutoul SarahSoutoul

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@SarahSoutoul @swolfand @seanperez29 @manovotny