SDK ReferenceReactAuthentication

React SDK — Authentication

The useAuth hook provides the full authentication API. Import it from @aerostack/react.

import { useAuth } from '@aerostack/react'

Auth state

const {
  user,            // User | null
  tokens,          // { accessToken, refreshToken?, expiresAt? } | null
  loading,         // boolean — any auth operation in progress
  error,           // string | null — last error message
  isAuthenticated, // boolean — shorthand for !!tokens?.accessToken
} = useAuth()

User type

interface User {
  id: string
  email: string
  name?: string
  avatar_url?: string
  emailVerified: boolean
  createdAt?: string
  customFields?: Record<string, any>
}

Methods

signIn(email, password, turnstileToken?)

Sign in with email and password. Sets user and tokens on success.

await signIn('[email protected]', 'password')
// or with Turnstile bot protection:
await signIn('[email protected]', 'password', turnstileToken)
ParameterTypeRequiredDescription
emailstringYesUser’s email address
passwordstringYesUser’s password
turnstileTokenstringNoCloudflare Turnstile token

Returns: Promise<AuthResponse> — { user, accessToken, refreshToken }

signUp(email, password, opts?)

Register a new user. If email verification is enabled, requiresVerification: true is returned.

const result = await signUp('[email protected]', 'password', {
  name: 'Jane Doe',
  customFields: { plan: 'free' },
  turnstileToken: token,
})
 
if (result.requiresVerification) {
  // Show "check your email" message
}
ParameterTypeRequiredDescription
emailstringYesNew user’s email
passwordstringYesNew user’s password
opts.namestringNoDisplay name
opts.customFieldsRecord<string, any>NoCustom profile fields
opts.turnstileTokenstringNoBot protection token

signOut()

Sign out the current user. Invalidates the refresh token server-side and clears local state.

await signOut()
// user and tokens are now null

sendOTP(identifier, type?)

Send a one-time code to an email address or phone number.

await sendOTP('[email protected]', 'email')
await sendOTP('+1234567890', 'phone')
ParameterTypeDefaultDescription
identifierstring—Email or phone number
type'email' | 'phone''email'Delivery method

verifyOTP(identifier, code, type?)

Verify the OTP code and sign in. Sets user and tokens on success.

await verifyOTP('[email protected]', '123456', 'email')
ParameterTypeDefault
identifierstring—
codestring—
type'email' | 'phone''email'

verifyEmail(token)

Verify the email address using the token from the verification email link.

// In your /verify-email page
const token = new URLSearchParams(window.location.search).get('token')
await verifyEmail(token)

resendVerificationEmail(email)

Resend the email verification link.

await resendVerificationEmail('[email protected]')

requestPasswordReset(email, turnstileToken?)

Send a password reset email.

await requestPasswordReset('[email protected]')

resetPassword(token, newPassword)

Set a new password using the token from the reset email.

const token = new URLSearchParams(window.location.search).get('token')
await resetPassword(token, 'newSecurePassword123')

refreshAccessToken(refreshToken)

Refresh the access token. Called automatically by the SDK on 401 responses, but can also be called manually.

const newTokens = await refreshAccessToken(tokens.refreshToken)

refreshUser()

Re-fetch the current user’s profile and update local state.

await refreshUser()
// user state is updated from the server

updateProfile(updates)

Update the current user’s profile. Calls refreshUser() automatically.

await updateProfile({
  name: 'New Name',
  avatar_url: 'https://cdn.example.com/avatar.jpg',
  customFields: { plan: 'pro' },
})
ParameterTypeDescription
namestringDisplay name
avatar_urlstringAvatar URL
avatar_image_idstringStorage image ID (auto-resolves to URL)
customFieldsRecord<string, any>Merge into existing custom fields

deleteAvatar()

Remove the current user’s avatar.

await deleteAvatar()

Error handling

All methods throw on failure. The error message is also set in error state:

const { signIn, error, loading } = useAuth()
 
const handleSubmit = async () => {
  try {
    await signIn(email, password)
  } catch (err) {
    // err.message is the same as error state
    console.error(err.message)
  }
}
 
// Or use the error state directly:
{error && <p className="text-red-500">{error}</p>}
SetupRealtime