AuthApi — Clean Architecture Auth API

The Problem

Most auth tutorials stop at "hash the password and return a JWT." Real-world auth needs rate limiting, token refresh, audit trails, role-based access, multiple auth provider support, and graceful error handling — none of which fits in a blog post. I wanted to build the full system end-to-end and make it available for anyone to test or plug into their own local projects.

The Approach

Engineered a full-featured authentication API using Clean Architecture with four distinct layers — Domain, Application, Infrastructure, and Api. The system supports two interchangeable auth providers (Supabase GoTrue and local BCrypt+JWT) behind a shared IAuthProvider interface, meaning the entire auth backend can be swapped without touching a single controller. Deployed on Fly.io as a public sandbox with Swagger docs for easy exploration.

System Architecture

Clean Architecture with strict dependency direction — outer layers depend on inner layers, never the reverse. The Domain layer has zero dependencies. Dual auth providers implement the same interface so switching between Supabase and local auth is a single config change.

Auth Flow

Client authenticates via email/password, receives JWT access + refresh tokens. Protected endpoints validate the Bearer token. Admin endpoints use a separate API key scheme. Token refresh is handled server-side without re-authentication.

API Structure

RESTful API versioned at /api/v1. Auth endpoints are public but rate-limited. User endpoints require JWT Bearer. Admin endpoints require an API key header. All errors return a consistent JSON shape with correlation IDs for debugging.

Try It — Sandbox API

The sandbox API is live. Copy any of these curl commands to test the endpoints directly.

curl -X POST https://authapi-clean.fly.dev/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "demo@example.com",
    "password": "Test1234!",
    "fullName": "Demo User"
  }'

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "v1.MHg3...",
  "expires_in": 3600,
  "token_type": "bearer",
  "user": {
    "id": "a1b2c3d4-...",
    "email": "demo@example.com",
    "role": "authenticated"
  }
}

curl -X POST https://authapi-clean.fly.dev/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "demo@example.com",
    "password": "Test1234!"
  }'

curl -X POST https://authapi-clean.fly.dev/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "<refresh_token>"
  }'

curl https://authapi-clean.fly.dev/api/v1/users/me \
  -H "Authorization: Bearer <access_token>"

{
  "id": "a1b2c3d4-...",
  "email": "demo@example.com",
  "fullName": "Demo User",
  "avatarUrl": null,
  "role": 0,
  "createdAt": "2026-02-21T18:00:00Z",
  "updatedAt": "2026-02-21T18:00:00Z"
}

curl https://authapi-clean.fly.dev/health

{
  "status": "healthy",
  "timestamp": "2026-02-21T19:30:00Z",
  "version": "1.0.0",
  "environment": "Sandbox",
  "authProvider": "Supabase"
}

Database Design

PostgreSQL with Entity Framework Core 10. Profiles mirror Supabase auth users for local data ownership. Audit logs track every auth action with IP, user agent, and success/failure for security forensics. Refresh tokens have expiry tracking for automatic cleanup.

Technical Decisions & Tradeoffs

Error Handling

Every error — validation, auth failure, rate limiting, server error — returns a consistent JSON shape with a correlationId that maps to server-side logs. Global exception middleware catches unhandled errors so no stack traces ever leak to clients.

{
  "status": 401,
  "message": "Invalid credentials.",
  "correlationId": "0HNJ..."
}

{
  "status": 429,
  "message": "Too many requests. Please try again later."
}

What It Does

What I Learned

Building a full auth system — not a tutorial, but a deployed, documented API — forced me to think about every edge case: What happens when Supabase is down? How do you prevent user enumeration on forgot-password? Why does the rate limiter need separate policies for auth vs general endpoints? Clean Architecture paid off the moment I needed to add the local auth provider — zero changes to controllers, just a new class implementing the same interface. The dual-provider pattern is something I'll carry into every future project.