How branavanj/api-auth works
Auth API is a FastAPI service for registration, verified-email login, mandatory MFA, session management, and account security. The main flow is registration and email verification, password login, MFA challenge verification, then access/refresh tokens; authenticated users can manage profiles and TOTP/backup codes. PostgreSQL holds user and backup-code records, while Redis holds challenges, OTP state, sessions, replay markers, and rate-limit counters. Major documented health and structured logging capabilities are included. Connections are based on excerpts, the SOURCE INDEX, and README; health and mailer internals were not fully sampled.
Main entry points: auth.py Auth routes · main.py FastAPI app · twofa.py 2FA routes · models.py User records
Components 20
API and accounts
- FastAPI app
app/main.py - Auth routes
app/routers/auth.py - Profile routes
app/routers/me.py - 2FA routes
app/routers/twofa.py - Auth dependencies
app/deps.py
Identity and MFA
- Password and tokens
app/security.py - Session lifecycle
app/sessions.py - TOTP verification
app/totp.py - Backup codes
app/backup_codes.py
State and persistence
- Challenge and OTP state
app/stores.py - Rate limiting
app/rate_limit.py - User records
app/models.py - PostgreSQL
db/init/02-schema.sql - Redis
app/redis_client.py
Operations
- Health routes
app/routers/health.py - Email delivery
app/mailer.py - Request and audit logs
app/logging_config.py - Configuration
app/config.py
Other components
- API client
- SMTP service
Connections 43
- API client → FastAPI app: sends requests
README.md - FastAPI app → Auth routes: routes to
app/main.py - FastAPI app → 2FA routes: routes to
app/main.py - FastAPI app → Profile routes: routes to
app/main.py - FastAPI app → Health routes: routes to
app/main.py - FastAPI app → Request and audit logs: installs middleware
app/main.py - FastAPI app → PostgreSQL: creates schema
app/main.py - Auth routes → User records: reads and writes
app/routers/auth.py - Auth routes → Challenge and OTP state: manages challenges
app/routers/auth.py - Auth routes → Session lifecycle: issues sessions
app/routers/auth.py - Auth routes → TOTP verification: verifies TOTP
app/routers/auth.py - Auth routes → Backup codes: consumes codes
app/routers/auth.py - Auth routes → Password and tokens: checks passwords
app/routers/auth.py - Auth routes → Rate limiting: enforces limits
app/routers/auth.py - Auth routes → Email delivery: sends codes
app/routers/auth.py - 2FA routes → User records: updates MFA
app/routers/twofa.py - 2FA routes → TOTP verification: sets and verifies
app/routers/twofa.py - 2FA routes → Backup codes: replaces codes
app/routers/twofa.py - 2FA routes → Password and tokens: checks and encrypts
app/routers/twofa.py - 2FA routes → Rate limiting: enforces limits
app/routers/twofa.py - Profile routes → Password and tokens: checks passwords
app/routers/me.py - Profile routes → User records: updates account
app/routers/me.py - Profile routes → Rate limiting: enforces limits
app/routers/me.py - Auth dependencies → Password and tokens: decodes access token
app/deps.py - Auth dependencies → User records: loads user
app/deps.py - Session lifecycle → Password and tokens: creates tokens
app/sessions.py - Session lifecycle → User records: checks user version
app/sessions.py - Auth routes → PostgreSQL: persists account data
README.md - Backup codes → User records: stores code hashes
app/backup_codes.py - Challenge and OTP state → Password and tokens: hashes codes and tokens
app/stores.py - Rate limiting → Request and audit logs: audits excesses
app/rate_limit.py - User records → PostgreSQL: maps records
app/models.py - Auth routes → Redis: uses state store
app/routers/auth.py - Session lifecycle → Redis: stores refresh state
app/sessions.py - Email delivery → SMTP service: delivers email
- Health routes → PostgreSQL: checks readiness
README.md - Health routes → Redis: checks readiness
README.md - Configuration → PostgreSQL: configures connection
- Configuration → Redis: configures connection
app/redis_client.py - Configuration → Email delivery: configures SMTP
app/mailer.py - Auth routes → Request and audit logs: emits audit events
app/routers/auth.py - 2FA routes → Request and audit logs: emits audit events
app/routers/twofa.py - Profile routes → Request and audit logs: emits audit events
app/routers/me.py