Authentication Module Overview

The Relay authentication stack issues and validates JWTs, manages developer API keys, and protects production-only operations. Reference this page whenever workflow demos or quick starts point to the auth module for deeper detail.

Key Responsibilities

• Issue, rotate, and revoke JSON Web Tokens (JWTs) for end-user and service access through SecureJWTAuth
• Manage developer and automation API keys with single-view raw key exposure, masking on read, and optional local filesystem persistence
• Gate admin-only operations (debug toggles, health diagnostics, migration utilities) through environment-aware safety checks
• Provide FastAPI dependency helpers that enforce tenant isolation, role permissions, and production safeguards

Core Components

Component	Description	Location
SecureJWTAuth	Issues and validates JWTs, tracks session lifecycles, and integrates with the session store for revocation.	src/security/jwt_auth.py
SessionStore	Cache-backed registry that records active JWT sessions and powers audit visibility and mass revocation.	src/services/session_store.py
APIKeyManager	Handles API key creation, rotation, verification, and masking, enforcing the "raw key returned once" contract.	src/services/auth_service.py
ProductionSafetyValidator	Guards production environments against debug-only features (demo mocks, mock signing).	src/security/production_safety_validator.py
Auth dependencies	FastAPI dependency providers that enforce authentication/authorization on routes.	src/auth/decorators.py, src/auth/dependencies.py

Operational Checklist

Before deploying the authentication module in a new environment:

1. Environment variables
   • JWT_SIGNING_KEY: Base64 encoded signing secret (required)
   • JWT_AUDIENCE / JWT_ISSUER: Populate with tenant-specific values
   • SESSION_STORE_BACKEND: redis (production) or memory (development)
   • ADMIN_PASSWORD: Explicit admin bootstrap password (no implicit derivation)
2. Session store
   • Provision Redis or configure the in-memory fallback for local usage
   • Confirm the session eviction TTLs in settings.py align with your revocation SLA
3. API keys
   • Use python3 scripts/maintenance/generate_admin_key.py (optional) to mint a bootstrap key in staging
   • Audit the API key list regularly with the /auth/api-keys endpoints
4. Monitoring
   • Enable the authentication metrics exporter (AUTH_SIGNING_METRICS_ENABLED)
   • Forward auth_* metrics to your observability stack for visibility into login success, failure, and revocation rates

Related Documentation

• JWT Session Management
• Troubleshooting Playbook
• Platform Overview