Better-Auth API Call Map¶

Auth Flows¶

LoginScreen -> useLogin (authClient.signIn.email)
  |-- Success, no 2FA -> applyPendingReferralCode -> authenticated
  +-- Success, 2FA required -> useSend2faOtp -> navigate to Login2faScreen
      +-- Login2faScreen -> useVerify2faOtp -> applyPendingReferralCode -> authenticated

LoginScreen/SignupScreen -> useSocialLogin (authClient.signIn.social)
  +-- Success -> applyPendingReferralCode -> authenticated

SignupWithCredentialsScreen -> useSignup (authClient.signUp.email + emailOtp.sendVerificationOtp)
  +-- applyPendingReferralCode (after signup, before OTP) -> navigate to onboarding
      +-- EmailVerificationProvider gates authenticated area:
          |-- isEmailVerified = false -> shows verification wall
          |   |-- User enters code -> authClient.emailOtp.verifyEmail -> me.refetch() -> children render
          |   +-- Resend button -> authClient.emailOtp.sendVerificationOtp
          +-- isEmailVerified = true -> renders children

4. Forgot password (Better Auth)¶

LoginScreen -> router.navigate('/(public)/forgot-password')
  -> ForgotPasswordScreen -> useRequestPasswordRecovery (authClient.requestPasswordReset)
      +-- Success -> confirmation UI (email sent; link handled by Better Auth email)

Deep link from the email lands on /(public)/reset-password with a token search param (validated via useValidatedSearchParams).

5. Reset password (Better Auth)¶

ResetPasswordScreen -> useResetPassword (authClient.resetPassword { newPassword, token })
  +-- Success -> redirect to login (or authenticated area per screen logic)

Password rules: passwordValidator from @bricks-common/api-communication (MIN_PASSWORD_LENGTH = 12 on clients).

6. Change password (authenticated, Security screen)¶

Account -> SecurityScreen -> ChangePasswordSection
  -> openModal(ChangePasswordModal)
      -> useChangePassword (authClient.changePassword { currentPassword, newPassword, revokeOtherSessions })
          +-- revokeOtherSessions true -> invalidate authQueryKeys.sessions (connected devices list)

Optional revokeOtherSessions checkbox: when enabled, Better Auth invalidates other sessions; the current session stays active.

7. Connected devices (authenticated, Security screen)¶

SecurityScreen -> ConnectedDevicesSection
  -> useListSessions (authClient.listSessions) — queryKey authQueryKeys.sessions, not persisted
  -> useRevokeSession (authClient.revokeSession { token }) per row (cannot revoke current session in UI)

Device labels are derived from session userAgent via parseSessionUserAgent (browser/OS icons).

8. Logout¶

logoutUser() called from:
  |-- LogoutModal — user confirms logout
  |-- Login2faScreen — user taps back (cancels 2FA)
  |-- EmailVerificationProvider — user taps back (cancels verification)
  |-- InformationScreen — WebView sends logout action
  +-- axios interceptor — 401 response (session expired)

logoutUser() does:
  1. authClient.signOut()
  2. clearStorage
  3. logTracing.clearUser
  4. resetBiometricStore
  5. removeQueries (keep maintenance + minimalVersion)
  6. clearMutationCache
  7. stopUserIdentification (CustomerIO)

All authClient Method Calls¶

Method	File	Trigger
`signUp.email`	`services/useSignup.ts`	Credentials signup form
`signIn.email`	`services/useLogin.ts`	Login form
`signIn.social`	`services/useSocialLogin.ts`	Social login button
`signOut`	`utils/authManager.ts` (logoutUser)	Logout / 401
`twoFactor.sendOtp`	`services/useSend2faOtp.ts`	After signIn with 2FA redirect / Resend code
`twoFactor.verifyOtp`	`services/useVerify2faOtp.ts`	User submits 2FA code
`emailOtp.sendVerificationOtp`	`services/useSignup.ts`	After signup (bundled in mutation)
`emailOtp.sendVerificationOtp`	`providers/EmailVerificationProvider.tsx`	Resend button
`emailOtp.verifyEmail`	`providers/EmailVerificationProvider.tsx`	User submits email OTP
`requestPasswordReset`	`services/usePasswordRecovery.ts`	Forgot-password form submit
`resetPassword`	`services/useResetPassword.ts`	Reset-password form submit (token from URL)
`changePassword`	`services/useChangePassword.ts`	Change-password modal submit
`listSessions`	`services/useListSessions.ts`	Security screen — connected devices list
`revokeSession`	`services/useRevokeSession.ts`	Security screen — disconnect a device
`useSession`	`app/_layout.tsx`	Route guard (public vs authenticated)
`useSession`	`providers/MandatoryLoader/MandatoryLoader.tsx`	Splash screen preload
`useSession`	`providers/FundingProgressProvider.tsx` (x2)	SSE connection gate
`getCookie`	`components/AuthenticatedWebView.tsx`	WebView cookie injection (native)
`getCookie`	`utils/axios/axios.ts`	Request interceptor (native, covers all axios calls)
`getCookie`	`providers/FundingProgressProvider.tsx`	SSE headers (native)

applyPendingReferralCode¶

Location: modules/auth/utils/authManager.ts

What it does: 1. Apply referral code if one exists in store (+ clear it)

Note: callers are responsible for calling appQueryClient.invalidateQueries() themselves after a successful auth — it's not part of this helper.

Called from:

File	When
`services/useSignup.ts`	In mutationFn, after signup succeeds
`services/useLogin.ts`	onSuccess, only if `!twoFactorRedirect`
`services/useSocialLogin.ts`	onSuccess after social auth
`services/useVerify2faOtp.ts`	onSuccess after 2FA verification

NOT called from: - providers/EmailVerificationProvider.tsx — only does me.refetch(), no applyPendingReferralCode