[swolfand]

Why

Architecture review finding #9 recommends making Clerk.auth the primary auth API and moving the prebuilt UI onto it. Today the UI can't make that move: signInWithOAuth takes neither transferable nor redirectUrl, and several other UI calls have no facade equivalent. This PR adds every missing piece, so the UI migration PR becomes a mechanical swap.

Stack: #1026 (drift fixes) → #1034 (one implementation per operation + matrix) → this PR.

Scope

I grepped source/ui for every old-layer auth call. The full mapping table is in #1034. Added here:

• Clerk.auth.signInWithOAuth(provider, transferable = true, redirectUrl = default)
• Clerk.auth.signUpWithOAuth(provider, redirectUrl = default, unsafeMetadata = null)
• Clerk.auth.signInWithPasskey(preferImmediatelyAvailableCredentials = false), for the UI's automatic passkey attempt
• Clerk.auth.signInWithGoogleOneTap(transferable = true). It is now the implementation behind SignIn.authenticateWithGoogleOneTap and Clerk.auth.signUpWithGoogleOneTap (which keeps its sign-in-first behaviour from Expose organization switcher sheet and add org list previews #665).
• SignInIdentifierBuilder.identifier, so a single "email, phone or username" field can call Clerk.auth.signIn { identifier = text }
• SignIn.authenticateWithOAuth(provider, transferable, redirectUrl) and SignIn.authenticateWithEnterpriseSso(transferable, redirectUrl) continue an existing sign-in through a redirect factor (prepare + launch). These replace the UI's prepareFirstFactor(OAuth / EnterpriseSSO) + authenticateWithPreparedRedirect pairs.
• SignIn.sendResetPasswordEmailCode(emailAddressId) / sendResetPasswordPhoneCode(phoneNumberId) take factor ids, which is what the UI has. sendResetPasswordCode { } now resolves the factor and delegates to them.
• SignIn.create(Passkey, preferImmediatelyAvailableCredentials) and SignIn.authenticateWithGoogleOneTap now delegate to the facade methods above.

No UI call sites change here, and nothing is deprecated. The deprecation of the old layer with ReplaceWith follows once the UI migration lands. Deprecating now would flood :source:ui with warnings.

Blast Radius

• Source compatible. New parameters have defaults, and new builder properties and extensions are additive.
• Binary compatible. The three widened Auth methods keep their previous JVM signatures as @Deprecated(level = HIDDEN) overloads, and a test checks they still exist. If build: check the public ABI against checked-in dumps #1022 (ABI dumps) lands first, the dump will show the new overloads and nothing removed.
• If build: enable explicit API mode for api, ui and telemetry #1023 (explicit API mode) lands first, the new public declarations need explicit public modifiers. That is a mechanical rebase fix.
• Item 11 (feat(api): add typed Strategy and migrate strategy comparisons #1025 typed Strategy, feat(api): add sealed OAuthResult.Outcome and drop UI force-unwraps #1030 OAuthResult.outcome): the new signatures take OAuthProvider / String / Boolean and return OAuthResult, so they don't depend on either PR and can switch to Strategy later without changing callers. Turning OAuthResult itself into a sealed type is deferred to item 9's follow-up (UI migration + deprecation).
• Item 10 (UI ViewModel stores): no UI files touched. The UI migration PR will rebase on top of it.

Testing

• AuthFacadeUiGapsTest (new, 10 cases): each new parameter or method reaches the right service with the right arguments. It also checks the reset-by-id local failure, the existing-sign-in redirect continuation, and that the old JVM signatures still exist. Against refactor(api): route both auth API layers through one implementation per operation #1034 the file doesn't compile, because the APIs it tests don't exist yet.
• AuthTest: the two Google One Tap tests now mock GoogleSignInService, since the facade no longer goes through SignIn.authenticateWithGoogleOneTap.
• ./gradlew :source:api:spotlessApply :source:api:detekt :source:api:testDebugUnitTest: all pass.
• ./gradlew :source:ui:testDebugUnitTest :source:ui:detekt: all pass.
• ./gradlew :samples:linear-clone:compileDebugKotlin: compiles. It calls signInWithOAuth / signInWithPasskey.

🤖 Generated with Claude Code

Review follow-ups

"Guard the new identifier field and clarify facade redirect and reset docs":

• signIn { identifier = … } now rejects identifier combined with email / phone / username. Before, the identifier silently lost.
• The redirectUrl KDoc on signInWithOAuth / signUpWithOAuth / authenticateWithOAuth / authenticateWithEnterpriseSso now says a custom value must be routed to SSOReceiverActivity, because Clerk.auth.handle() only completes clerk-scheme OAuth callbacks. Changing handle() to route any URI while SSO is pending would cancel the flow on unrelated deep links, so I documented it instead.
• sendResetPasswordEmailCode / PhoneCode KDoc says a null id picks the first reset factor whatever its address, and an explicit id is sent as given.
• New tests: SignIn.create(Passkey, preferImmediatelyAvailableCredentials = true), no redirect after a failed prepare, and the null-id reset fallback.

"Add facade transfers, custom email-link redirects and Enterprise SSO options" closes the gaps that kept old entry points in #1039 without a replacement:

• Clerk.auth.transferToSignIn() / transferToSignUp() complete a transfer after signUpWithIdToken / signInWithIdToken, which don't transfer on their own.
• SignIn.sendEmailLink(emailAddressId, redirectUri) and SignUp.sendEmailLink(redirectUrl) take a custom callback.
• EnterpriseSsoBuilder.redirectUrl and signInWithEnterpriseSso(transferable) { } match what signInWithOAuth already takes.
• The widened functions keep hidden overloads with their previous JVM signatures, and a test checks for them.

Summary by CodeRabbit

• New Features

  • Added support for a general identifier when starting sign-in, alongside email, phone number, and username.
  • Added OAuth and Enterprise SSO sign-in continuation with configurable redirect URLs and transferable settings.
  • Added email and phone reset-code options, including selection of a specific address or phone number.
  • Added Google One Tap sign-in, passkey credential preferences, and configurable OAuth sign-up options.
  • Added custom redirect URLs for email-link sign-in and sign-up, and Enterprise SSO sign-up.

• Bug Fixes

  • Reset-code requests now return a clear failure when no matching email or phone factor is available.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: clerk/clerk-android/.coderabbit.yaml
• Review profile: CHILL
• Plan: Team
• Run ID: 6d858a86-4d28-45a5-a8d2-8811d5a90065

📥 Commits

Reviewing files that changed from the base of the PR and between 2f59745 and 889e262.

📒 Files selected for processing (8)

• source/api/src/main/kotlin/com/clerk/api/auth/Auth.kt
• source/api/src/main/kotlin/com/clerk/api/auth/builders/CommonBuilders.kt
• source/api/src/main/kotlin/com/clerk/api/magiclink/NativeMagicLinkManager.kt
• source/api/src/main/kotlin/com/clerk/api/signin/SignInExtensions.kt
• source/api/src/main/kotlin/com/clerk/api/signup/SignUp.kt
• source/api/src/test/java/com/clerk/api/auth/AuthFacadeUiGapsTest.kt
• source/api/src/test/java/com/clerk/api/magiclink/NativeMagicLinkServiceTest.kt
• source/api/src/test/java/com/clerk/api/signup/SignUpEmailVerificationStrategyTest.kt

Included review availability: This review used your included allowance. 7 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

---

📝 Walkthrough

Walkthrough

Auth adds configurable OAuth and Enterprise SSO redirects, transfer options, passkey preferences, and transfer methods. SignIn adds general identifier input, redirect authentication, custom email-link redirects, and dedicated email and phone reset-code methods. Deprecated overloads retain selected prior method signatures.

Changes

Authentication API extensions

Layer / File(s)	Summary
Auth options and delegation source/api/src/main/kotlin/com/clerk/api/auth/Auth.kt, source/api/src/main/kotlin/com/clerk/api/auth/AuthFlows.kt, source/api/src/main/kotlin/com/clerk/api/signin/SignIn.kt, source/api/src/test/java/com/clerk/api/auth/AuthFacadeUiGapsTest.kt, source/api/src/test/java/com/clerk/api/auth/AuthTest.kt	Auth accepts redirect and transferability options for OAuth and Enterprise SSO, metadata for OAuth sign-up, and an immediate-credential preference for passkey sign-in. It adds Google One Tap sign-in and transfer methods. SignIn and AuthFlows delegate passkey and Google One Tap calls through Auth. Tests check forwarding, transfer requests, and selected JVM signatures.
Identifier input support source/api/src/main/kotlin/com/clerk/api/auth/builders/SignInBuilders.kt, source/api/src/test/java/com/clerk/api/auth/AuthFacadeUiGapsTest.kt, source/api/src/test/java/com/clerk/api/signup/SignUpEmailVerificationStrategyTest.kt	SignInIdentifierBuilder accepts identifier as an alternative to email, phone, and username. It rejects identifier when combined with one of those fields and falls back to it after the existing typed fields. Tests cover identifier input and rejection.
Redirect authentication and email-link and reset-code methods source/api/src/main/kotlin/com/clerk/api/signin/SignInExtensions.kt, source/api/src/main/kotlin/com/clerk/api/magiclink/NativeMagicLinkManager.kt, source/api/src/main/kotlin/com/clerk/api/signup/SignUp.kt, source/api/src/test/java/com/clerk/api/auth/AuthFacadeUiGapsTest.kt, source/api/src/test/java/com/clerk/api/magiclink/NativeMagicLinkServiceTest.kt, source/api/src/test/java/com/clerk/api/signup/SignUpEmailVerificationStrategyTest.kt	SignIn adds OAuth and Enterprise SSO redirect authentication and custom email-link redirects. Dedicated reset-code methods select a supplied factor ID or the first matching factor, and return a failure when no factor is available. SignUp and the native magic-link manager accept custom redirect URLs. Tests cover redirect forwarding, reset-factor selection, and method signatures.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Suggested reviewers: mikepitre

Merge Risk: ⚪ Minimal · up to 889e2

This change adds Clerk.auth facade options and keeps the earlier method signatures through hidden deprecated overloads. No merge-blocking issue was identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.77% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 65 functions across 12 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the API changes that fill gaps needed by the prebuilt UI.
Description check	✅ Passed	The description explains the motivation, scope, compatibility, testing, and follow-up changes. It does not include the template’s explicit “What to focus on” or “Screenshots / video” headings, but the…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}