yourwillyourwish/docs/BETTERAUTH_QUICKSTART.md

BetterAuth Quick Reference

🚀 Quick Start (5 minutes)

1. Generate Secret

npx @better-auth/cli secret
# Output: abc123... (copy this)

2. Update .env

BETTER_AUTH_SECRET=abc123...

3. Start Dev Server

npm run dev
# Opens http://localhost:3001

4. Test Login

• Click "Sign Up" / "Sign In" button
• Enter email and password
• Should redirect to /account/webinars

📦 What's in the Box

Files Created

lib/auth.ts                      - BetterAuth server config
lib/auth-client.ts               - BetterAuth frontend client
app/api/auth/[...route]/         - Unified auth handler
app/auth/*/callback/             - OAuth callbacks (4 files)
BETTERAUTH_MIGRATION.md          - Detailed migration guide
BETTERAUTH_SETUP_GUIDE.md        - Complete setup guide

Database Tables

User       ↔ Account (OAuth links)
User       ↔ Session (Active sessions)
User       ↔ Verification (Tokens)

API Endpoints

/api/auth/sign-up/email          - Register
/api/auth/sign-in/email          - Login
/api/auth/sign-out               - Logout
/api/auth/[provider]             - OAuth start
/auth/[provider]/callback        - OAuth callback
/api/auth/get-session            - Get user

🔑 Key Features

✅ Email/Password authentication ✅ 4 OAuth providers (Google, GitHub, Facebook, Discord) ✅ Session-based auth (secure cookies) ✅ Email verification ✅ Password reset ✅ Admin-configurable providers ✅ Role-based access control

🛡️ Security

• Passwords: 8-20 chars, bcrypt hashed
• Sessions: HTTP-only, secure cookies
• OAuth: Industry-standard 2.0
• Tokens: TTL-based (email & reset)

📝 Environment Variables

Required:

DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=abc123...

Optional (set via admin setup or .env):

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
# Same for GITHUB, FACEBOOK, DISCORD

🔗 OAuth Setup (per provider)

Google

1. Go to Google Cloud Console
2. Create OAuth 2.0 Client ID
3. Add Authorized redirect URI: http://localhost:3001/auth/google/callback
4. Copy Client ID and Secret to .env

GitHub

1. Go to Settings > Developer settings > OAuth Apps
2. Create new OAuth App
3. Set Authorization callback URL: http://localhost:3001/auth/github/callback
4. Copy Client ID and Secret to .env

Facebook

1. Go to Facebook Developers
2. Create App > Select Consumer category
3. Add Facebook Login product
4. Add Valid OAuth Redirect URIs: http://localhost:3001/auth/facebook/callback
5. Copy App ID and App Secret to .env

Discord

1. Go to Discord Developer Portal
2. Create New Application
3. Add OAuth2 > Redirects: http://localhost:3001/auth/discord/callback
4. Copy Client ID and Client Secret to .env

🧪 Testing Checklist

• Register with email/password
• Login with email/password
• Check user in database
• Verify password hashing
• Test Google OAuth
• Test GitHub OAuth
• Test logout
• Check /account/webinars redirects correctly
• Check /admin redirects correctly
• Verify session persists on page reload

🐛 Common Issues

Issue	Fix
"Module not found"	Run npm install
"Database error"	Check DATABASE_URL, run npm run db:migrate
"Session not working"	Check BETTER_AUTH_SECRET is set
"OAuth not working"	Verify Client ID/Secret and redirect URI
"Role always USER"	Database migrated correctly? Check User table

📞 Support

• BetterAuth Docs: https://better-auth.com/
• GitHub Issues: https://github.com/better-auth/better-auth
• Discord: https://discord.gg/better-auth

✨ Advanced Features

Want to add later?

• Two-factor authentication (TOTP)
• Social account linking
• Custom email templates
• Rate limiting
• Activity logging
• API tokens

Check BetterAuth docs for plugins and extensions!

🎯 Production Checklist

• BETTER_AUTH_SECRET at least 32 characters
• APP_BASE_URL set to production domain
• OAuth redirect URIs updated to production domain
• SMTP configured for email (if needed)
• Database backups configured
• Rate limiting configured
• Security headers configured
• CORS configured (if API used externally)

---

Status: ✅ Ready to test Est. Setup Time: 5 minutes Database: PostgreSQL with BetterAuth schema Auth Methods: 5 (Email, Google, GitHub, Facebook, Discord)