Full-Stack REST API — Auth System

A production-ready authentication and user management API built with FastAPI, PostgreSQL, Redis, and Docker. Register users, log in with JWT tokens, verify emails, reset passwords—everything you'd expect from a solid auth backend, ready to plug into your next project.

---

What’s inside

• JWT auth — Access and refresh tokens, secure and stateless
• Roles — Admin and User, with protected endpoints
• Email verification — Verify addresses before full access
• Password reset — Triggered by email link
• Rate limiting — Per IP and per user to keep things safe
• Structured logging — JSON logs for easy monitoring
• Docker support — Multi-stage builds, Compose for local dev
• Cloud-ready — Designed for AWS (EC2, RDS, SES)

---

Quick start (Docker)

If you’ve got Docker installed, you can be up and running in a few minutes.

1. Set up your environment

   cp .env.example .env

   Open .env and set a few basics:

   • SECRET_KEY — a long random string (32+ characters)
   • POSTGRES_PASSWORD — your database password
   • DATABASE_URL — e.g. postgresql+asyncpg://authuser:changeme@db:5432/authdb

2. Spin everything up

   docker compose up --build

3. Open the docs

   Once it’s running, head to: http://localhost:8000/docs

The API runs on port 8000. PostgreSQL is on 5432 and Redis on 6379.

---

Running without Docker

If you prefer to run things locally:

1. Create .env from .env.example and set:

   • DATABASE_URL=postgresql+asyncpg://authuser:changeme@localhost:5432/authdb
   • REDIS_URL=redis://localhost:6379/0
   • SECRET_KEY — a secure random string

2. Install dependencies

   pip install -r requirements.txt

3. Start PostgreSQL and Redis (locally or in Docker)

4. Run the API

   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

---

Handy commands

Create an admin user (after first run):

# With Docker
docker compose run --rm api python scripts/seed_admin.py

# Locally
ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=Admin1234! python scripts/seed_admin.py

Run tests

docker compose run --rm api pytest tests/ -v

Apply database migrations

docker compose run --rm api alembic upgrade head

---

Tech stack

Layer	Tech
Backend	Python 3.11, FastAPI
Database	PostgreSQL 15
Cache	Redis 7
Email	AWS SES or SMTP (e.g. Mailtrap)
Containers	Docker, Docker Compose
Deployment	AWS EC2, RDS, SES, GitHub Actions

---

Project structure

auth-system/
├── app/
│   ├── api/v1/endpoints/   # Auth, users, admin, health
│   ├── core/               # Config, security, logging
│   ├── db/                 # Database session & models
│   ├── models/             # SQLAlchemy ORM
│   ├── schemas/            # Pydantic request/response
│   └── services/           # Business logic (user, token, email)
├── tests/
├── migrations/             # Alembic migrations
├── scripts/                # DB init, seed admin
├── nginx/                  # Reverse proxy config
├── .github/workflows/      # CI/CD
├── Dockerfile
├── docker-compose.yml
└── .env.example

---

API endpoints

Auth

Method	Path	Description
POST	/api/v1/auth/register	Register a new user
POST	/api/v1/auth/login	Log in, get tokens
POST	/api/v1/auth/refresh	Refresh access token
POST	/api/v1/auth/logout	Revoke refresh token
GET	/api/v1/auth/verify-email	Verify email address
POST	/api/v1/auth/resend-verification	Resend verification
POST	/api/v1/auth/forgot-password	Request password reset
POST	/api/v1/auth/reset-password	Reset password

Users

Method	Path	Description	Auth
GET	/api/v1/users/me	Get current user	Bearer
PUT	/api/v1/users/me	Update profile	Bearer
DELETE	/api/v1/users/me	Delete account	Bearer

Admin

Method	Path	Description	Auth
GET	/api/v1/admin/users	List all users	Admin
GET	/api/v1/admin/users/{id}	Get user by ID	Admin
PUT	/api/v1/admin/users/{id}	Update role/status	Admin
DELETE	/api/v1/admin/users/{id}	Delete user	Admin

Health

Method	Path	Description
GET	/api/v1/health	Health check

---

Deployment

For AWS deployment, see scripts/deploy.sh and .github/workflows/deploy.yml.

---

Licence

Feel free to use this project as a starting point for your own applications.