routes.auth

Pre-built authentication routes for FastHTML applications

Overview

This module provides pre-built authentication routes that follow FastHTML patterns and the Answer.AI design philosophy:

• Simple by default: login_route(rt) gives you a working login page
• Progressively customizable: Override forms, handlers, or paths as needed
• No magic: All behavior is explicit and visible
• MonsterUI integration: Beautiful forms out of the box

Quick Start

from ship_kit.routes.auth import login_route, signup_route, logout_route
from fasthtml.common import *

app, rt = fast_app()

# Add all auth routes with defaults
login_route(rt)
signup_route(rt)
logout_route(rt)

Component Visualization

To visualize MonsterUI components in this notebook during development, run the setup cell below. This will create a JupyUvi server that can render components with proper MonsterUI styling.

Note: The Show function requires a running JupyUvi server. If components aren’t displaying, make sure you’ve run the setup cell and that the server is still running on port 8003.

# Setup visualization for this notebook
from fasthtml.jupyter import HTMX, JupyUvi
import uuid

# Create visualization app and server
_viz_app, _viz_rt = fast_app(hdrs=Theme.blue.headers())
_viz_server = JupyUvi(_viz_app, port=8003)

def Show(component, height='auto'):
    """Display a MonsterUI component in the notebook."""
    path = f'/show/{uuid.uuid4().hex}'
    
    @_viz_app.route(path)
    def show_component():
        return component
    
    return HTMX(path, app=_viz_app, port=8003, height=height)

# Remember to stop the server to avoid dangling thread
_viz_server.stop()

Login Route

---

source

login_route

 login_route (rt, path='/login', redirect_to='/', login_form=None,
              authenticate=None, session_key='auth', **kwargs)

*Create a login route with customizable form and authentication.

Following FastHTML patterns - pass the router instance, not the app.

Args: rt: FastHTML router instance (from fast_app()) path: Route path (default: ‘/login’) redirect_to: Where to redirect after successful login (default: ‘/’) login_form: Custom form component (callable returning FT) authenticate: Custom authentication function(email, password) -> user_dict or None session_key: Session key for auth data (default: ‘auth’) **kwargs: Additional arguments passed to form component*

	Type	Default	Details
rt			FastHTML router instance
path	str	/login
redirect_to	str	/
login_form	NoneType	None
authenticate	NoneType	None
session_key	str	auth
kwargs	VAR_KEYWORD

def default_login_form(error=None, **kwargs):
    return Card(
        H2('Login'),
        Form(
            LabelInput('Email', 
                      name='email', 
                      id='email', 
                      type='email', 
                      required=True, 
                      placeholder='you@example.com'),
            LabelInput('Password', 
                      name='password', 
                      id='password', 
                      type='password', 
                      required=True),
            Alert(error, variant='destructive') if error else None,
            Button('Sign In', type='submit', cls='w-full'),
            method='post',
            cls='space-y-4'
        ),
        P(
            "Don't have an account? ",
            A('Sign up', href='/signup', cls='text-primary hover:underline'),
            cls='text-center text-sm mt-4'
        ),
        cls='max-w-md mx-auto mt-8'
    )

# Uncomment to Visualize the default login form
#Show(default_login_form(), height='500px')

Login Examples

Basic Usage

The default login form includes: - Email and password fields with proper input types - MonsterUI styling with Card container - Error handling with Alert component - HTMX integration for seamless form submission - Link to signup page

# Simple login with all defaults
login_route(rt)

Custom Form Example

def branded_login_form(error=None, **kwargs):
    return Container(
        Card(
            Div(
                H1('Welcome Back!', cls='text-3xl font-bold'),
                P('Sign in to continue to your account', cls='text-muted-foreground'),
                cls='text-center mb-6'
            ),
            Form(
                LabelInput('Email Address',
                          name='email', 
                          type='email', 
                          required=True, 
                          placeholder='Enter your email'),
                Div(
                    LabelInput('Password',
                              name='password', 
                              type='password', 
                              required=True),
                    A('Forgot password?', href='/forgot-password', 
                      cls='text-sm text-primary hover:underline mt-1 block'),
                    cls='space-y-1'
                ),
                Alert(error, variant='destructive', cls='mb-4') if error else None,
                Button('Sign In', type='submit', cls='w-full', size='lg'),
                DividerSplit('Or'),
                P(
                    "Don't have an account? ",
                    A('Sign up', href='/signup', cls='text-primary hover:underline'),
                    cls='text-center text-sm'
                ),
                method='post',
                cls='space-y-4'
            ),
            cls='max-w-md w-full'
        ),
        cls='min-h-screen flex items-center justify-center'
    )

# Use the custom form
# login_route(rt, login_form=branded_login_form)

# Uncomment to Visualize the branded login form
#Show(branded_login_form(), height='700px')

Custom Authentication

# Example with database authentication
def db_authenticate(email, password):
    """Authenticate user against database."""
    # This is pseudocode - implement your actual database logic
    # user = db.query("SELECT * FROM users WHERE email = ?", email)
    # if user and verify_password(password, user['password_hash']):
    #     return {'id': user['id'], 'email': user['email'], 'name': user['name']}
    # return None
    pass

# login_route(rt, authenticate=db_authenticate)

Signup Route

---

source

signup_route

 signup_route (rt, path='/signup', redirect_to='/', signup_form=None,
               create_user=None, session_key='auth', **kwargs)

*Create a signup route with customizable form and user creation.

Following FastHTML patterns - pass the router instance, not the app.

Args: rt: FastHTML router instance (from fast_app()) path: Route path (default: ‘/signup’) redirect_to: Where to redirect after successful signup (default: ‘/’) signup_form: Custom form component (callable returning FT) create_user: Custom user creation function(form_data) -> user_dict or error_string session_key: Session key for auth data (default: ‘auth’) **kwargs: Additional arguments passed to form component*

	Type	Default	Details
rt			FastHTML router instance
path	str	/signup
redirect_to	str	/
signup_form	NoneType	None
create_user	NoneType	None
session_key	str	auth
kwargs	VAR_KEYWORD

The default signup form includes: - Name, email, password, and password confirmation fields - Form validation with error messages - Preserves form values on validation errors - HTMX integration for seamless submission - Link to login page for existing users

# Visualize the default signup form
def default_signup_form(error=None, values=None, **kwargs):
    values = values or {}
    return Card(
        H2('Create Account'),
        Form(
            LabelInput('Name',
                      name='name', 
                      id='name', 
                      required=True, 
                      value=values.get('name', ''),
                      placeholder='John Doe'),
            LabelInput('Email',
                      name='email', 
                      id='email', 
                      type='email', 
                      required=True,
                      value=values.get('email', ''),
                      placeholder='you@example.com'),
            LabelInput('Password',
                      name='password', 
                      id='password', 
                      type='password', 
                      required=True,
                      placeholder='At least 8 characters'),
            LabelInput('Confirm Password',
                      name='password_confirm', 
                      id='password_confirm', 
                      type='password', 
                      required=True),
            Alert(error, variant='destructive') if error else None,
            Button('Create Account', type='submit', cls='w-full'),
            method='post',
            cls='space-y-4'
        ),
        P(
            "Already have an account? ",
            A('Sign in', href='/login', cls='text-primary hover:underline'),
            cls='text-center text-sm mt-4'
        ),
        cls='max-w-md mx-auto mt-8'
    )

# Uncomment to Visualize the default signup form
#Show(default_signup_form(), height='600px')

Logout Route

---

source

logout_route

 logout_route (rt, path='/logout', redirect_to='/login',
               session_key='auth', before_logout=None)

*Create a logout route that clears the session.

Following FastHTML patterns - pass the router instance, not the app.

Args: rt: FastHTML router instance (from fast_app()) path: Route path (default: ‘/logout’) redirect_to: Where to redirect after logout (default: ‘/login’) session_key: Session key to clear (default: ‘auth’) before_logout: Optional callback function(session) called before logout*

	Type	Default	Details
rt			FastHTML router instance
path	str	/logout
redirect_to	str	/login
session_key	str	auth
before_logout	NoneType	None

Complete Example

Here’s a complete example showing how to use all the auth routes together with custom authentication:

# Example of complete auth setup
def setup_auth(rt, db):
    """Setup authentication routes with database integration."""
    
    def authenticate_user(email, password):
        """Check credentials against database."""
        user = db.get_user_by_email(email)
        if user and verify_password(password, user['password_hash']):
            return {
                'id': user['id'],
                'email': user['email'],
                'name': user['name']
            }
        return None
    
    def create_new_user(form_data):
        """Create new user in database."""
        # Validation
        if form_data['password'] != form_data['password_confirm']:
            return "Passwords don't match"
        
        if len(form_data['password']) < 8:
            return "Password must be at least 8 characters"
        
        # Check if email exists
        if db.get_user_by_email(form_data['email']):
            return "Email already registered"
        
        # Create user
        user_id = db.create_user(
            email=form_data['email'],
            name=form_data['name'],
            password_hash=hash_password(form_data['password'])
        )
        
        return {
            'id': user_id,
            'email': form_data['email'],
            'name': form_data['name']
        }
    
    # Add all routes
    login_route(rt, authenticate=authenticate_user)
    signup_route(rt, create_user=create_new_user)
    logout_route(rt)

# Usage:
# app, rt = fast_app()
# setup_auth(rt, database)

Interactive Demo

You can create a working demo using JupyUvi:

# Demo app with all auth routes
# Note: This demo uses JupyUvi to run interactively in the notebook
from fasthtml.jupyter import JupyUvi

# Create demo app
demo_app, rt = fast_app(hdrs=Theme.blue.headers())

# Simple in-memory user store for demo
demo_users = {}

def demo_authenticate(email, password):
    """Demo authentication."""
    user = demo_users.get(email)
    if user and user['password'] == password:  # Don't do this in production!
        return {'email': email, 'name': user['name']}
    return None

def demo_create_user(form_data):
    """Demo user creation."""
    if form_data['password'] != form_data['password_confirm']:
        return "Passwords don't match"
    
    if form_data['email'] in demo_users:
        return "Email already exists"
    
    demo_users[form_data['email']] = {
        'name': form_data['name'],
        'password': form_data['password']  # Don't store plain passwords in production!
    }
    
    return {'email': form_data['email'], 'name': form_data['name']}

# Add auth routes using rt pattern
login_route(rt, authenticate=demo_authenticate)
signup_route(rt, create_user=demo_create_user)
logout_route(rt)

# Add a protected home page
@rt('/')
def home(sess):
    user = sess.get('auth')
    if not user:
        return RedirectResponse('/login', status_code=303)
    
    return Container(
        Card(
            H1(f"Welcome, {user.get('name', 'User')}!"),
            P(f"You are logged in as {user['email']}"),
            Button('Logout', hx_get='/logout', hx_push_url='true'),
            cls='max-w-2xl mx-auto mt-8'
        )
    )

# Run the demo server
print("Starting demo server...")
print("\nDemo app routes:")
print("- http://localhost:8000/login - Login page")
print("- http://localhost:8000/signup - Signup page") 
print("- http://localhost:8000/logout - Logout")
print("- http://localhost:8000/ - Protected home page")
print("\nTry creating an account and logging in!")

# Start the server
server = JupyUvi(demo_app)

# Remember to stop the server when done:
server.stop()

Advanced Customization

Custom Session Management

# Use different session keys for different user types
# login_route(rt, session_key='admin_auth', path='/admin/login')
# login_route(rt, session_key='user_auth', path='/user/login')

Multi-tenant Authentication

def tenant_authenticate(email, password, tenant_id=None):
    """Authenticate within a specific tenant."""
    # Your multi-tenant logic here
    pass

# Create tenant-specific login
# login_route(rt, 
#     path='/tenant/{tenant_id}/login',
#     authenticate=lambda e, p: tenant_authenticate(e, p, req.path_params['tenant_id'])
# )

OAuth Login Form

def oauth_login_form(error=None, **kwargs):
    """Login form with OAuth options."""
    return Card(
        H2('Sign In'),
        Div(
            Button(
                UkIcon('github'), 'Continue with GitHub',
                onclick="window.location.href='/auth/github'",
                cls='w-full mb-2'
            ),
            Button(
                'Continue with Google', 
                onclick="window.location.href='/auth/google'",
                cls='w-full'
            ),
            cls='mb-4'
        ),
        DividerSplit('OR'),
        Form(
            # Regular email/password form
            LabelInput('Email',
                      name='email', 
                      type='email', 
                      required=True),
            LabelInput('Password',
                      name='password', 
                      type='password', 
                      required=True),
            Alert(error, variant='destructive') if error else None,
            Button('Sign In with Email', type='submit', cls='w-full'),
            method='post',
            cls='space-y-4'
        ),
        cls='max-w-md mx-auto mt-8'
    )

# Use OAuth-enabled form
# login_route(rt, login_form=oauth_login_form)

Testing Auth Routes

Here’s how to test the auth routes:

# Test with httpx
import httpx

def test_auth_flow(base_url='http://localhost:8000'):
    """Test the complete auth flow."""
    with httpx.Client(base_url=base_url, follow_redirects=True) as client:
        # Test signup
        response = client.post('/signup', data={
            'name': 'Test User',
            'email': 'test@example.com',
            'password': 'testpass123',
            'password_confirm': 'testpass123'
        })
        assert response.status_code == 200
        
        # Test login
        response = client.post('/login', data={
            'email': 'test@example.com',
            'password': 'testpass123'
        })
        assert response.status_code == 200
        
        # Test protected route
        response = client.get('/')
        assert 'Welcome' in response.text
        
        # Test logout
        response = client.get('/logout')
        assert response.url.path == '/login'
        
    print("All tests passed!")

# Run tests against your app
# test_auth_flow()

# Uncomment to Visualize the OAuth login form
# Show(oauth_login_form(), height='600px')

Summary

The auth routes module provides:

1. Simple defaults - Just call login_route(rt) to get started
2. Progressive customization - Override forms, handlers, or paths as needed
3. FastHTML patterns - Uses standard rt() decorator, req/sess parameters, and HTMX
4. MonsterUI integration - Beautiful forms out of the box
5. No magic - All code is explicit and understandable

The routes handle both regular and HTMX requests, include CSRF protection via POST methods, and integrate seamlessly with FastHTML’s session management.

Breaking Changes in v2.0

• Functions now take rt parameter instead of app - This follows FastHTML best practices
• Old: login_route(app)
• New: login_route(rt)