fastapi-authly

A modular authentication system for FastAPI applications. Provides complete user authentication with OAuth2, JWT tokens, password recovery, and more.

✨ Features

• 🔐 OAuth2 Password Flow - Standard OAuth2 authentication
• 🎫 JWT Token Management - Secure token creation and validation
• 🔑 Password Recovery - Email-based password reset
• 👤 User Management - Registration, profile management
• 📧 Email Verification - User email verification system
• 🔄 Token Refresh - Refresh token functionality
• 🧩 Modular Design - Easy to integrate and configure
• 🛡️ Security First - Built with security best practices
• 📚 Type Hints - Full type annotation support

🚀 Quick Start (Tortoise + Postgres 默认实现)

Installation

uv pip install fastapi-authly
# or
pip install fastapi-authly

Minimal FastAPI App (uses default TortoiseUserRepository)

from fastapi import FastAPI
from tortoise.contrib.fastapi import register_tortoise
from fastapi_authly import (
    AuthConfig,
    AuthDependencyConfig,
    create_auth_router,
)
from fastapi_authly.contrib.tortoise_pg import TortoiseUserRepository

app = FastAPI()

# 1) init Tortoise (Postgres)
register_tortoise(
    app,
    db_url="postgres://user:password@localhost:5432/mydb",
    modules={"models": ["fastapi_authly.models.user"]},
    generate_schemas=True,
    add_exception_handlers=True,
)

# 2) assemble auth router with default repo (can override via dependencies)
config = AuthConfig(token_url="login")  # keep token_url aligned with /login route
deps = AuthDependencyConfig(user_repository=TortoiseUserRepository())

auth_router = create_auth_router(config=config, dependencies=deps)
app.include_router(auth_router)

# Optional: Setup Scalar API documentation (static resources included, no manual setup needed)
from fastapi_authly import setup_scalar_docs
setup_scalar_docs(app, docs_url="/docs", static_url="/static")

Advanced Usage (custom implementations)

from fastapi_authly import AuthConfig, AuthDependencyConfig, create_auth_router
from fastapi_authly.interfaces import UserRepository, Mailer

class MyRepo(UserRepository):
    async def get_by_name(self, username: str): ...
    async def get_by_id(self, user_id: str | int): ...
    async def create_user(self, user): ...
    async def to_public(self, user): ...

class MyMailer(Mailer):
    async def send_password_reset(self, request, token): ...
    async def send_verification(self, email, token): ...

config = AuthConfig(router_prefix="/api/auth", token_url="login")
deps = AuthDependencyConfig(
    user_repository=MyRepo(),
    mailer=MyMailer(),
)
auth_router = create_auth_router(config=config, dependencies=deps)

📚 API Documentation

fastapi-authly includes built-in Scalar API documentation support with all necessary static resources:

from fastapi import FastAPI
from fastapi_authly import setup_scalar_docs

app = FastAPI(title="My API")

# One line to enable Scalar documentation
# Automatically mounts static files to /static and creates docs page at /docs
setup_scalar_docs(app)

# Custom configuration
setup_scalar_docs(
    app,
    docs_url="/api-docs",      # Custom docs URL
    static_url="/assets",      # Custom static files prefix
    title="Custom API Docs",   # Custom title
    openapi_url="/openapi.json" # Custom OpenAPI schema URL
)

📋 API Endpoints

Authentication

• POST /auth/login - Login and get access token (+optional refresh)
• POST /auth/token/verify - Verify token validity
• POST /auth/token/refresh - Refresh access token

User Management

• POST /auth/register - User registration
• GET /auth/me - Get current user info

Password Management

• POST /auth/password/reset-request - Request password reset
• POST /auth/password/reset - Reset password with token

🔧 Configuration

AuthConfig Parameters

🏗️ Architecture

fastapi_authly/
├── auth.py                    # Main authentication module (routes)
├── schemas/                   # Pydantic schemas (request/response models)
│   └── user.py
├── models/                    # DB models (e.g., Tortoise ORM)
│   └── user.py
├── contrib/
│   └── tortoise_pg.py         # Default Tortoise Postgres repository
├── core/                      # Core functionality
│   ├── config.py              # Settings & dependency container
│   ├── security.py            # Token + password utilities
│   └── __init__.py
├── interfaces.py              # Protocols (UserRepository, Mailer, etc.)
├── __init__.py                # Package exports
└── __about__.py               # Version info

🔌 Integration Examples

# FastAPI + Tortoise + Postgres (default repo)
from fastapi import FastAPI
from tortoise.contrib.fastapi import register_tortoise
from fastapi_authly import AuthConfig, AuthDependencyConfig, create_auth_router
from fastapi_authly.contrib.tortoise_pg import TortoiseUserRepository

app = FastAPI()

register_tortoise(
    app,
    db_url="postgres://user:password@localhost:5432/mydb",
    modules={"models": ["fastapi_authly.models.user"]},
    generate_schemas=True,
    add_exception_handlers=True,
)

config = AuthConfig(token_url="login")
deps = AuthDependencyConfig(user_repository=TortoiseUserRepository())
app.include_router(create_auth_router(config=config, dependencies=deps))

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastAPI - The web framework
• Pydantic - Data validation
• python-jose - JWT implementation
• passlib - Password hashing

📞 Support

If you have any questions or need help:

• 💬 GitHub Issues: Create an issue
• 📖 Documentation: Read the docs