# Authentication Setup

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

*Canonical: https://makerkit.dev/docs/void-cloudflare/authentication/setup*

---

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](./overview).

## Locally

```bash
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

| Variable | Required | What it does |
|---|---|---|
| `BETTER_AUTH_SECRET` | yes | Signs 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_URL` | yes | The 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_NAME` | yes | Your product's name, in email subjects and bodies. |
| `AUTH_RATE_LIMIT` | no (`true`) | Per-IP rate limits on auth endpoints. See [Rate Limits](./rate-limits). |
| `AUTH_PASSWORD` | no (`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_LINK` | no (`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_OTP` | no (`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_FACTOR` | no (`false`) | Authenticator-app codes after any sign-in, set up at `/settings/security`. See [Two-Factor Authentication](./two-factor). |
| `AUTH_PASSKEY` | no (`false`) | Passkey sign-in, passkeys added at `/settings/security`. See [Passkeys](./passkeys). |
| `TURNSTILE_SITE_KEY`, `TURNSTILE_SECRET_KEY` | no | Cloudflare Turnstile on the forms bots abuse, on when both are set. See [Bot Protection](./captcha). |
| `AUTH_GOOGLE_CLIENT_ID`, `AUTH_GOOGLE_CLIENT_SECRET` | no | "Continue with Google", on when both are set. See [OAuth Sign-In](./oauth). |
| `APP_HOME_PATH` | no (`/dashboard`) | Where users land after signing in when there's no `next`. |
| `PASSWORD_REQUIRE_SPECIAL_CHARS`, `PASSWORD_REQUIRE_NUMBERS`, `PASSWORD_REQUIRE_UPPERCASE` | no (`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](../configuration/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`:

```ts {% title="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](../deployment/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](../deployment/production).
- Never run `void db seed` against a deployed database: the seed users have a public password.
