# Authentication

> How the kit signs users up, in and out with self-managed Better Auth on Cloudflare Workers: the flows, the files, and where to change them.

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

---

The kit runs its own [Better Auth](https://www.better-auth.com) instance inside the Void app. Users sign up with email and password, verify their email, sign in, sign out and reset a forgotten password. Sessions live in Postgres, emails go out through `void/email`, and auth requests are rate limited per IP.

## What You Get

| Flow | Page | Notes |
|---|---|---|
| Sign up | `/auth/sign-up` | Always ends on "check your email", also for a taken address, so it never reveals who has an account |
| Verify email | link in the email → `/auth/verify-email` | A good link signs the user in and continues to `next`; a bad or expired one offers a new link |
| Sign in | `/auth/sign-in` | One error for a wrong email or password; an unverified user can resend the link |
| Magic link (`AUTH_MAGIC_LINK=true`) | "Send Email Link" on `/auth/sign-in` and `/auth/sign-up` | No password: the emailed link signs in, creating a verified account for a new address. Same answer for every address |
| Email code (`AUTH_EMAIL_OTP=true`) | "Email me a code" on `/auth/sign-in` and `/auth/sign-up` | A 6-digit code instead of a link, for devices where opening a link is awkward. 3 tries per code, 10 codes per address per 24 hours; a new address gets a verified account |
| OAuth (`AUTH_GOOGLE_CLIENT_ID` + `_SECRET`) | "Continue with Google" on `/auth/sign-in` and `/auth/sign-up` | One click; a new email gets an account. Links to an existing account only when both emails are verified. Other providers take one config entry. See [OAuth Sign-In](./oauth) |
| Two-factor (`AUTH_TWO_FACTOR=true`) | set up at `/settings/security`; asked on `/auth/two-factor` | A code from an authenticator app (or a backup code) after any sign-in method. See [Two-Factor Authentication](./two-factor) |
| Passkeys (`AUTH_PASSKEY=true`) | added at `/settings/security`; "Sign in with a passkey" on `/auth/sign-in` | Fingerprint, face or device PIN; can't be phished, and skips the 2FA code. See [Passkeys](./passkeys) |
| Bot protection (`TURNSTILE_SITE_KEY` + `_SECRET_KEY`) | a Turnstile check on sign-in, sign-up, reset and verify-email | Guards password sign-in and sign-up, the reset request and every email sent; usually invisible. See [Bot Protection](./captcha) |
| Sign out | the account menu on every app page | A POST; cross-site requests are rejected |
| Reset password | `/auth/password-reset` → link → `/password-reset` | Ends every session of the account |

All auth endpoints are Better Auth's own, under `/api/auth/*`. The forms call them from the browser through `authClient`, so Better Auth's origin check and rate limits apply to every request.

{% callout type="note" %}
Signing in by link or code proves the address. On an account that never verified it, Better Auth then removes any password and sessions set before (someone could have registered the address in advance), so that user signs in by link or code, or resets the password.
{% /callout %}

Auth dates use `timestamptz`, so session and verification expiry represent the same instant in every database session timezone. Schema regeneration preserves this setting.

The database enforces one account per provider identity, one membership per organization and user, one passkey per credential id, and one two-factor record per user. Concurrent invitation acceptance keeps one membership; retrying incomplete factor setup updates the existing record.

## Who Can Open a Page

The folder a page lives in decides it. There's no list of protected paths to keep in sync.

| Folder | Who | Example |
|---|---|---|
| `apps/web/pages/(app)/` | Signed-in users only | `pages/(app)/dashboard/index.tsx` is `/dashboard` |
| `apps/web/pages/auth/` | Signed-out visitors only | `/auth/sign-in`, `/auth/sign-up` |
| everywhere else | Everyone | `/`, `/password-reset` |

Signed-out visitors of a signed-in page go to `/auth/sign-in?next=<page>` and come back after signing in. Signed-in users who open an `/auth` page go to `next` or the app home (`APP_HOME_PATH`, default `/dashboard`). See [Sessions and Guards](./sessions-and-guards).

## Where Things Live

| What | File |
|---|---|
| Better Auth options (hooks, rate limits, emails) | `packages/better-auth/src/options.ts` |
| The app's auth instance | `apps/web/config/auth.server.ts` |
| Session helpers (`getSession`, `requireSession`, `getNextPath`) | `apps/web/lib/session.server.ts` |
| Rate-limit overrides (`rateLimitRules`); password rules come from `PASSWORD_REQUIRE_*` | `apps/web/config/auth.config.server.ts` |
| Auth page paths | `apps/web/config/auth-paths.ts` |
| Emails | `apps/web/config/auth-mailer.server.ts` (binds `createQueuedAuthMailer` from `@kit/better-auth/mailer`), strings in `packages/i18n/src/messages/<locale>/auth.json` |
| Session middleware and guards | `apps/web/middleware/06.session.ts` |
| Forms | `packages/auth/src/*.tsx` |
| Pages | `apps/web/pages/auth/`, `apps/web/pages/password-reset/` |
| Generated auth tables | `apps/web/db/auth-schema.ts` (never edit by hand; written by `auth:generate`, see [Adding Plugins](./adding-plugins#what-authgenerate-does)) |

## Pages in This Section

- [Setup](./setup): secret, site URL, email sender, local database and seed users
- [Sessions and Guards](./sessions-and-guards): reading the user in loaders, actions, handlers and components
- [Emails](./emails): what's sent, translations, failures
- [Step-Up Codes](./step-up-codes): emailed codes that confirm a destructive action
- [Rate Limits](./rate-limits): the limits and how to change them
- [Adding Better Auth Plugins](./adding-plugins): plugins and regenerating the schema
- [Testing](./testing): seed users and the e2e helpers
- [Troubleshooting](./troubleshooting)

{% callout type="warning" %}
Never import `void/auth`, use `auth` from `void/client`, or add an `auth.ts` file at the app root. Void would switch on its own auth next to the kit's.
{% /callout %}
