X Enterprises
Composables

useXAuth

Unified Nile Auth composable — toasts, navigation, state, verification pending, MFA, and SDK authorizer escape hatch.

useXAuth

Unified authentication composable for Nile Auth. Wraps the @niledatabase/client Authorizer with reactive shared state (useState), loading indicators, Nuxt UI toasts, and xAuth.redirects navigation.

const {
  user,
  isLoading,
  isAuthenticated,
  emailSent,
  verificationPending,
  pendingSignupEmail,
  checkAuth,
  restore,
  refresh,
  login,
  signup,
  logout,
  forgotPassword,
  resetPassword,
  resendVerificationEmail,
  sendVerificationEmail,
  loginWithMagicLink,
  loginWithOAuth,
  getCurrentUser,
  updateProfile,
  mfaSetup,
  mfaChallenge,
  mfaRemove,
  getProviders,
  getAuthHeaders,
  getToken,
  authorizer,
} = useXAuth()

Returns

KeyTypeDescription
userRef<NileUser | null>Session user merged with /me profile data.
isLoadingRef<boolean>Any in-flight auth operation.
isAuthenticatedRef<boolean>True when an active session is verified.
emailSentRef<boolean>After forgot-password / magic-link (non-disclosing).
verificationPendingRef<boolean>Signup returned Nile's verification-required status.
pendingSignupEmailRef<string>Address for resendVerificationEmail().
login(email, password)Promise<NileUser | null>MFA challenge → navigates to /auth/mfa. Success → afterLogin.
signup(email, password, opts?)Promise<NileUser | null>Verification required → sets verificationPending. Success → afterSignup.
resendVerificationEmail()Promise<boolean>Resend to pendingSignupEmail or current user.
sendVerificationEmail(email, callback?)Promise<boolean>Send verification email via CSRF + POST /auth/verify-email.
forgotPassword(email)Promise<boolean>Non-disclosing. POST /auth/reset-password without json=true.
resetPassword(password)Promise<true | { error }>Completes reset via authorizer.forgotPassword (PUT).
loginWithMagicLink(email, callback?)Promise<boolean>Send passwordless magic link to email.
loginWithOAuth(provider, callback?)Promise<boolean>Starts OAuth/SSO flow for the given provider.
updateProfile(data)Promise<{ ok?: boolean, error?: string }>PUT /me to update profile fields.
mfaSetup(method?)Promise<AuthResponse>Setup authenticator app or email OTP.
mfaChallenge({ token, code, ... })Promise<AuthResponse>Verify challenge code.
mfaRemove({ code?, token?, ... })Promise<AuthResponse>Remove MFA from account.
getProviders()Promise<AuthResponse>List configured OAuth providers on Nile DB.
getAuthHeaders()Promise<Record<string, string>>Returns { 'x-tenant-id': id } when tenant cookie is present.
getToken()Promise<null>Always null (Nile sessions are cookie-based).
authorizerAuthorizerRaw @niledatabase/client singleton for direct SDK operations.

SDK quirks (@niledatabase/client 5.3.1)

  • forgotPassword / resetPassword naming is inverted in the SDK. Send-mail is POST /auth/reset-password without json=true. Complete reset is authorizer.forgotPassword (PUT). Do not use authorizer.resetPassword({ redirect: false }) to send mail.
  • MFA challenge on sign-in: signIn('credentials') returns HTTP 401 + { scope: "challenge", token } which login() maps to navigation to /auth/mfa.
  • credentials: "include": applied via authorizer.configure({ init }) because constructor ignores init. SDK hard-reloads after credential sign-in/sign-up.
  • Authorizer URL split: resolveNileAuthorizerEndpoints handles origin and full-URL basePath resolution.
  • Verify click does not create a session: User clicks verification link and must sign in to establish session cookies.

AI Context

composable: useXAuth
package: "@xenterprises/nuxt-x-auth-nile"
use-when: >
  Standard Nile UI and auth operations. Unified composable with reactive state,
  toasts, and navigation. Use authorizer for raw SDK calls if needed.

Handler

Generic auth callback handler for Nile Auth — OAuth round-trips, password reset, and generic callbacks.

Configuration

xAuth app.config.ts, branding, consents, and runtimeConfig for nuxt-x-auth-nile.

Copyright © 2026