For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/web/authentication.md (or send Accept: text/markdown).
Authentication
Sign-in methods, sessions, and account security.
Create and verify a real account
Authentication means proving who is using the app. Start Postgres and run migrations using the database guide first, then leave the Web server running. Open http://localhost:3000/auth, choose email/password sign-up, enter your name, email and password, and submit. Keep EMAIL_PROVIDER=local for this first test.
When a flow requests an email code, open http://localhost:3000/mail-preview in another browser tab, find the most recent message for that address and copy its code back into the sign-in form. Request a fresh code if it expires. These messages stay in the local outbox; repeatedly checking an external inbox will not find them. Sign out, then sign in again to confirm the database-backed account works.
If sign-up reports a database connection or missing-table error, finish database setup instead of enabling social login. Google, GitHub, Apple, X and Microsoft buttons need their own provider application and callback settings; enable one only after its provider guide is complete. Better Auth is the shipped default engine and does not need a paid authentication account for local email sign-in.
Choose enabled sign-in methods
The foundation includes email/password, OTP, and configurable social authentication. Better Auth owns identity and sessions, while the application composes provider configuration and transactional OTP delivery.
Enable only the social providers you have configured. Provider client secrets and the authentication secret stay on the server.
Connect identity to a workspace
Authenticated handlers resolve session state before accessing workspace records. Workspace provisioning must remain idempotent so replaying a lifecycle hook does not create duplicate ownership records.
Verify session behavior
Test sign-in, invalid or expired OTPs, single-use consumption, sign-out, and rejected anonymous access. Memory-adapter tests cover handler semantics; production database persistence and real provider callbacks need separate acceptance.
Setup and configuration
Better Auth is the default engine (AUTH_PROVIDER=better-auth); an Auth.js engine is available for teams standardizing on it. Enabled methods are declared per provider: email/password, one-time codes delivered by transactional mail, and social sign-in for Google, Apple, GitHub, Microsoft, and Twitter.
Each social provider switches on with its AUTH_<PROVIDER>_ENABLED flag plus the matching client id and secret. The auth secret, provider secrets, and session signing keys are server-only configuration.
AUTH_PROVIDER=better-auth
AUTH_SECRET=generate-a-long-random-value
AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…Implementation workflow
The /auth surface renders the configured methods; the server composes the engine in auth-runtime and resolves the session at every protected boundary. A successful first sign-in provisions the member's personal workspace idempotently — replayed lifecycle hooks must never create a second ownership record.
Account security lives under /settings/security: password change, active sessions, and passkeys where the build enables them. Keep session restore, sign-out revocation, and cross-workspace denial as server-enforced behavior, not interface state.
Verification and troubleshooting
Exercise sign-in, invalid and expired OTP codes, single-use consumption, passkey ceremonies on HTTPS origins, social callback returns, sign-out, and anonymous denial. Register every provider redirect URI before testing callbacks, and verify that a revoked session cannot keep performing protected work.