Enterprise Authentication Service — FastAPI v3

A standalone identity and access management backend for web, mobile, SaaS and internal enterprise applications. The project is designed as a production-oriented modular monolith that can later be extracted into a dedicated identity microservice.

What is included

• Secure user registration and strict email validation
• Email verification with expiring, one-time, hashed tokens
• JSON login and OAuth2-compatible password-token endpoint
• Argon2id password hashing and configurable password policy
• Failed-login counters, temporary account lockout and administrator unlock
• Short-lived JWT access tokens
• Rotating refresh-token sessions with family-based reuse detection
• Current-device, all-device and individual-session revocation
• Password recovery, password change and global session invalidation
• Verified email-address change workflow
• TOTP authenticator-app MFA with encrypted secrets
• One-time MFA backup codes
• Multi-tenant organizations, memberships and invitations
• Global RBAC with roles, permissions and user-role assignment
• Organization-scoped owner, administrator and member roles
• Scoped API keys stored only as hashes, with rotation and revocation
• SMTP email delivery with safe development logging fallback
• Redis-backed rate limiting with in-memory fallback
• User administration, soft deletion and security controls
• Structured audit logs with actor, IP address, user agent and request ID
• Standardized validation and HTTP error envelopes
• PostgreSQL and SQLite support
• Alembic migrations, Docker Compose, health checks and CI
• OpenAPI JSON, Swagger, ReDoc and Postman collection
• Automated end-to-end security lifecycle tests

Contract size

• 55 API operations
• 42 API paths
• 45 OpenAPI schemas
• 15 database tables

See docs/API_ENDPOINTS.md for the complete endpoint catalogue.

Architecture

Web / Mobile / SaaS / Internal Services
                 │
                 ▼
        FastAPI REST Gateway
                 │
   ┌─────────────┼──────────────────┐
   │             │                  │
Authentication  RBAC & Tenancy   API Keys
   │             │                  │
   ├─ JWT        ├─ Roles           ├─ Hash-only storage
   ├─ Refresh    ├─ Permissions     ├─ Scope intersection
   ├─ MFA        ├─ Organizations   └─ Rotation/revocation
   └─ Recovery   └─ Invitations
                 │
       PostgreSQL / SQLite
                 │
       Redis rate limiting
                 │
          SMTP provider

Quick start with Docker

Expand-Archive enterprise-auth-module-v3.zip
cd enterprise-auth-module-v3
Copy-Item .env.example .env

Change SECRET_KEY, ENCRYPTION_SECRET and database credentials inside .env, then run:

docker compose up --build

Seed roles, permissions and demonstration accounts:

docker compose exec api python -m scripts.seed

Open:

• Swagger: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health: http://localhost:8000/health/ready

Local development without Docker

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

For local SQLite development, set this value in .env:

DATABASE_URL=sqlite:///./auth_service.db
REDIS_URL=

Then run:

alembic upgrade head
python -m scripts.seed
uvicorn app.main:app --reload

Demonstration accounts

All demonstration users use Password@123.

Role	Email
Super administrator	admin@auth.example.com
Security auditor	auditor@auth.example.com

Change all demonstration credentials before any shared or deployed environment.

Core lifecycle

Register
   ↓
Verify email
   ↓
Login ── MFA enabled? ── Yes ──► Verify TOTP / backup code
   │                                  │
   └──────────── No ──────────────────┘
                     ↓
             Access + refresh tokens
                     ↓
            Rotate refresh token
                     ↓
      Reuse detected? Revoke token family

Important environment variables

Variable	Purpose
DATABASE_URL	PostgreSQL or SQLite connection URL
SECRET_KEY	JWT signing key; minimum 32 characters
ENCRYPTION_SECRET	Encrypts TOTP secrets at rest
REDIS_URL	Distributed rate-limit backend
ACCESS_TOKEN_MINUTES	Access-token lifetime
REFRESH_TOKEN_DAYS	Refresh-session lifetime
MAX_FAILED_LOGINS	Failed attempts before lockout
LOCKOUT_MINUTES	Temporary lock duration
SMTP_HOST	SMTP server; blank logs email locally
FRONTEND_URL	Base URL used in security emails
EXPOSE_DEBUG_TOKENS	Development-only token visibility

Never enable EXPOSE_DEBUG_TOKENS in production.

Running tests

pytest -q

The test suite covers registration, email verification, access and refresh tokens, token-family reuse detection, sessions, organizations, invitations, API keys, MFA, password recovery, account lockout, administrator unlock and audit logs.

Regenerating API assets

python -m scripts.export_openapi
python -m scripts.generate_postman

Production notes

This project is a strong engineering starter, not a compliance certificate. Before production use, integrate your approved email provider, secrets manager, centralized logging, metrics, alerting, database backups, penetration testing, privacy controls and organization-specific legal requirements.