infoscreen/AUTH_QUICKREF.md

Authentication Quick Reference

For Backend Developers

Protecting a Route

from flask import Blueprint
from server.permissions import require_role, admin_or_higher, editor_or_higher

my_bp = Blueprint("myroute", __name__, url_prefix="/api/myroute")

# Specific role(s)
@my_bp.route("/admin")
@require_role('admin', 'superadmin')
def admin_only():
    return {"message": "Admin only"}

# Convenience decorators
@my_bp.route("/settings")
@admin_or_higher
def settings():
    return {"message": "Admin or superadmin"}

@my_bp.route("/create", methods=["POST"])
@editor_or_higher
def create():
    return {"message": "Editor, admin, or superadmin"}

Getting Current User in Route

from flask import session

@my_bp.route("/profile")
@require_auth
def profile():
    user_id = session.get('user_id')
    username = session.get('username')
    role = session.get('role')
    return {
        "user_id": user_id,
        "username": username,
        "role": role
    }

For Frontend Developers

Using the Auth Hook

import { useAuth } from './useAuth';

function MyComponent() {
  const { user, isAuthenticated, login, logout, loading } = useAuth();
  
  if (loading) return <div>Loading...</div>;
  
  if (!isAuthenticated) {
    return <button onClick={() => login('user', 'pass')}>Login</button>;
  }
  
  return (
    <div>
      <p>Welcome {user?.username}</p>
      <p>Role: {user?.role}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

Conditional Rendering

import { useCurrentUser } from './useAuth';
import { isAdminOrHigher, isEditorOrHigher } from './apiAuth';

function Navigation() {
  const user = useCurrentUser();
  
  return (
    <nav>
      <a href="/">Home</a>
      
      {/* Show for all authenticated users */}
      {user && <a href="/events">Events</a>}
      
      {/* Show for editor+ */}
      {isEditorOrHigher(user) && (
        <a href="/events/new">Create Event</a>
      )}
      
      {/* Show for admin+ */}
      {isAdminOrHigher(user) && (
        <a href="/admin">Admin Panel</a>
      )}
    </nav>
  );
}

Making Authenticated API Calls

// Always include credentials for session cookies
const response = await fetch('/api/protected-route', {
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
  },
  // ... other options
});

Role Hierarchy

superadmin > admin > editor > user

Role	Can Do
user	View events
editor	user + CRUD events/media
admin	editor + manage users/groups/settings
superadmin	admin + manage superadmins + system config

Environment Variables

# Required for sessions
FLASK_SECRET_KEY=your_secret_key_here

# Required for superadmin creation
DEFAULT_SUPERADMIN_USERNAME=superadmin
DEFAULT_SUPERADMIN_PASSWORD=your_password_here

Generate a secret key:

python -c 'import secrets; print(secrets.token_hex(32))'

Testing Endpoints

# Login
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"superadmin","password":"your_password"}' \
  -c cookies.txt

# Check current user
curl http://localhost:8000/api/auth/me -b cookies.txt

# Check auth status (lightweight)
curl http://localhost:8000/api/auth/check -b cookies.txt

# Logout
curl -X POST http://localhost:8000/api/auth/logout -b cookies.txt

# Test protected route
curl http://localhost:8000/api/protected -b cookies.txt

Common Patterns

Backend: Optional Auth

from flask import session

@my_bp.route("/public-with-extras")
def public_route():
    user_id = session.get('user_id')
    
    if user_id:
        # Show extra content for authenticated users
        return {"data": "...", "extras": "..."}
    else:
        # Public content only
        return {"data": "..."}

Frontend: Redirect After Login

const { login } = useAuth();

const handleLogin = async (username: string, password: string) => {
  try {
    await login(username, password);
    window.location.href = '/dashboard';
  } catch (err) {
    console.error('Login failed:', err);
  }
};

Frontend: Protected Route Component

import { useAuth } from './useAuth';
import { Navigate } from 'react-router-dom';

function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { isAuthenticated, loading } = useAuth();
  
  if (loading) return <div>Loading...</div>;
  
  if (!isAuthenticated) {
    return <Navigate to="/login" />;
  }
  
  return <>{children}</>;
}

// Usage in routes:
<Route path="/admin" element={
  <ProtectedRoute>
    <AdminPanel />
  </ProtectedRoute>
} />

Troubleshooting

"Authentication required" on /api/auth/me

✅ Normal - User is not logged in. This is expected behavior.

Session not persisting across requests

• Check credentials: 'include' in fetch calls
• Verify FLASK_SECRET_KEY is set
• Check browser cookies are enabled

403 Forbidden on decorated route

• Verify user is logged in
• Check user role matches required role
• Inspect response for required_roles and your_role

Files Reference

File	Purpose
server/routes/auth.py	Auth endpoints (login, logout, /me)
server/permissions.py	Permission decorators
dashboard/src/apiAuth.ts	Frontend API client
dashboard/src/useAuth.tsx	React context/hooks
models/models.py	User model and UserRole enum

Full Documentation

See AUTH_SYSTEM.md for complete documentation including:

• Architecture details
• Security considerations
• API reference
• Testing guide
• Production checklist