appointment-booking-software/API_ROUTES_AUTH.md

API Routes Authentication Overview

This document provides a comprehensive overview of all API routes and their authentication requirements.

🔓 Public Routes (No Authentication Required)

Authentication Routes

• /api/auth/challenge - Generate WebAuthn challenge
• /api/auth/login - User login (WebAuthn or passphrase)
• /api/auth/register - User registration
• /api/auth/confirm - Email confirmation
• /api/auth/resend-confirmation - Resend confirmation email

System Routes

• /api/health - Health check
• /api/health/services - Service health status
• /api/docs - API documentation
• /api/openapi.json - OpenAPI specification
• /api/env - Environment information
• /api/log - Logging endpoint

Admin Setup Routes

• /api/admin/init - Initialize first global admin
• /api/admin/exists - Check if global admin exists

🔒 Protected Routes (Authentication Required)

Protected Auth Routes (Any Authenticated User)

• /api/auth/logout - User logout
• /api/auth/refresh - Refresh authentication tokens
• /api/auth/session - Get current session info
• /api/auth/sessions - Manage user sessions
• /api/auth/sessions/[sessionId] - Manage specific session
• /api/auth/passkeys - Add additional WebAuthn keys

Global Admin Routes (GLOBAL_ADMIN Role Required)

• /api/tenants - Create and list tenants
• /api/tenants/[id] - Manage specific tenant
• /api/tenants/[id]/config - Tenant configuration
• /api/tenants/config/defaults - Default tenant configuration

Admin Routes (ADMIN Role Required)

• /api/admin/tenant - Tenant management for admins

📋 Route Categories

By Authentication Level:

1. Public: 12 routes - No authentication required
2. Protected Auth: 6 routes - Any authenticated user
3. Global Admin: 5 routes - GLOBAL_ADMIN role required

By Functionality:

• Authentication: 11 routes (5 public, 6 protected)
• Admin Management: 2 routes (2 public)
• Tenant Management: 5 routes (5 global admin)
• System/Utility: 6 routes (6 public)

🔧 Implementation Details

Authentication Flow:

1. Session Cookie: session cookie for browser-based auth
2. Bearer Token: Authorization header for API access
3. Role Checking: AuthorizationService.hasRole() for role verification

Security Features:

• JWT token verification
• Session validation
• Role-based access control (RBAC)
• Proper HTTP status codes (401 vs 403)
• Detailed logging for security events

Configuration Location:

• Main config: src/server-hooks/authHandle.ts
• Authorization service: src/lib/server/auth/authorization-service.ts
• Session service: src/lib/server/auth/session-service.ts

🚨 Security Considerations

1. Public Routes: Should be carefully reviewed for security implications
2. Protected Routes: Require valid authentication but no specific roles
3. Global Admin Routes: High privilege routes requiring GLOBAL_ADMIN role
4. Rate Limiting: Applied to all routes via rateLimitHandle
5. CORS: Properly configured for API access
6. HTTPS: Security headers enforced in production

📝 Notes

• All routes are automatically covered by the authentication middleware
• New API routes should be explicitly added to the appropriate category
• Role requirements are enforced at the middleware level
• Session management is handled automatically for authenticated routes