Authentication and Onboarding: Sign-up, Sign-in, Verify, Reset, Plan Gate

This guide covers the account entry flows that exist in the current product, including invitations, 2FA, onboarding, and billing gate behavior.

Key Routes

• /auth/sign-up: create account (email/password or social login)
• /auth/sign-in: sign in (email/password, social login, optional invitation redirect)
• /auth/verify: one-time password verification for 2FA sign-in
• /auth/forgot-password: request reset email
• /auth/reset-password: set a new password using reset token
• /dashboard/onboarding: two-step first-login account setup
• /dashboard/choose-plan: enforced plan selection when billing is enabled without a free tier
• /dashboard/organization-invitation/[invitationId]: invitation acceptance flow after sign-up or sign-in

New User Registration

1. Open /auth/sign-up
2. Submit Name, Email, and Password
3. If verification is enabled, complete the verification step
4. Continue into /dashboard/onboarding when the account is incomplete
5. Finish onboarding and land on /dashboard

Sign-in With 2FA

1. Sign in from /auth/sign-in
2. If TOTP is required, user is redirected to /auth/verify
3. Enter 6-digit code from authenticator app
4. User is redirected to target route (redirectTo / dashboard)

Invitation-Aware Access

If invitationId exists in the URL:

1. Sign up or sign in normally
2. The app preserves invitation context
3. Post-auth redirect targets /dashboard/organization-invitation/[invitationId]
4. Accept the invitation and continue into the target organization

Password Recovery

1. Open /auth/forgot-password
2. Submit account email
3. Open reset link from email
4. Set new password at /auth/reset-password
5. Return to /auth/sign-in

Onboarding Flow

The onboarding flow is split into two explicit steps:

1. Set up your profile
2. Pick your workspace

The workspace step now supports:

• choosing an existing organization
• creating a new workspace during onboarding
• finishing onboarding without an active workspace

If the user finishes without a workspace, the app returns them to /dashboard, where invitations or workspace creation can happen later.

Plan Selection Gate

/dashboard/choose-plan appears when all conditions are true:

• billing is enabled
• no free plan exists
• user has an active organization
• active organization has no paid plan yet

After successful plan selection, user continues to organization workspace.

Troubleshooting

• Redirect loop to sign-in: session expired or cookies blocked by browser policy.
• Verify page does not accept code: device clock drift or wrong authenticator account is common.
• Reset password link fails: token expired or already used; request a new reset link.
• User stays on onboarding: the workspace step may not be completed yet, or the session needs a refresh after profile completion.