Signup & Forgot Password

SignupForm and ForgotPasswordForm are standalone components that handle their respective multi-step flows internally. Both use ChallengeView for email verification. Both require <AilitaProvider> as an ancestor to access merchant configuration and inject API credentials.

How It Works

User fills the registration form

SignupForm collects firstName, lastName, email, password (optional when loginMode is OTP_EMAIL), and phone (optional). Password requirements: minimum 8 characters, must contain at least one letter and one number. The password field is hidden entirely when the merchant uses OTP-only authentication.

Library submits signup request

On submit, the library calls the signup API with the form data plus device fingerprint and behavioral biometrics — both collected automatically in the background before the user clicks submit. The app and mid tenant identifiers are injected from the merchant context automatically. You do not provide them.

Email verification

Two outcomes depending on the backend response:1. challengeId returned — SignupForm shows an inline ChallengeView where the user enters a 6-digit OTP sent to their email. After successful verification, onSuccess(userId) fires and the user is considered fully registered.2. No challengeId — SignupForm shows a “Check your email” message with an activation link instruction. The user must click the link in their email before they can log in. onSuccess does not fire in this case.

Account activated

After email verification (OTP or link), the account moves to active status and the user can log in via LoginForm.

A signed-up user cannot log in until their email is verified. If your app redirects to the login page immediately after signup, display a message reminding the user to check their email first. Do not call router.push('/dashboard') inside onSuccess without confirming the user’s email is already verified — the standard approach is to navigate to a “check your email” page instead.

The table below shows what state the user account is in at each stage of the signup flow.

After	User Status	Email Status	Can Login?
Form submitted	`ACTIVE`	`VALIDATION_SENT`	No
Email verified (OTP or link)	`ACTIVE`	`VALIDATED`	Yes

The signupMode of the merchant controls who can sign up. When set to INVITATION_ONLY, SignupForm shows a 403 error: “Registration on this platform is by invitation only.” Users without a prior invitation cannot create accounts. The signupMode is configured on the backend — see Provider Setup for details.

SignupForm Props

'full-screen' | 'side-screen'

Controls the visual layout. full-screen renders a centered card on a gray background. side-screen renders the form on the right half with a branded colored panel on the left (uses --color-primary). Defaults to 'full-screen'.

(userId: string) => void

Fires after successful signup and email OTP verification. Receives the new user’s ID. If the backend returns no challengeId (email link verification path), this callback does not fire — the user must navigate to login manually after clicking the link in their email.

Optional. Fires when the user clicks “Already have an account? Log in.” Use this to navigate back to your login page.

(challengeId: string) => void

Optional. If provided, SignupForm does not render the inline ChallengeView after signup. Instead it calls this callback with the challengeId and stops — you are responsible for rendering ChallengeView in a custom location.

This follows the same pattern as LoginForm.onChallengeRequired — provide it only if you want to render ChallengeView outside the form (e.g., in a modal or a separate route). For most apps, omitting this prop is the right choice.

'use client'
import { SignupForm } from 'ailita-library'
import { useRouter } from 'next/navigation'

export default function SignupPage() {
  const router = useRouter()

  return (
    <SignupForm
      onSuccess={() => router.push('/dashboard')}
      onLoginClick={() => router.push('/login')}
    />
  )
}

import { SignupForm } from 'ailita-library'
import { useNavigate } from 'react-router-dom'

export default function SignupPage() {
  const navigate = useNavigate()

  return (
    <SignupForm
      onSuccess={() => navigate('/dashboard')}
      onLoginClick={() => navigate('/login')}
    />
  )
}

Forgot Password Flow

How It Works

User enters email

ForgotPasswordForm collects the user’s email address and calls the forgot-password API. The form is a single email field with a submit button.

Email OTP verification

The backend sends a 6-digit code to the provided email address. ForgotPasswordForm transitions to a verification screen and renders an inline ChallengeView for OTP entry.Security behavior: If the email address does not exist in the system, the API returns 404 — but the form still advances to the verification screen and shows: “If the email exists, we sent a code.” This prevents email enumeration attacks. Developers must not override this behavior by adding a custom “email not found” error message.

Set new password

After OTP verification, the form transitions to a new password screen. The user enters a new password (minimum 8 characters, must contain at least one letter and one number) and a confirmation field. Mismatched passwords are validated client-side before the API call.

Password updated

A success confirmation screen is shown with a “Go to login” button. The onSuccess() callback fires at this point.

allowPasswordRecovery

If the merchant has allowPasswordRecovery set to false, ForgotPasswordForm renders only a message: “Forgot your password? Please contact your administrator.” with a link back to login. The forgot-password API is never called. This setting is read from the discovery response automatically — you do not check it manually. See Provider Setup for details on merchant configuration.

ForgotPasswordForm Props

() => void

Optional. Fires after the password has been successfully reset. Use this to navigate the user to the login page or display a global success notification.

Optional. Fires when the user clicks “Back to login” on any step of the flow. Wire this to your login page route.

Forgot Password Integration Example

'use client'
import { ForgotPasswordForm } from 'ailita-library'
import { useRouter } from 'next/navigation'

export default function ForgotPasswordPage() {
  const router = useRouter()

  return (
    <ForgotPasswordForm
      onSuccess={() => router.push('/login')}
      onLoginClick={() => router.push('/login')}
    />
  )
}

import { ForgotPasswordForm } from 'ailita-library'
import { useNavigate } from 'react-router-dom'

export default function ForgotPasswordPage() {
  const navigate = useNavigate()

  return (
    <ForgotPasswordForm
      onSuccess={() => navigate('/login')}
      onLoginClick={() => navigate('/login')}
    />
  )
}

Wiring All Auth Pages Together

The recommended routing structure for a complete authentication surface:

/login           → <LoginForm onSignupClick={→/signup} onForgotPasswordClick={→/forgot-password} />
/signup          → <SignupForm onLoginClick={→/login} />
/forgot-password → <ForgotPasswordForm onLoginClick={→/login} />

All three components are self-contained. They manage their own internal state machines and render ChallengeView inline when needed. You only need to wire the navigation callbacks — no state lifting required.

Next Steps

Auth Flows

Deep dive into the login state machine, challenge handling, and TOTP verification.

Hooks: useAuth & useUser

Access auth state, user data, and trigger auth actions programmatically.

Getting started

Auth & identity

Session management

Component reference

Security

How It Works

SignupForm Props

Forgot Password Flow

How It Works

allowPasswordRecovery

ForgotPasswordForm Props

Forgot Password Integration Example

Wiring All Auth Pages Together

Next Steps

Auth Flows

Hooks: useAuth & useUser

​Signup Flow

​How It Works

​Post-Signup State

​SignupForm Props

​Signup Integration Example

​Forgot Password Flow

​How It Works

​allowPasswordRecovery

​ForgotPasswordForm Props

​Forgot Password Integration Example

​Wiring All Auth Pages Together

​Next Steps

Auth Flows

Hooks: useAuth & useUser

Signup Flow

How It Works

Post-Signup State

SignupForm Props

Signup Integration Example

Forgot Password Flow

How It Works

allowPasswordRecovery

ForgotPasswordForm Props

Forgot Password Integration Example

Wiring All Auth Pages Together

Next Steps