Enterprise-grade authentication. Zero compromise.
Features • Tech Stack • Architecture • Getting Started • API • Roadmap
Secure authentication infrastructure for modern applications. Built for scale, designed for developers, engineered for security.
|
Python 3.11 |
FastAPI |
PostgreSQL |
Redis |
Docker |
K8s |
Stripe |
Google OAuth |
JWT |
CI/CD |
Datadog |
Monitoring |
| Feature | Description |
|---|---|
| JWT Authentication | Secure token-based auth with configurable expiration |
| Google OAuth 2.0 | One-click social login integration |
| Stripe Payments | Subscriptions, credits, and webhook handling |
| Rate Limiting | Per-endpoint protection against abuse |
| Request Tracing | Distributed tracing with X-Request-ID |
| Security Headers | XSS, clickjacking, MIME sniffing protection |
| API Versioning | /v1/* routes with backward compatibility |
| Health Probes | Kubernetes-ready liveness & readiness checks |
| Graceful Shutdown | Zero-downtime deployments |
| Secrets Validation | Startup validation with severity levels |
flowchart TB
subgraph Clients["👥 Clients"]
WEB["🌐 Web App"]
MOB["📱 Mobile App"]
SVC["⚙️ Services"]
end
subgraph Gateway["🛡️ API Gateway"]
LB["Load Balancer"]
RL["Rate Limiter"]
end
subgraph Auth["🔐 Auth Service"]
API["FastAPI"]
MW["Middleware Stack"]
BL["Business Logic"]
end
subgraph Data["💾 Data Layer"]
PG[("PostgreSQL")]
RD[("Redis Cache")]
end
subgraph External["🌍 External"]
GOOGLE["Google OAuth"]
STRIPE["Stripe API"]
EMAIL["SendGrid"]
end
WEB & MOB & SVC --> LB
LB --> RL --> API
API --> MW --> BL
BL --> PG & RD
BL <--> GOOGLE & STRIPE & EMAIL
style Auth fill:#1a1a2e,stroke:#7C4DFF,stroke-width:2px
style Data fill:#1a1a2e,stroke:#00E676,stroke-width:2px
style External fill:#1a1a2e,stroke:#FF6D00,stroke-width:2px
sequenceDiagram
participant C as Client
participant A as Auth Service
participant DB as PostgreSQL
participant G as Google OAuth
rect rgb(40, 40, 60)
Note over C,G: Login Flow
C->>A: POST /v1/auth/login
A->>DB: Verify credentials
DB-->>A: User data
A-->>C: JWT Token
end
rect rgb(40, 60, 40)
Note over C,G: OAuth Flow
C->>A: GET /v1/auth/oauth/google
A-->>C: Redirect to Google
C->>G: Authorize
G-->>C: Auth code
C->>A: Callback with code
A->>G: Exchange code
G-->>A: User info
A->>DB: Create/update user
A-->>C: JWT Token
end
flowchart LR
REQ["📥 Request"] --> RID["Request ID"]
RID --> SEC["Security Headers"]
SEC --> CORS["CORS"]
CORS --> RATE["Rate Limit"]
RATE --> TIMEOUT["Timeout"]
TIMEOUT --> AUTH["🔐 Auth"]
AUTH --> HANDLER["Handler"]
HANDLER --> RES["📤 Response"]
style REQ fill:#7C4DFF,stroke:#fff,color:#fff
style RES fill:#00E676,stroke:#fff,color:#000
style AUTH fill:#FF6D00,stroke:#fff,color:#fff
C4Deployment
title Deployment Diagram
Deployment_Node(cloud, "Cloud Platform", "GCP/AWS") {
Deployment_Node(k8s, "Kubernetes Cluster") {
Deployment_Node(ns, "auth-namespace") {
Container(api, "Auth Service", "FastAPI", "Handles authentication")
ContainerDb(pg, "PostgreSQL", "Database", "User data storage")
ContainerDb(redis, "Redis", "Cache", "Session & rate limits")
}
}
}
Deployment_Node(ext, "External Services") {
System_Ext(stripe, "Stripe", "Payments")
System_Ext(google, "Google", "OAuth")
System_Ext(sendgrid, "SendGrid", "Email")
}
Rel(api, pg, "Reads/Writes")
Rel(api, redis, "Cache")
Rel(api, stripe, "API calls")
Rel(api, google, "OAuth")
Rel(api, sendgrid, "Emails")
python >= 3.11
postgresql >= 13
docker (optional)# Clone
git clone https://github.com/AIgen-Solutions-s-r-l/fastapi-auth-service.git
cd fastapi-auth-service
# Install
poetry install
# Configure
cp .env.example .env
# Edit .env with your settings
# Migrate
alembic upgrade head
# Run
uvicorn app.main:app --reload --port 8080# Build & Run
docker build -t auth-service .
docker run -p 8080:8080 --env-file .env auth-service| Method | Endpoint | Auth | Description |
|---|---|---|---|
POST |
/v1/auth/register |
- | Create account |
POST |
/v1/auth/login |
- | Get JWT token |
POST |
/v1/auth/refresh |
JWT | Refresh token |
GET |
/v1/auth/me |
JWT ✓ | Get profile |
GET |
/v1/auth/oauth/google |
- | Google OAuth |
GET |
/v1/credits/balance |
API Key | Check balance |
POST |
/v1/webhooks/stripe |
Signature | Stripe events |
GET /healthcheck/live # Liveness probe
GET /healthcheck/ready # Readiness probe
GET /healthcheck/full # Detailed statusGET /api/versions{
"current_version": "v1",
"supported_versions": [{"version": "v1", "status": "stable"}]
}| Layer | Protection |
|---|---|
| Transport | HTTPS, TLS 1.3 |
| Headers | X-Frame-Options, CSP, HSTS |
| Auth | JWT RS256, bcrypt passwords |
| Input | Validation, sanitization |
| Rate Limit | 100 req/min (auth), 1000 req/min (api) |
| Timeout | 30s request timeout |
| Secrets | Startup validation, no defaults in prod |
| Priority | Feature | Status |
|---|---|---|
P1 |
Multi-tenant support | 🔜 Planned |
P1 |
WebAuthn/Passkeys | 🔜 Planned |
P2 |
MFA/2FA | 🔜 Planned |
P2 |
Audit logging | 🔜 Planned |
P3 |
Admin dashboard | 📋 Backlog |
P3 |
GraphQL API | 📋 Backlog |
# Fork & Clone
git clone https://github.com/YOUR_USERNAME/fastapi-auth-service.git
# Branch
git checkout -b feature/amazing-feature
# Commit
git commit -m "feat: add amazing feature"
# Push & PR
git push origin feature/amazing-featureGuidelines:
- Follow Conventional Commits
- Write tests for new features
- Update documentation as needed
MIT License
Copyright (c) 2025 AIgen Solutions s.r.l.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
Built with ❤️ by AIgen Solutions