---

name: better-auth description: Implement authentication and authorization with Better Auth - a framework-agnostic TypeScript authentication framework. Features include email/password authentication with verification, OAuth providers (Google, GitHub, Discord, etc.), two-factor authentication (TOTP, SMS), passkeys/WebAuthn support, session management, role-based access control (RBAC), rate limiting, and database adapters. Use when adding authentication to applications, implementing OAuth flows, setting up 2FA/MFA, managing user sessions, configuring authorization rules, or building secure authentication systems for web applications. license: MIT version: 2.0.0

Better Auth Skill

Better Auth is comprehensive, framework-agnostic authentication/authorization framework for TypeScript with built-in email/password, social OAuth, and powerful plugin ecosystem for advanced features.

Quick Start

Installation

Environment Setup

Create .env:

CopyBETTER_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

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:

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

Implementation Checklist

• Install better-auth package
• Set environment variables (SECRET, URL)
• Create auth server instance with database config
• Run schema migration (npx @better-auth/cli generate)
• Mount API handler in framework
• Create client instance
• Implement sign-up/sign-in UI
• Add session management to components
• Set up protected routes/middleware
• Add plugins as needed (regenerate schema after)
• Test complete auth flow
• Configure email sending (verification/reset)
• Enable rate limiting for production
• Set up error handling

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