Authentication Setup

The environment variables, email sender and local database authentication needs, locally and when deployed.

Authentication needs a secret, the site's URL, the product name and an email sender. Everything else has a default.

This page is part of the Authentication documentation.

Locally

pnpm kit:setup # .env with its own BETTER_AUTH_SECRET, database, migrations, the app; asks before demo data

With demo data, sign in at http://localhost:5173/auth/sign-in as user1@makerkit.dev (to user5), password testingpassword. Emails the app sends land in Void's dev inbox (http://localhost:5173/__void/inbox?token=…; the link is in .makerkit/processes/app.log, or printed by pnpm dev at startup).

pnpm db:seed resets the database it points at before seeding (it runs void db seed after dropping the schemas Void's reset keeps, such as outbox). Use void db migrate to keep existing data.

Environment Variables

VariableRequiredWhat it does
BETTER_AUTH_SECRETyesSigns session cookies and email tokens. At least 32 characters; generate one with openssl rand -base64 32. A Worker secret in production, never VITE_*. Changing it signs everyone out and invalidates links already sent.
SITE_URLyesThe public URL, e.g. https://app.example.com. Must be https (http only for localhost). Better Auth builds email links from it, accepts requests only from this origin, and uses secure cookies when it is https. pnpm preview uses its own address, http://localhost:4173.
PRODUCT_NAMEyesYour product's name, in email subjects and bodies.
AUTH_RATE_LIMITno (true)Per-IP rate limits on auth endpoints. See Rate Limits.
AUTH_PASSWORDno (true)Email and password sign-in and sign-up. Off: Better Auth refuses its password endpoints, the forms hide, and the password-reset pages answer 404. Keep at least one sign-in method on.
AUTH_MAGIC_LINKno (false)Sign-in with an emailed link. Off: Better Auth's magic-link plugin isn't registered (no endpoints) and the forms don't show it.
AUTH_EMAIL_OTPno (false)Sign-in with an emailed 6-digit code. Off: Better Auth's email OTP plugin isn't registered. On, only its sign-in endpoints answer; its password reset, email verification and email change by code answer 404.
AUTH_TWO_FACTORno (false)Authenticator-app codes after any sign-in, set up at /settings/security. See Two-Factor Authentication.
AUTH_PASSKEYno (false)Passkey sign-in, passkeys added at /settings/security. See Passkeys.
TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEYnoCloudflare Turnstile on the forms bots abuse, on when both are set. See Bot Protection.
AUTH_GOOGLE_CLIENT_ID, AUTH_GOOGLE_CLIENT_SECRETno"Continue with Google", on when both are set. See OAuth Sign-In.
APP_HOME_PATHno (/dashboard)Where users land after signing in when there's no next.
PASSWORD_REQUIRE_SPECIAL_CHARS, PASSWORD_REQUIRE_NUMBERS, PASSWORD_REQUIRE_UPPERCASEno (false)Extra password rules. The forms show them and the server enforces them on every endpoint that sets a password. Passwords are always 8–128 characters.

The full list is in Environment Variables. void env check validates them, and the deployed Worker refuses to start with a missing or short secret.

Email Sender

Auth emails go out through void/email from the address in apps/web/void.config.ts:

apps/web/void.config.ts

email: { from: 'Acme <noreply@acme.com>' },

On Cloudflare, sending to any address needs the Workers Paid plan and Email Sending set up for your domain (pnpm --filter web exec void email setup --platform cloudflare). See Production. The kit needs Workers Paid anyway: password hashing can exceed the Free plan's CPU limit.

Deployed

  • Set every key as a Worker secret: pnpm --filter web exec void secret put SITE_URL, then PRODUCT_NAME and BETTER_AUTH_SECRET. void deploy refuses to deploy while a required one is missing.
  • Leave AUTH_RATE_LIMIT on.
  • void deploy applies migrations (with DATABASE_URL in the deploy shell); the auth tables are in the first one. See Production.
  • Never run void db seed against a deployed database: the seed users have a public password.