Rate Limits

Rate limiting protects authentication endpoints from brute force attacks, credential stuffing, and email bombing. All limits are tenant-scoped (per-environment) with global safety nets to prevent cross-tenant abuse.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     Request Flow                                 │
├─────────────────────────────────────────────────────────────────┤
│  1. Preauth Middleware (500/min per IP)                         │
│     └─ Blocks random auth_flow_id hammering before DB access    │
│                                                                  │
│  2. Config/OAuth Rate Limits (token bucket)                     │
│     └─ Burst-friendly for enterprise login spikes               │
│                                                                  │
│  3. Verification Rate Limits (layered)                          │
│     ├─ Temporary lockout (10 failures → 30 min lock)            │
│     ├─ Exponential backoff (3+ failures → increasing delays)    │
│     ├─ Per-env per-email limit                                  │
│     ├─ Per-env per-IP limit                                     │
│     └─ Global email safety net                                  │
│                                                                  │
│  4. Email Rate Limits                                           │
│     ├─ Deduplication (3 min window)                             │
│     ├─ Per-env per-email hourly                                 │
│     ├─ Per-env per-IP hourly                                    │
│     └─ Global daily safety net                                  │
└─────────────────────────────────────────────────────────────────┘

Rate Limit Tiers

Tier	Multiplier	Use Case
DEFAULT	1x	Standard limits for most customers
ENTERPRISE	5x	Higher limits for enterprise customers
CUSTOM	Configurable	Per-limit overrides via rate_limit_overrides

Protected Endpoints

Preauth Middleware

Applied before any database access to block attackers hammering random auth flow IDs.

Limit	Scope	Purpose
500/min	Per IP	High threshold to block automated attacks

Config Endpoint

Limit	Scope	Purpose
120/min	Per IP (token bucket)	Burst-friendly for enterprise SSO
600/min	Per environment	Circuit breaker per tenant

Credential Verification (Layered Protection)

Layer	Limit	Scope	Trigger
Temporary lockout	30 min lock	Per env + email	10+ failures
Exponential backoff	5s → 15 min	Per env + email	3+ failures
Rate limit	5/15min	Per env + email	Standard limit
Rate limit	10/15min	Per env + IP	Standard limit
Global safety net	20/15min	Global per email	Prevents tenant rotation

Email Sending

Layer	Limit	Scope
Deduplication	3 min window	Per env + email + type
Hourly per address	3/hour	Per env + email + type
Hourly per IP	10/hour	Per env + IP + type
Daily global	20/day	Global per email

Configuration

All rate limits are configurable via environment variables.

Variable	Default	Description
RATE_LIMIT_CONFIG_PER_IP	120/minute	Config endpoint per IP
RATE_LIMIT_CONFIG_PER_ENV	600/minute	Config endpoint per environment
RATE_LIMIT_VERIFY_PER_ENV_EMAIL	5/15minutes	Per env + email
RATE_LIMIT_VERIFY_PER_ENV_IP	10/15minutes	Per env + IP
RATE_LIMIT_EMAIL_PER_ENV_ADDR	3/hour	Per env + email + type
RATE_LIMIT_EMAIL_GLOBAL_DAILY	20/day	Global daily per email
BACKOFF_BASE_SECONDS	5	Initial backoff delay
BACKOFF_MAX_SECONDS	900	Maximum backoff (15 min)
BACKOFF_LOCKOUT_THRESHOLD	10	Failures before lockout
RATE_LIMIT_ENTERPRISE_MULTIPLIER	5.0	Multiplier for enterprise tier

Response Format

Rate Limit Exceeded

HTTP/1.1 429 Too Many Requests
Retry-After: 847

{
  "detail": "Too many verification attempts. Please try again later.",
  "code": "rate_limit_exceeded"
}

Temporary Lockout

HTTP/1.1 429 Too Many Requests
Retry-After: 1800

{
  "detail": "Account temporarily locked due to too many failed attempts.",
  "code": "exceeded_max_login_attempts"
}

The Retry-After header indicates seconds until the limit resets.