How Sushi SaaS Authentication Works
Follow the shipped sign-in journey, then decide which providers, verification, MFA, tenancy, and abuse controls your product should keep.
This guide is for adopters making authentication a product decision rather than treating it as a login screen. Sushi SaaS uses Better Auth for identity mechanics and adds the tenant, recovery, moderation, and audit rules required by the rest of the starter.
The default user journey
- A user signs up with email and password, or with Google when both OAuth credentials are configured.
- Email/password signup requires email verification. Successful verification can enqueue the one-time signup credit grant.
- Signup creates a personal organization. A repair path creates it later if the original hook was interrupted.
- Sign-in creates a session only after lifecycle and suspension checks pass.
- Password reset revokes existing sessions.
Two-factor authentication is available to customer accounts but is not mandatory for the customer application. It is mandatory for the separate admin console, in addition to an admin_ro or admin_rw operator role.
The configuration lives in src/lib/auth.ts at 7580470. Setup values and callback URLs are covered in Authentication and Admin.
Choices to make before launch
| Decision | Shipped choice | Change it when |
|---|---|---|
| Sign-in methods | Email/password; Google only when configured | Your users require passwordless, enterprise SSO, or another provider |
| Email verification | Required for password signup | Your risk model permits unverified accounts; also decide when signup benefits are granted |
| Customer MFA | Available, user-controlled | Your data sensitivity requires step-up or mandatory MFA |
| Admin MFA | Required | Keep this unless you replace it with an equally strong operator access policy |
| Bot protection | Turnstile on credential and mail endpoints when enabled; production config fails closed around the chosen setting | You use another edge or identity-provider control and update validation and tests with it |
| Tenant creation | Every account gets a personal organization | The product is truly single-user and organization scoping is removed end to end |
Do not simply switch off verification while leaving signup credits attached to verification. Decide whether to move that grant, remove it, or require another proof of account quality.
Identity is not authorization
A valid session answers “who is this?” It does not grant access to every organization's data. Membership roles answer which product actions a user may perform; plan entitlements answer which capabilities the organization bought. Sushi keeps those questions separate.
The Better Auth organization plugin manages owner, admin, and member mechanics. Application services add rules such as seat limits, never removing the last owner, and never leaving a user without a workspace. Generic organization deletion is disabled because deleting auth rows alone would orphan billing and product data.
Read Organizations and Teams before changing roles or tenant selection.
Recovery and abuse controls
Turnstile can protect credential and email-sending endpoints. Signup checks apply to password and OAuth account creation; session creation blocks suspended or erasing accounts regardless of sign-in method. User-visible failures resolve through localized error codes instead of exposing server messages.
These controls still need your policy: who may suspend an account, how appeals work, how long sessions last, which events are retained, and what support may change.
A production test plan
- Verify signup, resend, expiration, and sign-in after verification.
- Reset a password and confirm old sessions stop working.
- Test every configured OAuth callback in its production origin.
- Enroll, verify, recover, and disable MFA; protect backup codes.
- Exercise invitation seat limits and last-owner safeguards concurrently.
- Bootstrap both admin roles and confirm MFA is enforced on the admin origin.
Continue with Admin Console Setup for the operator path. This guide reflects starter commit 7580470.
How Sushi SaaS Is Structured
Understand the starter's enforced layers, the choices behind them, and how to add a feature without creating a second architecture.
How Sushi SaaS Routes Requests
See what the middleware does for users and operators, why organization selection stays visible in the URL, and which routing choices you can change.