fastapi-fullauth 0.1.0__tar.gz

fastapi_fullauth-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --dev --extra sqlalchemy --extra sqlmodel
+      - run: uv run pytest tests/ -v

fastapi_fullauth-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

fastapi_fullauth-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Databases
+*.db
+*.sqlite3
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Distribution
+*.tar.gz
+*.whl
+architecture.md

fastapi_fullauth-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

fastapi_fullauth-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+### Added
+
+- **Core auth engine**: JWT access/refresh tokens with rotation and blacklisting
+- **Password hashing**: Argon2id by default via argon2-cffi
+- **Auth flows**: register, login, logout, password reset, email verification
+- **Brute-force protection**: progressive lockout after configurable failed attempts
+- **Auth backends**: Bearer token and HttpOnly cookie backends (pluggable)
+- **FastAPI dependencies**: `current_user`, `current_active_verified_user`, `require_role`, `require_permission`, `CurrentUser`, `VerifiedUser`
+- **Pre-built router**: `/auth/me` (GET/PATCH/DELETE), `/auth/me/verified`, `/auth/register`, `/auth/login`, `/auth/logout`, `/auth/refresh`, `/auth/change-password`, `/auth/password-reset/*`, `/auth/verify-email/*`, `/auth/admin/*`
+- **Change password**: `POST /auth/change-password` — verifies current password, validates new password strength
+- **Update profile**: `PATCH /auth/me` — update user fields with protected field filtering
+- **Delete account**: `DELETE /auth/me` — self-deletion for logged-in users
+- **Token expires_in**: login and refresh responses include `expires_in` (seconds) for frontend token refresh scheduling
+- **Auth route rate limiting**: per-IP rate limits on login, register, and password-reset routes (configurable via `AUTH_RATE_LIMIT_*`)
+- **Flat config**: `FullAuth(secret_key=..., adapter=...)` — no `FullAuthConfig` wrapper needed
+- **Auto SECRET_KEY**: omit `secret_key` in dev mode, auto-generates with a warning
+- **Route enum**: `Route.LOGIN`, `Route.ME`, etc. for type-safe `enabled_routes`
+- **Auto-derive schemas**: `UserSchema` and `CreateUserSchema` auto-generated from ORM model fields
+- **Auto-wire middleware**: SecurityHeaders, CSRF, and RateLimit auto-added by `init_app()` from config flags
+- **Email hooks**: `send_verification_email` and `send_password_reset_email` in the hooks system
+- **Event hooks**: `after_register`, `after_login`, `after_logout`, `after_password_reset`, `after_email_verify`
+- **Redis blacklist**: async `RedisBlacklist` backend via `redis.asyncio` — activate with `BLACKLIST_BACKEND="redis"`
+- **Refresh token persistence**: stored in DB with family tracking for theft detection
+- **Token reuse detection**: replaying a used refresh token revokes the entire token family
+- **Logout refresh revocation**: pass `refresh_token` in logout body to revoke the session family
+- **Configuration**: `FullAuthConfig` via pydantic-settings with `FULLAUTH_` env var prefix, or inline kwargs
+- **ORM adapters**: SQLAlchemy (async), SQLModel (async), and InMemory (for testing)
+- **Modular extras**: `[sqlalchemy]`, `[sqlmodel]`, `[redis]` — install only what you need
+- **Alembic migration helpers**: `include_fullauth_models()` and `get_fullauth_metadata()`
+- **Password validation**: configurable rules (length, uppercase, digit, special, blocked list)
+- **Custom token claims**: `on_create_token_claims` callback embedded in JWTs
+- **Utilities**: `create_superuser()`, `generate_secret_key()`
+- **Test suite**: 97 tests covering all auth flows, tokens, middleware, DX, refresh token security, and new endpoints
+- **Examples**: InMemory, SQLAlchemy, and SQLModel demo apps

fastapi_fullauth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammed Farhan KC
+
+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.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_fullauth-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: fastapi-fullauth
+Version: 0.1.0
+Summary: Production-grade, async-native authentication and authorization library for FastAPI
+Project-URL: Homepage, https://github.com/mdfarhankc/fastapi-fullauth
+Project-URL: Documentation, https://github.com/mdfarhankc/fastapi-fullauth
+Project-URL: Repository, https://github.com/mdfarhankc/fastapi-fullauth
+License-Expression: MIT
+License-File: LICENSE
+Keywords: argon2,authentication,authorization,fastapi,jwt,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: argon2-cffi>=23.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic[email]>=2.0
+Requires-Dist: pyjwt>=2.8
+Requires-Dist: python-multipart>=0.0.22
+Requires-Dist: uuid-utils>=0.14.1
+Provides-Extra: all
+Requires-Dist: alembic>=1.13; extra == 'all'
+Requires-Dist: beanie>=1.25; extra == 'all'
+Requires-Dist: httpx-oauth>=0.13; extra == 'all'
+Requires-Dist: itsdangerous>=2.1; extra == 'all'
+Requires-Dist: pyotp>=2.9; extra == 'all'
+Requires-Dist: qrcode>=7.4; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'all'
+Requires-Dist: sqlmodel>=0.0.16; extra == 'all'
+Requires-Dist: tortoise-orm>=0.21; extra == 'all'
+Requires-Dist: webauthn>=2.0; extra == 'all'
+Provides-Extra: audit
+Provides-Extra: beanie
+Requires-Dist: beanie>=1.25; extra == 'beanie'
+Provides-Extra: magic-link
+Requires-Dist: itsdangerous>=2.1; extra == 'magic-link'
+Provides-Extra: oauth
+Requires-Dist: httpx-oauth>=0.13; extra == 'oauth'
+Provides-Extra: passkeys
+Requires-Dist: webauthn>=2.0; extra == 'passkeys'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: sqlalchemy
+Requires-Dist: alembic>=1.13; extra == 'sqlalchemy'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'sqlalchemy'
+Provides-Extra: sqlmodel
+Requires-Dist: alembic>=1.13; extra == 'sqlmodel'
+Requires-Dist: sqlmodel>=0.0.16; extra == 'sqlmodel'
+Provides-Extra: tenants
+Provides-Extra: tortoise
+Requires-Dist: tortoise-orm>=0.21; extra == 'tortoise'
+Provides-Extra: totp
+Requires-Dist: pyotp>=2.9; extra == 'totp'
+Requires-Dist: qrcode>=7.4; extra == 'totp'
+Description-Content-Type: text/markdown
+
+# fastapi-fullauth
+
+[![PyPI](https://img.shields.io/pypi/v/fastapi-fullauth)](https://pypi.org/project/fastapi-fullauth/)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-fullauth)](https://pypi.org/project/fastapi-fullauth/)
+[![CI](https://github.com/mdfarhankc/fastapi-fullauth/actions/workflows/ci.yml/badge.svg)](https://github.com/mdfarhankc/fastapi-fullauth/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Async auth library for FastAPI. Handles JWT tokens, refresh rotation, password hashing, email verification, and role-based access out of the box.
+
+## Install
+
+```bash
+pip install fastapi-fullauth
+# with an ORM adapter:
+pip install fastapi-fullauth[sqlmodel]
+pip install fastapi-fullauth[sqlalchemy]
+# with redis for token blacklisting:
+pip install fastapi-fullauth[sqlmodel,redis]
+```
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from fastapi_fullauth import FullAuth
+from fastapi_fullauth.adapters.memory import InMemoryAdapter
+
+app = FastAPI()
+
+fullauth = FullAuth(
+    secret_key="your-secret-key",
+    adapter=InMemoryAdapter(),
+)
+fullauth.init_app(app)
+```
+
+This gives you `/auth/me`, `/auth/register`, `/auth/login`, `/auth/logout`, `/auth/refresh`, `/auth/change-password`, `/auth/password-reset/*`, `/auth/verify-email/*`, and admin role management endpoints — all under `/api/v1` by default.
+
+Omit `secret_key` in dev and a random one is generated (tokens won't survive restarts).
+
+## Custom user fields
+
+Just define your model — schemas are auto-derived:
+
+```python
+from fastapi_fullauth.adapters.sqlmodel import UserBase, Role, UserRoleLink, RefreshTokenRecord, SQLModelAdapter
+from sqlmodel import Field, Relationship
+
+class MyUser(UserBase, table=True):
+    __tablename__ = "fullauth_users"
+    __table_args__ = {"extend_existing": True}
+
+    display_name: str = Field(default="", max_length=100)
+    phone: str = Field(default="", max_length=20)
+
+    roles: list[Role] = Relationship(back_populates="users", link_model=UserRoleLink)
+    refresh_tokens: list[RefreshTokenRecord] = Relationship(back_populates="user")
+
+fullauth = FullAuth(
+    secret_key="...",
+    adapter=SQLModelAdapter(session_maker, user_model=MyUser),
+)
+```
+
+No need to create separate schema classes or subclass the adapter. Registration and response schemas pick up `display_name` and `phone` automatically. You can still pass explicit `user_schema` / `create_user_schema` if you want full control.
+
+## Protected routes
+
+```python
+from fastapi import Depends
+from fastapi_fullauth.dependencies import current_user, require_role
+
+@app.get("/profile")
+async def profile(user=Depends(current_user)):
+    return user
+
+@app.delete("/admin/users/{id}")
+async def delete_user(user=Depends(require_role("admin"))):
+    ...
+```
+
+## Configuration
+
+Pass inline kwargs or a full config object:
+
+```python
+# inline
+fullauth = FullAuth(
+    secret_key="...",
+    adapter=adapter,
+    api_prefix="/api/v2",
+    access_token_expire_minutes=60,
+)
+
+# or use FullAuthConfig for everything
+from fastapi_fullauth import FullAuthConfig
+fullauth = FullAuth(config=FullAuthConfig(SECRET_KEY="..."), adapter=adapter)
+```
+
+Config also reads env vars with `FULLAUTH_` prefix.
+
+## Redis blacklist
+
+```python
+fullauth = FullAuth(
+    secret_key="...",
+    adapter=adapter,
+    blacklist_backend="redis",
+    redis_url="redis://localhost:6379/0",
+)
+```
+
+## Refresh token security
+
+Refresh tokens are stored in DB with family tracking. If a revoked token is replayed (possible theft), the entire token family gets revoked. Disable rotation with `REFRESH_TOKEN_ROTATION=False`.
+
+## Event hooks
+
+```python
+async def welcome(user):
+    await send_email(user.email, "Welcome!")
+
+fullauth.hooks.on("after_register", welcome)
+```
+
+Events: `after_register`, `after_login`, `after_logout`, `after_password_change`, `after_password_reset`, `after_email_verify`, `send_verification_email`, `send_password_reset_email`
+
+## Route control
+
+```python
+from fastapi_fullauth import Route
+
+fullauth = FullAuth(
+    secret_key="...",
+    adapter=adapter,
+    enabled_routes=[Route.LOGIN, Route.LOGOUT, Route.REFRESH],
+)
+```
+
+## Middleware
+
+SecurityHeaders, CSRF, and rate limiting are auto-wired from config flags. Pass `auto_middleware=False` to `init_app()` to handle it yourself.
+
+## Auth rate limiting
+
+Login, register, and password-reset have per-IP rate limits enabled by default (5/3/3 per minute). Configure via `AUTH_RATE_LIMIT_*` settings.
+
+## Development
+
+```bash
+git clone https://github.com/mdfarhankc/fastapi-fullauth.git
+cd fastapi-fullauth
+uv sync --dev --extra sqlalchemy --extra sqlmodel
+uv run pytest tests/ -v
+```
+
+## License
+
+MIT

fastapi_fullauth-0.1.0/README.md

@@ -0,0 +1,159 @@
+# fastapi-fullauth
+
+[![PyPI](https://img.shields.io/pypi/v/fastapi-fullauth)](https://pypi.org/project/fastapi-fullauth/)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-fullauth)](https://pypi.org/project/fastapi-fullauth/)
+[![CI](https://github.com/mdfarhankc/fastapi-fullauth/actions/workflows/ci.yml/badge.svg)](https://github.com/mdfarhankc/fastapi-fullauth/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Async auth library for FastAPI. Handles JWT tokens, refresh rotation, password hashing, email verification, and role-based access out of the box.
+
+## Install
+
+```bash
+pip install fastapi-fullauth
+# with an ORM adapter:
+pip install fastapi-fullauth[sqlmodel]
+pip install fastapi-fullauth[sqlalchemy]
+# with redis for token blacklisting:
+pip install fastapi-fullauth[sqlmodel,redis]
+```
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from fastapi_fullauth import FullAuth
+from fastapi_fullauth.adapters.memory import InMemoryAdapter
+
+app = FastAPI()
+
+fullauth = FullAuth(
+    secret_key="your-secret-key",
+    adapter=InMemoryAdapter(),
+)
+fullauth.init_app(app)
+```
+
+This gives you `/auth/me`, `/auth/register`, `/auth/login`, `/auth/logout`, `/auth/refresh`, `/auth/change-password`, `/auth/password-reset/*`, `/auth/verify-email/*`, and admin role management endpoints — all under `/api/v1` by default.
+
+Omit `secret_key` in dev and a random one is generated (tokens won't survive restarts).
+
+## Custom user fields
+
+Just define your model — schemas are auto-derived:
+
+```python
+from fastapi_fullauth.adapters.sqlmodel import UserBase, Role, UserRoleLink, RefreshTokenRecord, SQLModelAdapter
+from sqlmodel import Field, Relationship
+
+class MyUser(UserBase, table=True):
+    __tablename__ = "fullauth_users"
+    __table_args__ = {"extend_existing": True}
+
+    display_name: str = Field(default="", max_length=100)
+    phone: str = Field(default="", max_length=20)
+
+    roles: list[Role] = Relationship(back_populates="users", link_model=UserRoleLink)
+    refresh_tokens: list[RefreshTokenRecord] = Relationship(back_populates="user")
+
+fullauth = FullAuth(
+    secret_key="...",
+    adapter=SQLModelAdapter(session_maker, user_model=MyUser),
+)
+```
+
+No need to create separate schema classes or subclass the adapter. Registration and response schemas pick up `display_name` and `phone` automatically. You can still pass explicit `user_schema` / `create_user_schema` if you want full control.
+
+## Protected routes
+
+```python
+from fastapi import Depends
+from fastapi_fullauth.dependencies import current_user, require_role
+
+@app.get("/profile")
+async def profile(user=Depends(current_user)):
+    return user
+
+@app.delete("/admin/users/{id}")
+async def delete_user(user=Depends(require_role("admin"))):
+    ...
+```
+
+## Configuration
+
+Pass inline kwargs or a full config object:
+
+```python
+# inline
+fullauth = FullAuth(
+    secret_key="...",
+    adapter=adapter,
+    api_prefix="/api/v2",
+    access_token_expire_minutes=60,
+)
+
+# or use FullAuthConfig for everything
+from fastapi_fullauth import FullAuthConfig
+fullauth = FullAuth(config=FullAuthConfig(SECRET_KEY="..."), adapter=adapter)
+```
+
+Config also reads env vars with `FULLAUTH_` prefix.
+
+## Redis blacklist
+
+```python
+fullauth = FullAuth(
+    secret_key="...",
+    adapter=adapter,
+    blacklist_backend="redis",
+    redis_url="redis://localhost:6379/0",
+)
+```
+
+## Refresh token security
+
+Refresh tokens are stored in DB with family tracking. If a revoked token is replayed (possible theft), the entire token family gets revoked. Disable rotation with `REFRESH_TOKEN_ROTATION=False`.
+
+## Event hooks
+
+```python
+async def welcome(user):
+    await send_email(user.email, "Welcome!")
+
+fullauth.hooks.on("after_register", welcome)
+```
+
+Events: `after_register`, `after_login`, `after_logout`, `after_password_change`, `after_password_reset`, `after_email_verify`, `send_verification_email`, `send_password_reset_email`
+
+## Route control
+
+```python
+from fastapi_fullauth import Route
+
+fullauth = FullAuth(
+    secret_key="...",
+    adapter=adapter,
+    enabled_routes=[Route.LOGIN, Route.LOGOUT, Route.REFRESH],
+)
+```
+
+## Middleware
+
+SecurityHeaders, CSRF, and rate limiting are auto-wired from config flags. Pass `auto_middleware=False` to `init_app()` to handle it yourself.
+
+## Auth rate limiting
+
+Login, register, and password-reset have per-IP rate limits enabled by default (5/3/3 per minute). Configure via `AUTH_RATE_LIMIT_*` settings.
+
+## Development
+
+```bash
+git clone https://github.com/mdfarhankc/fastapi-fullauth.git
+cd fastapi-fullauth
+uv sync --dev --extra sqlalchemy --extra sqlmodel
+uv run pytest tests/ -v
+```
+
+## License
+
+MIT

fastapi_fullauth-0.1.0/examples/memory_app.py

@@ -0,0 +1,62 @@
+"""
+In-memory example — no database needed.
+
+Run: uv run uvicorn examples.memory_app:app --reload
+"""
+
+from fastapi import Depends, FastAPI
+
+from fastapi_fullauth import FullAuth
+from fastapi_fullauth.adapters.memory import InMemoryAdapter
+from fastapi_fullauth.dependencies import (
+    current_active_verified_user,
+    current_user,
+    require_role,
+)
+from fastapi_fullauth.types import CreateUserSchema, UserSchema
+
+
+class MyCreateUserSchema(CreateUserSchema):
+    display_name: str
+
+
+# replace these with real email sending in production
+async def send_verification_email(email: str, token: str):
+    print(f"\n[VERIFY] To: {email}\n[VERIFY] Token: {token}\n")
+
+
+async def send_password_reset_email(email: str, token: str):
+    print(f"\n[RESET] To: {email}\n[RESET] Token: {token}\n")
+
+
+async def add_custom_claims(user: UserSchema) -> dict:
+    return {"display_name": getattr(user, "display_name", "")}
+
+
+app = FastAPI(title="FullAuth In-Memory Demo")
+
+fullauth = FullAuth(
+    secret_key="change-me-use-a-32-byte-key-here",
+    adapter=InMemoryAdapter(),
+    on_send_verification_email=send_verification_email,
+    on_send_password_reset_email=send_password_reset_email,
+    create_user_schema=MyCreateUserSchema,
+    on_create_token_claims=add_custom_claims,
+    include_user_in_login=True,
+)
+fullauth.init_app(app)
+
+
+@app.get("/api/v1/me")
+async def me(user=Depends(current_user)):
+    return user
+
+
+@app.get("/api/v1/verified-only")
+async def verified_only(user=Depends(current_active_verified_user)):
+    return {"msg": "your email is verified", "user": user}
+
+
+@app.get("/api/v1/admin")
+async def admin_only(user=Depends(require_role("admin"))):
+    return {"msg": "welcome admin", "user": user}

fastapi_fullauth-0.1.0/examples/sqlalchemy_app.py

@@ -0,0 +1,86 @@
+"""
+SQLAlchemy example with custom user fields.
+
+Run: uv run uvicorn examples.sqlalchemy_app:app --reload
+Requires: uv add fastapi-fullauth[sqlalchemy] aiosqlite
+"""
+
+from contextlib import asynccontextmanager
+
+from fastapi import Depends, FastAPI
+from sqlalchemy import String
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.orm import Mapped, mapped_column
+
+from fastapi_fullauth import FullAuth
+from fastapi_fullauth.adapters.sqlalchemy import (
+    FullAuthBase,
+    SQLAlchemyAdapter,
+    UserModel,
+)
+from fastapi_fullauth.dependencies import (
+    current_active_verified_user,
+    current_user,
+    require_role,
+)
+from fastapi_fullauth.types import UserSchema
+
+DATABASE_URL = "sqlite+aiosqlite:///fullauth_sqlalchemy_demo.db"
+engine = create_async_engine(DATABASE_URL)
+session_maker = async_sessionmaker(engine, expire_on_commit=False)
+
+
+class MyUser(UserModel):
+    __tablename__ = "fullauth_users"
+    __table_args__ = {"extend_existing": True}
+
+    display_name: Mapped[str] = mapped_column(String(100), nullable=True, default="")
+    phone: Mapped[str] = mapped_column(String(20), nullable=True, default="")
+
+
+async def send_verification_email(email: str, token: str):
+    print(f"\n[VERIFY] To: {email}\n[VERIFY] Token: {token}\n")
+
+
+async def send_password_reset_email(email: str, token: str):
+    print(f"\n[RESET] To: {email}\n[RESET] Token: {token}\n")
+
+
+async def add_custom_claims(user: UserSchema) -> dict:
+    return {"display_name": getattr(user, "display_name", "")}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with engine.begin() as conn:
+        await conn.run_sync(FullAuthBase.metadata.create_all)
+    yield
+    await engine.dispose()
+
+
+app = FastAPI(title="FullAuth SQLAlchemy Demo", lifespan=lifespan)
+
+fullauth = FullAuth(
+    secret_key="change-me-use-a-32-byte-key-here",
+    adapter=SQLAlchemyAdapter(session_maker=session_maker, user_model=MyUser),
+    on_send_verification_email=send_verification_email,
+    on_send_password_reset_email=send_password_reset_email,
+    on_create_token_claims=add_custom_claims,
+    include_user_in_login=True,
+)
+fullauth.init_app(app)
+
+
+@app.get("/api/v1/me")
+async def me(user=Depends(current_user)):
+    return user
+
+
+@app.get("/api/v1/verified-only")
+async def verified_only(user=Depends(current_active_verified_user)):
+    return {"msg": "your email is verified", "user": user}
+
+
+@app.get("/api/v1/admin")
+async def admin_only(user=Depends(require_role("admin"))):
+    return {"msg": "welcome admin", "user": user}