Kernlift
Login and auth providers

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

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.

Reference

Next steps