Example Docs

Concepts

Understanding these core concepts will help you get the most out of Better Auth and build robust authentication systems.

Architecture Overview

Better Auth follows a layered architecture:

┌──────────────────────────────────────┐
│          Client SDK (React, etc.)    │
├──────────────────────────────────────┤
│            API Handler               │
├──────────────────────────────────────┤
│          Auth Core Engine            │
├──────────────┬───────────────────────┤
│   Plugins    │   Database Adapter    │
└──────────────┴───────────────────────┘
  1. Client SDK — Framework-specific hooks and utilities for the frontend
  2. API Handler — HTTP endpoints that handle auth requests (sign in, sign up, etc.)
  3. Auth Core Engine — The central logic that orchestrates authentication flows
  4. Plugins — Optional modules that extend functionality (2FA, passkeys, etc.)
  5. Database Adapter — Abstraction layer for your database of choice

Key Concepts

Auth Instance

The auth instance is the central object that configures your authentication system. It's created with betterAuth() and holds all configuration, plugins, and database connections.

Sessions

Sessions represent an authenticated user's state. Better Auth uses secure, encrypted cookies to manage sessions automatically. Sessions can be configured with custom expiry times, refresh tokens, and more.

Accounts

An account links a user to an authentication method. A single user can have multiple accounts (e.g., email + Google + GitHub), all linked to the same user profile.

Verification

Verification tokens are used for email verification, password resets, and other flows that require proving ownership of an email address.

Deep Dives