Admin Dashboard | Client Guides

The admin dashboard provides system-wide statistics and user management capabilities. Only designated admin users can access this protected area.

ℹ️

Prerequisites

Admin access configured in .env.local
Database connection established
Understanding of email-based access control

Overview

The admin system provides:

Statistics Dashboard: View total users, revenue, and plan distribution
Admin Management: Add or remove admin access for team members
Email-Based Access: Simple and secure access control using email addresses
Bootstrap Admin: Set initial admin via environment variable

Setting Up Admin Access

Configure Bootstrap Admin Email

The first admin (bootstrap admin) is set via environment variable. This admin can then grant access to other team members.

.env.local

1# Admin Access
2ADMIN_EMAIL="your-email@example.com"

💡

Bootstrap Admin

The email in ADMIN_EMAIL will automatically have admin access and will be added to the database on first login.

Access the Admin Dashboard

Once configured, log in with your admin email and navigate to:

text

1/app/admin/dashboard

You'll see system-wide statistics including:

Total user count
Total revenue (calculated from active subscriptions)
Plan distribution breakdown (Free, Pro, Enterprise)

Add Additional Admins

From the Admin Dashboard, click on "Admin Management" to add more admin users:

Navigate to /app/admin/settings
Enter the email address of the person you want to grant admin access
Click "Add Admin"
The email will be added to the database immediately

⚠️

Security Note

Only add trusted team members as admins. Admin users can view all system data and manage other admins.

How Admin Access Works

Two-Layer Access Control

The system checks admin status using two layers:

Environment Variable (Bootstrap): Checks if email matches ADMIN_EMAIL
Database Records: Checks if email exists in the Admin table

Admin Utility Functions

The codebase provides utility functions in src/lib/admin.ts:

src/lib/admin.ts

1// Check if an email has admin access
2export async function isAdmin(email: string): Promise<boolean>
3 
4// Get all admin emails from database
5export async function getAdminEmails(): Promise<string[]>
6 
7// Validate email format
8export function isValidEmail(email: string): boolean

Database Schema

prisma/schema.prisma

1model Admin {
2  id        String   @id @default(cuid())
3  email     String   @unique
4  addedAt   DateTime @default(now())
5  addedBy   String?
6 
7  @@index([email])
8}

Admin API Routes

Available Endpoints

Admin-only API routes are located in src/app/api/admin/:

GET /api/admin/stats

Retrieves system-wide statistics (users, revenue, plan breakdown)

typescript

1const response = await fetch('/api/admin/stats');
2const stats = await response.json();
3// { totalUsers, totalRevenue, planBreakdown }

GET /api/admin/admins

Lists all admin email addresses

typescript

1const response = await fetch('/api/admin/admins');
2const { admins } = await response.json();
3// admins: string[]

POST /api/admin/admins

Add a new admin email

typescript

1const response = await fetch('/api/admin/admins', {
2  method: 'POST',
3  headers: { 'Content-Type': 'application/json' },
4  body: JSON.stringify({ email: 'newadmin@example.com' })
5});

DELETE /api/admin/admins

Remove an admin email

typescript

1const response = await fetch('/api/admin/admins', {
2  method: 'DELETE',
3  headers: { 'Content-Type': 'application/json' },
4  body: JSON.stringify({ email: 'oldadmin@example.com' })
5});

ℹ️

Permission Checks

All admin API routes verify that the requesting user has admin access before processing the request. Unauthorized requests receive a 403 Forbidden response.

Troubleshooting

Can't Access Admin Dashboard

Verify your email matches the ADMIN_EMAIL in .env.local
Ensure you're logged in with the admin email account
Check that the database connection is working
Restart the dev server after changing environment variables

Admin Added But Can't Access

Email addresses are case-insensitive and trimmed automatically
Admin must log in with the exact email that was added
Check the database Admin table to verify the email exists

Statistics Not Showing

Verify the database has subscription data
Check browser console for API errors
Ensure /api/admin/stats endpoint is accessible

Customization

Add Custom Statistics

Extend the stats calculation in src/lib/stats.ts:

src/lib/stats.ts

1export async function getAdminStats() {
2  // Add your custom metrics here
3  const customMetric = await prisma.yourModel.count();
4 
5  return {
6    totalUsers,
7    totalRevenue,
8    planBreakdown,
9    customMetric, // Add your metric
10  };
11}

Customize Dashboard Components

Admin UI components are located in src/components/admin/:

StatCard.tsx - Statistic display cards
AdminManagement.tsx - Admin email management interface

Related Guides

Billing Setup

Configure Stripe and LemonSqueezy payment providers for your SaaS

User Management

Learn how to manage users, sessions, and authentication in your SaaS application

Database Schema

Understand the database structure and relationships in your SaaS application

💡

Next Steps

Now that you understand the admin system, you might want to:

Learn about Billing Setup to understand revenue tracking
Explore User Management for user operations
Review Database Schema for data structure

Setting Up Admin Access

Configure Bootstrap Admin Email

The first admin (bootstrap admin) is set via environment variable. This admin can then grant access to other team members.

.env.local

1# Admin Access
2ADMIN_EMAIL="your-email@example.com"

💡

Bootstrap Admin

The email in ADMIN_EMAIL will automatically have admin access and will be added to the database on first login.

Access the Admin Dashboard

Once configured, log in with your admin email and navigate to:

text

1/app/admin/dashboard

You'll see system-wide statistics including:

Total user count
Total revenue (calculated from active subscriptions)
Plan distribution breakdown (Free, Pro, Enterprise)

Add Additional Admins

From the Admin Dashboard, click on "Admin Management" to add more admin users:

Navigate to /app/admin/settings
Enter the email address of the person you want to grant admin access
Click "Add Admin"
The email will be added to the database immediately

⚠️

Security Note

Only add trusted team members as admins. Admin users can view all system data and manage other admins.

How Admin Access Works

Two-Layer Access Control

The system checks admin status using two layers:

Environment Variable (Bootstrap): Checks if email matches ADMIN_EMAIL
Database Records: Checks if email exists in the Admin table

Admin Utility Functions

The codebase provides utility functions in src/lib/admin.ts:

src/lib/admin.ts

1// Check if an email has admin access
2export async function isAdmin(email: string): Promise<boolean>
3 
4// Get all admin emails from database
5export async function getAdminEmails(): Promise<string[]>
6 
7// Validate email format
8export function isValidEmail(email: string): boolean

Database Schema

prisma/schema.prisma

1model Admin {
2  id        String   @id @default(cuid())
3  email     String   @unique
4  addedAt   DateTime @default(now())
5  addedBy   String?
6 
7  @@index([email])
8}

Admin API Routes

Available Endpoints

Admin-only API routes are located in src/app/api/admin/:

GET /api/admin/stats

Retrieves system-wide statistics (users, revenue, plan breakdown)

typescript

1const response = await fetch('/api/admin/stats');
2const stats = await response.json();
3// { totalUsers, totalRevenue, planBreakdown }

GET /api/admin/admins

Lists all admin email addresses

typescript

1const response = await fetch('/api/admin/admins');
2const { admins } = await response.json();
3// admins: string[]

POST /api/admin/admins

Add a new admin email

typescript

1const response = await fetch('/api/admin/admins', {
2  method: 'POST',
3  headers: { 'Content-Type': 'application/json' },
4  body: JSON.stringify({ email: 'newadmin@example.com' })
5});

DELETE /api/admin/admins

Remove an admin email

typescript

1const response = await fetch('/api/admin/admins', {
2  method: 'DELETE',
3  headers: { 'Content-Type': 'application/json' },
4  body: JSON.stringify({ email: 'oldadmin@example.com' })
5});

ℹ️

Permission Checks

All admin API routes verify that the requesting user has admin access before processing the request. Unauthorized requests receive a 403 Forbidden response.

Troubleshooting

Can't Access Admin Dashboard

Verify your email matches the ADMIN_EMAIL in .env.local
Ensure you're logged in with the admin email account
Check that the database connection is working
Restart the dev server after changing environment variables

Admin Added But Can't Access

Email addresses are case-insensitive and trimmed automatically
Admin must log in with the exact email that was added
Check the database Admin table to verify the email exists

Statistics Not Showing

Verify the database has subscription data
Check browser console for API errors
Ensure /api/admin/stats endpoint is accessible

Customization

Add Custom Statistics

Extend the stats calculation in src/lib/stats.ts:

src/lib/stats.ts

1export async function getAdminStats() {
2  // Add your custom metrics here
3  const customMetric = await prisma.yourModel.count();
4 
5  return {
6    totalUsers,
7    totalRevenue,
8    planBreakdown,
9    customMetric, // Add your metric
10  };
11}

Customize Dashboard Components

Admin UI components are located in src/components/admin/:

StatCard.tsx - Statistic display cards
AdminManagement.tsx - Admin email management interface