Environment Setup

Create .env:

BETTER_AUTH_SECRET=<generated-secret-32-chars-min>
BETTER_AUTH_URL=http://localhost:3000

Basic Server Setup

Create auth.ts (root, lib/, utils/, or under src/app/server/):

export const auth = betterAuth({ database: { // See references/database-integration.md }, emailAndPassword: { enabled: true, autoSignIn: true }, socialProviders: { github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, } } });

Database Schema

Mount API Handler

Next.js App Router:

export const { POST, GET } = toNextJsHandler(auth);

Other frameworks: See references/email-password-auth.md#framework-setup

Client Setup

Create auth-client.ts:

export const authClient = createAuthClient({ baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || "http://localhost:3000" });

Basic Usage

// Sign in await authClient.signIn.email({ email: "user@example.com", password: "secure123" });

// OAuth await authClient.signIn.social({ provider: "github" });

// Session const { data: session } = authClient.useSession(); // React/Vue/Svelte const { data: session } = await authClient.getSession(); // Vanilla JS

Feature Selection Matrix

Feature	Plugin Required	Use Case	Reference
Email/Password	No (built-in)	Basic auth	email-password-auth.md
OAuth (GitHub, Google, etc.)	No (built-in)	Social login	oauth-providers.md
Email Verification	No (built-in)	Verify email addresses	email-password-auth.md
Password Reset	No (built-in)	Forgot password flow	email-password-auth.md
Two-Factor Auth (2FA/TOTP)	Yes (`twoFactor`)	Enhanced security	advanced-features.md
Passkeys/WebAuthn	Yes (`passkey`)	Passwordless auth	advanced-features.md
Magic Link	Yes (`magicLink`)	Email-based login	advanced-features.md
Username Auth	Yes (`username`)	Username login	email-password-auth.md
Organizations/Multi-tenant	Yes (`organization`)	Team/org features	advanced-features.md
Rate Limiting	No (built-in)	Prevent abuse	advanced-features.md
Session Management	No (built-in)	User sessions	advanced-features.md

Auth Method Selection Guide

Choose Email/Password when:

Building standard web app with traditional auth
Need full control over user credentials
Targeting users who prefer email-based accounts

Choose OAuth when:

Want quick signup with minimal friction
Users already have social accounts
Need access to social profile data

Choose Passkeys when:

Want passwordless experience
Targeting modern browsers/devices
Security is top priority

Choose Magic Link when:

Want passwordless without WebAuthn complexity
Targeting email-first users
Need temporary access links

Combine Multiple Methods when:

Want flexibility for different user preferences
Building enterprise apps with various auth requirements
Need progressive enhancement (start simple, add more options)

Core Architecture

Better Auth uses client-server architecture:

Server (better-auth): Handles auth logic, database ops, API routes
Client (better-auth/client): Provides hooks/methods for frontend
Plugins: Extend both server/client functionality

Implementation Checklist

Reference Documentation

Core Authentication

Email/Password Authentication - Email/password setup, verification, password reset, username auth
OAuth Providers - Social login setup, provider configuration, token management
Database Integration - Database adapters, schema setup, migrations

Advanced Features

Advanced Features - 2FA/MFA, passkeys, magic links, organizations, rate limiting, session management

Scripts

scripts/better_auth_init.py - Initialize Better Auth configuration with interactive setup

Resources

Docs: https://www.better-auth.com/docs
GitHub: https://github.com/better-auth/better-auth
Plugins: https://www.better-auth.com/docs/plugins
Examples: https://www.better-auth.com/docs/examples

better-auth

Better Auth Skill

Quick Start

Installation