Quick Start

Get your complete authentication system up and running in 5 minutes with multi-tenant architecture, enterprise security, and production-ready UI components.

Automated Setup (Recommended)

AuthCore v3.3.1 offers three deployment modes. Choose the one that fits your project architecture:

Main Template Mode

AuthCore becomes your primary source code with complete ownership.

Full Template Mode

Copy all source code to your project for maximum customization.

Package Mode

Import components from the npm package.

Template Modes Explained

Main Template Mode: AuthCore becomes your primary source code - all components, hooks, and utilities become direct imports from your project (@/components, @/hooks, etc.). Perfect when AuthCore IS your application.
Full Template Mode: Copy all source code to your project for 100% ownership and customization. Ideal for maximum control.
Package Mode: Traditional npm package approach - import components and utilities from 'codalware-auth'.

CLI primer: Use --template-mode=main for complete source ownership, --migrate to run database migrations, and --with-api to include API route templates. Add --auth-provider=better-auth for Better-Auth instead of NextAuth.

What You Get

✅ Complete authentication system (login, register, password reset, email verification)
✅ Multi-tenant architecture with tenant isolation
✅ Organizations & teams with role-based access control
✅ Enterprise security (2FA, account lockout, bot protection)
✅ Billing & subscriptions with Stripe integration
✅ Production-ready React components and UI
✅ Database schema, migrations, and seed data
✅ Environment configuration and API routes

CLI Flags

--template-mode=main|full - Choose deployment mode
--migrate - Run database migrations automatically
--with-api - Include API route templates
--auth-provider=nextauth|better-auth - Choose auth provider
--seed-admin - Create admin user
--yes - Skip prompts and accept defaults

That's it! Your complete authentication system is ready. Run npm run dev and visit your login page.

Option 2: Manual Setup

Prefer to set things up manually? Follow these steps:

1. Create NextAuth API Route

AuthCore uses NextAuth.js for session management. Create the API route:

2. Create Login Page

Use the pre-built AuthForm component:

3. Create Protected Page

Protect routes with server-side session checks:

4. Add Middleware (Optional)

Protect multiple routes at once with middleware:

Using Next.js App Router

If you're using the App Router instead of Pages Router:

Root Layout

Login Page

Note: The API route (api/auth/[...nextauth]) still goes in the app/api directory for App Router.

Test Your Setup

1️⃣

Start Development Server

npm run dev

2️⃣

Visit Login Page

Navigate to http://localhost:3000/login

3️⃣

Use Demo Credentials

If you ran the seed script:

Email: owner@example.com
Password: password123

4️⃣

Access Protected Page

After login, you should be redirected to the dashboard

Common Issues

❌ "Invalid credentials" Error

Make sure you've run the database migrations
Verify the seed script created the demo user
Check your database with npx prisma studio

❌ Session Not Persisting

Verify NEXTAUTH_SECRET is set in .env
Check NEXTAUTH_URL matches your app URL
Clear browser cookies and try again

❌ Redirect Loop

Make sure your login page path matches the middleware config
Don't protect the login page itself with middleware

Deep Dives

Ready to go beyond the basics? Explore guides that cover the drag-and-drop logo uploader and production hardening strategies.

Handling Organization Logos

Decode Base64 payloads, upload to S3, and serve SVG fallbacks when customers skip branding.

Production Launch Checklist

Verify secrets, lock down security policies, and wire telemetry before your go-live date.