Skip to content

User Management

Learn how to manage admin users in your FastAPI boilerplate's admin panel. The boilerplate automatically creates admin users from environment variables and provides a separate authentication system (powered by CRUDAdmin) from your application users.

CRUDAdmin Authentication: For advanced authentication features and session management, see the CRUDAdmin documentation.

Initial Admin Setup

Configure Admin Credentials

Set your admin credentials in your .env file:

# Required admin credentials
ADMIN_USERNAME="admin"
ADMIN_PASSWORD="SecurePassword123!"

# Optional details
ADMIN_NAME="Administrator"
ADMIN_EMAIL="admin@yourcompany.com"

Access the Admin Panel

Start your application and access the admin panel:

# Start application
uv run fastapi dev

# Visit: http://localhost:8000/admin
# Login with your ADMIN_USERNAME and ADMIN_PASSWORD

The boilerplate automatically creates the initial admin user from your environment variables when the application starts.

Managing Admin Users

Creating Additional Admin Users

Once logged in, you can create more admin users through the admin interface:

  1. Navigate to the admin users section in the admin panel
  2. Click "Create" or "Add New"
  3. Fill in the required fields:
  4. Username (must be unique)
  5. Password (will be hashed automatically)
  6. Email (optional)

Admin User Requirements

  • Username: 3-50 characters, letters/numbers/underscores/hyphens
  • Password: Minimum 8 characters with mixed case, numbers, and symbols
  • Email: Valid email format (optional)

Updating and Removing Users

  • Update: Find the user in the admin panel and click "Edit"
  • Remove: Click "Delete" (ensure you have alternative admin access first)

Security Configuration

Environment-Specific Settings

Configure different security levels for each environment:

# Development
ADMIN_USERNAME="dev-admin"
ADMIN_PASSWORD="DevPass123!"
ENVIRONMENT="local"

# Production
ADMIN_USERNAME="prod-admin"
ADMIN_PASSWORD="VerySecurePassword123!"
ENVIRONMENT="production"
CRUD_ADMIN_TRACK_EVENTS=true
CRUD_ADMIN_TRACK_SESSIONS=true
SESSION_SECURE_COOKIES=true

Session Management

Control admin sessions with these settings:

# Session limits and timeouts
CRUD_ADMIN_MAX_SESSIONS=10          # Max concurrent sessions per user
CRUD_ADMIN_SESSION_TIMEOUT=1440     # Timeout in minutes (24 hours)
SESSION_SECURE_COOKIES=true         # HTTPS-only cookies

Enable Tracking

Monitor admin activity by enabling event tracking:

# Track admin actions and sessions
CRUD_ADMIN_TRACK_EVENTS=true        # Log all admin actions  
CRUD_ADMIN_TRACK_SESSIONS=true      # Track session lifecycle

Production Deployment

Secure Credential Management

For production, use Docker secrets or Kubernetes secrets instead of plain text:

# docker-compose.yml
services:
  web:
    secrets:
      - admin_username
      - admin_password
    environment:
      - ADMIN_USERNAME_FILE=/run/secrets/admin_username
      - ADMIN_PASSWORD_FILE=/run/secrets/admin_password

secrets:
  admin_username:
    file: ./secrets/admin_username.txt
  admin_password:
    file: ./secrets/admin_password.txt

Production Security Settings

# Production .env
ENVIRONMENT="production"
ADMIN_USERNAME="prod-admin"
ADMIN_PASSWORD="UltraSecurePassword123!"

# Enhanced security
CRUD_ADMIN_REDIS_ENABLED=true
CRUD_ADMIN_REDIS_HOST="redis.internal.company.com"
CRUD_ADMIN_REDIS_PASSWORD="secure-redis-password"
CRUD_ADMIN_REDIS_SSL=true

# Monitoring
CRUD_ADMIN_TRACK_EVENTS=true
CRUD_ADMIN_TRACK_SESSIONS=true
SESSION_SECURE_COOKIES=true
CRUD_ADMIN_MAX_SESSIONS=5
CRUD_ADMIN_SESSION_TIMEOUT=480      # 8 hours

Application User Management

Admin vs Application Users

Your boilerplate maintains two separate user systems:

  • Admin Users: Access the admin panel (stored by CRUDAdmin)
  • Application Users: Use your application (stored in your User model)

Managing Application Users

Through the admin panel, you can manage your application's users:

  1. Navigate to "Users" section (your application users)
  2. View, create, update user profiles
  3. Manage user tiers and subscriptions
  4. View user-generated content (posts)

The User model is already registered with password hashing and proper permissions.

Emergency Recovery

Lost Admin Password

If you lose admin access, update your environment variables:

# Update .env file
ADMIN_USERNAME="emergency-admin"
ADMIN_PASSWORD="EmergencyPassword123!"

# Restart application
uv run fastapi dev

Database Recovery (Advanced)

For direct database password reset:

# Generate bcrypt hash
import bcrypt
password = "NewPassword123!"
hashed = bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt())
print(hashed.decode('utf-8'))

-- Update in database
UPDATE admin_users 
SET password_hash = '<bcrypt-hash>' 
WHERE username = 'admin';

What's Next

Your admin user management is now configured with:

  • Automatic admin user creation from environment variables
  • Secure authentication separate from application users
  • Environment-specific security settings
  • Production-ready credential management
  • Emergency recovery procedures

You can now securely manage both admin users and your application users through the admin panel.