t1k:web:backend:better-auth
| Field | Value |
|---|---|
| Module | backend |
| Version | 1.13.12 |
| Effort | medium |
| Tools | — |
Keywords: 2FA, auth, authentication, better-auth, JWT, OAuth, passkeys, RBAC, sessions
How to invoke
Section titled “How to invoke”/t1k:web:backend:better-auth[auth-method or feature]Better Auth Skill
Section titled “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.
Studio internal/admin apps: studio-auth first
Section titled “Studio internal/admin apps: studio-auth first”For an internal or admin studio app (e.g. a new
The1Studio/WebAppTemplate-based app), sign-in goes through studio-auth
(docs/studio-auth.md in theonekit-core), not a Better Auth social provider, a Google OAuth client, a new Cloudflare
Access app or in-app sign-up. Google is never the default identity here: a Google sign-in or Google API need goes
through the order in docs/studio-auth.md § “Google identity and Google APIs” (reuse the studio Google OAuth client
from the vault first; a new client is the last resort, only after the studio-auth exception). studio-auth’s browser login is unverified (its Status line);
say so in the plan rather than assume it works. See t1k-web-devops-core § “Auth — studio-auth first”. For an
EXISTING Access-gated app, legacy: t1k-web-devops-selfhost-cloudflare/references/cloudflare-access.md § 6 (verify the
Cf-Access-Jwt-Assertion header). Starter wiring:
t1k-web-devops-deploy/references/platforms/cloudflare.md § “Studio starter: WebAppTemplate”.
Reach for Better Auth instead when the app has genuine public/consumer sign-up: end users who are not studio
team members and so cannot be gated by studio org membership. Only there do the google and github providers
below belong.
When to Use
Section titled “When to Use”- Implementing auth in TypeScript/JavaScript applications
- Adding email/password or social OAuth authentication
- Setting up 2FA, passkeys, magic links, advanced auth features
- Building multi-tenant apps with organization support
- Managing sessions and user lifecycle
- Working with any framework (Next.js, Nuxt, SvelteKit, Remix, Astro, Hono, Express, etc.)
Quick Start
Section titled “Quick Start”Installation
Section titled “Installation”bun install better-auth# or: bun add better-authEnvironment Setup
Section titled “Environment Setup”Create .env:
BETTER_AUTH_SECRET=<generated-secret-32-chars-min>BETTER_AUTH_URL=http://localhost:3000Basic Server Setup
Section titled “Basic Server Setup”Create auth.ts (root, lib/, utils/, or under src/app/server/):
import { betterAuth } from "better-auth";
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
Section titled “Database Schema”bunx auth@latest generate # Generate schema/migrationsbunx auth@latest migrate # Apply migrations (Kysely only)Mount API Handler
Section titled “Mount API Handler”Next.js App Router:
import { auth } from "@/lib/auth";import { toNextJsHandler } from "better-auth/next-js";
export const { POST, GET } = toNextJsHandler(auth);Other frameworks: See references/email-password-auth.md#framework-setup
Client Setup
Section titled “Client Setup”Create auth-client.ts:
import { createAuthClient } from "better-auth/react";
export const authClient = createAuthClient({ baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || "http://localhost:3000"});Basic Usage
Section titled “Basic Usage”// Sign upawait authClient.signUp.email({ email: "user@example.com", password: "secure123", name: "John Doe"});
// Sign inawait authClient.signIn.email({ email: "user@example.com", password: "secure123"});
// OAuthawait authClient.signIn.social({ provider: "github" });
// Sessionconst { data: session } = authClient.useSession(); // React/Vue/Svelteconst { data: session } = await authClient.getSession(); // Vanilla JSFeature Selection Matrix
Section titled “Feature Selection Matrix”| Feature | Plugin Required | Use Case | Reference |
|---|---|---|---|
| Email/Password | No (built-in) | Basic auth | email-password-auth.md (./references/email-password-auth.md) |
| OAuth (GitHub, Google, etc.) | No (built-in) | Social login | oauth-providers.md (./references/oauth-providers.md) |
| Email Verification | No (built-in) | Verify email addresses | email-password-auth.md (./references/email-password-auth.md#email-verification) |
| Password Reset | No (built-in) | Forgot password flow | email-password-auth.md (./references/email-password-auth.md#password-reset) |
| Two-Factor Auth (2FA/TOTP) | Yes (twoFactor) | Enhanced security | advanced-features.md (./references/advanced-features.md#two-factor-authentication) |
| Passkeys/WebAuthn | Yes (passkey) | Passwordless auth | advanced-features.md (./references/advanced-features.md#passkeys-webauthn) |
| Magic Link | Yes (magicLink) | Email-based login | advanced-features.md (./references/advanced-features.md#magic-link) |
| Username Auth | Yes (username) | Username login | email-password-auth.md (./references/email-password-auth.md#username-authentication) |
| Organizations/Multi-tenant | Yes (organization) | Team/org features | advanced-features.md (./references/advanced-features.md#organizations) |
| Rate Limiting | No (built-in) | Prevent abuse | advanced-features.md (./references/advanced-features.md#rate-limiting) |
| Session Management | No (built-in) | User sessions | advanced-features.md (./references/advanced-features.md#session-management) |
Auth Method Selection Guide
Section titled “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
Section titled “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
Section titled “Implementation Checklist”- Install
better-authpackage - Set environment variables (SECRET, URL)
- Create auth server instance with database config
- Run schema migration (
bunx auth@latest 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
Section titled “Reference Documentation”Core Authentication
Section titled “Core Authentication”- Email/Password Authentication (
./references/email-password-auth.md) - Email/password setup, verification, password reset, username auth - OAuth Providers (
./references/oauth-providers.md) - Social login setup, provider configuration, token management - Database Integration (
./references/database-integration.md) - Database adapters, schema setup, migrations
Advanced Features
Section titled “Advanced Features”- Advanced Features (
./references/advanced-features.md) - 2FA/MFA, passkeys, magic links, organizations, rate limiting, session management
Scripts
Section titled “Scripts”scripts/better_auth_init.py- Initialize Better Auth configuration with interactive setup
Resources
Section titled “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/introduction
Hard rules
Section titled “Hard rules”- JWT secret in
process.envwithout rotation = perpetual blast radius — rotate per-environment, separate per-instance closures, never log the secret even onLEVEL=trace. - OAuth callback URLs MUST include the trailing slash if your provider expects it — silent 401s for half your users on production.