Set up email and password sign-in
Users can create an account, verify their email address, sign in and reset a forgotten password.
Email and password is the default sign-in method. You set the session secret in the environment, then control sign-up and verification from the admin console.
Before you begin
- A migrated database and a first administrator. See First steps after install.
- An admin account with
config.readandconfig.write. - An email provider, so verification and reset emails can be delivered. See Send transactional email.
Set the session secret and base URL
Set the session secret
Set BETTER_AUTH_SECRET to a long random value in the deployment environment, for example the output of node -e "console.log(crypto.randomUUID()+crypto.randomUUID())". It is the only auth setting stored in the environment, because it is needed before the database is read. Outside development the app does not start without it.
Set the base URL
Sign in as an administrator and go to Settings → Auth Config (/admin/config/auth). In the Better Auth panel, set Base URL to the public URL of your deployment, for example https://<your-domain>, and click Save. The page shows Configuration saved.
Choose the account rules
The Better Auth panel on Auth Config holds the switches that apply to every account.
Set the switches
- Enabled: turns email and password sign-up and sign-in on or off. Saving here also updates the Enabled switch in the Email Login panel, so change it here.
- Delete account: lets signed-in users delete their own account from
/app/profile. - Email verification: when on (the default), a user who has not clicked the verification link cannot sign in, and each attempt sends a fresh verification email.
Leave the secret alone
Secret already holds the value from BETTER_AUTH_SECRET. Leave it blank to keep it.
Save
Click Save. Each panel on the page saves only its own fields.
Changing the secret signs everyone out
Entering a new value in Secret replaces the stored one, and every existing session stops working. With Email verification on and no email provider, sign-up still succeeds but new users cannot sign in.
The Allow new users switch in the Email Login panel does not currently restrict email sign-up.
Verify
Create an account
In a private browser window, open /auth/sign-up and create an account. The form shows that the account was created and asks you to verify your email.
Verify and sign in
Open the link in the verification email. It lands on /auth/verify-email. Then sign in at /auth/sign-in. You land on /app/profile.
Reset the password
Sign out, open /auth/forgot-password and request a reset for the same address. The reset email is always sent in English, and its link opens /auth/reset-password, where you set a new password.
/setup reports whether the session secret is set and at least one sign-in method is available. To check the wiring from the command line, run pnpm validate:auth.
Troubleshooting
Sign-in says the email is not verified
Email verification is on, so unverified addresses are rejected and a new verification email is sent on each attempt. Turn it off on Auth Config if your product does not need verified email. If no email arrives, check the provider on Email Config and the log at /admin/email/deliveries.
The app refuses to start with a session secret error
APP_ENV is not development and BETTER_AUTH_SECRET is unset or still the template value. Set it to a random value.
Sign-in sends users to /system/rate-limited
Sign-in is limited to 10 attempts per 5 minutes for each IP address and email. Wait for the window to pass.
Signed-in users are sent to /system/session-expired
The account's status is Pending. Set it to Active on the user's page in the admin console. See Manage users, roles and permissions.