campus.audit: API Key Security Implementation

[ngjunsiang]

Overview

Implement comprehensive API key security for the Campus Audit Service to replace current HTTP Basic/Bearer authentication with a dedicated API key system that provides granular access control, auditability, and rate limiting.

Background

The audit trace API currently uses HTTP Basic/Bearer authentication but lacks dedicated API key management. While the PRD mentions that API keys should be required for trace endpoints, there's no actual API key validation system in place.

Design Decision: Standalone Service

campus.audit is a standalone service with its own authentication system:

• Only uses API key authentication (no users, no clients)
• Users/clients are in campus.auth service
• Only admins can create audit API keys
• No actor tracking needed (no user/client concept in audit service)

Goals

• Replace HTTP Basic/Bearer auth with dedicated API key system
• Provide granular access control via scopes
• Enable API key lifecycle management (create, revoke, expire)
• Implement per-key rate limiting
• Full audit trail for key usage (what, when, which key - no actor)
• Secure key storage (hashes only, never plaintext)

Subissues

This issue is broken down into 7 subissues:

✅ Completed

• Issue Issue 538.1: API Key Model Implementation #539 - API Key Model Implementation ✅
• Issue Issue 538.2: API Key Hashing and Validation #540 - API Key Hashing and Validation ✅
• Issue Issue 538.3: API Key Management Endpoints #541 - API Key Management Endpoints ✅

🔄 In Progress

• Issue Issue 538.4: API Key Authentication Middleware #542 - API Key Authentication Middleware ✅

📋 Deferred to Future Iterations

• Issue Issue 538.5: APIKey Model Validation and Helper Methods #566 - APIKey Model Validation and Helper Methods 📋

  • Implement is_expired(), is_revoked(), has_scope() methods
  • Add model validation for updates

• Issue Issue 538.6: Audit Trail Logging for API Key Lifecycle Events #567 - Audit Trail Logging for API Key Lifecycle Events 📋

  • Log all CRUD operations to traces table
  • Capture what, when, which key (no actor - admin-only service)
  • Resolve TODO at campus/audit/resources/apikeys.py:226

• Issue Issue 538.7: Plain Text Content Negotiation for Audit API #568 - Plain Text Content Negotiation for Audit API 📋

  • Support text/plain Accept header for human-readable responses
  • Define plain text formats for all endpoints

Design Decisions

• APIKey inherits from Model - Leverages existing id and created_at fields
• Owner field instead of created_by - Allows key reassignment between users (no actor tracking needed)
• revoked_at timestamp - More useful than boolean, tracks when key was revoked
• SHA-256 hashing - Secure, fast, constant-time comparison
• Scope-based permissions - Fine-grained access control (traces:read, metrics:read, etc.)
• Per-key rate limits - Prevent abuse while allowing different tiers
• No actor tracking - Standalone service with no users/clients (admin-only key creation)

Migration Path

Phase 1: Core API key system (model, validation, middleware) ✅
Phase 2: Management endpoints and admin UI ✅
Phase 3: Rate limiting and advanced security features (future)
Phase 4: Migration of existing clients to API keys (future)

Related

• PRD: campus/audit/docs/campus-trace-api-prd-v3.md §5.1 (Authentication)
• Current auth: campus/campus/auth/middleware/__init__.py
• Audit service: campus/campus/audit/