Quick Start

Get your authentication system up and running in 5 minutes.

Option 1: Automated Setup (Recommended)

The AuthCore CLI bootstraps a working authentication backend and optional API routes into your project. Choose between complete source ownership or standard package imports.

Main Template Mode

AuthCore becomes your primary source code with complete ownership.

Standard Mode

Import components from the package.

What the CLI does for you (high level):

Copies prisma/schema.prisma and optional migrations; runs prisma migrate when --migrate is provided.
Creates a .env.example with required env vars and prints the next steps.
Installs starter seed data and provides a seed script you can run with npx prisma db seed.
If --with-api is used, the CLI will copy router templates depending on the value: pages, app, or both. The copied handlers include auth flows, 2FA, organizations, tenant security, and session helpers. When using the App Router you may still need to adjust exports or move files into app/api depending on your project layout.

Key Flags

--migrate — runs Prisma migrations after copying the schema.
--with-api=pages|app|both — copies router templates into pages/api, app/api, or both respectively.
--yes — accepts prompts automatically when you know there are no conflicts.

Creates & Updates

prisma/schema.prisma and a seed script
.env.example plus generated secrets
Optional API handlers for auth, organizations, tenant policy, and session switching

After running the CLI:

Run npm install to ensure peers are installed (@prisma/client, next-auth).
Generate Prisma client: npx prisma generate.
Seed demo data (if included): npx prisma db seed.
Sync theme/styles: npx authcore styles:install to inject the CSS import into your app entry if you want the AuthCore theme.

That's it! Your app is ready. Run npm run dev and visit the 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.

Next Steps

Explore Components →

Learn about all available UI components

Security Features →

Set up lockout policies and restrictions

Organizations →

Add multi-tenant organization support

Configuration →

Customize AuthCore for your needs