py-auth-fastapi

FastAPI integration for py-auth-core.

PyAuthFastAPI is an APIRouter. You pass it a configured PyAuth instance; it registers the HTTP routes, sets and clears cookies, and turns py-auth errors into FastAPI HTTPExceptions. It does not talk to the database — that stays on your adapter.

Requires Python 3.10+.

Install

pip install py-auth-fastapi

You also need py-auth-core and a storage adapter such as py-auth-sqlalchemy.

Quick start

from fastapi import FastAPI, Depends
from py_auth import PyAuth
from py_auth_fastapi import PyAuthFastAPI

auth = PyAuth(adapter=adapter, providers=[...])

app = FastAPI()
auth_router = PyAuthFastAPI(auth)
app.include_router(auth_router)

@app.get("/protected")
async def protected(session=Depends(auth_router.get_current_session())):
    return {"user_id": session["user_id"]}

Defaults: prefix /auth, tags ["Authentication"]. Extra keyword arguments are forwarded to APIRouter. Cookie names and flags come from auth.cookies (configured on PyAuth, not here).

PyAuthFastAPI(auth, prefix="/api/auth", tags=["Auth"])

Routes

Mutating routes that require CSRF compare the CSRF cookie with the x-csrf-token header (double-submit). Fetch GET /auth/csrf first, then send the same value in that header.

On failure, the response looks like:

{
  "detail": {
    "success": false,
    "message": "...",
    "error": { "status_code": 401, "code": "InvalidSession", "details": {} }
  }
}

Protecting your own routes

get_current_session() is a FastAPI dependency factory. It reads the session cookie, calls verify_session, and injects the session dict (id, user_id, expires, …). Invalid or missing sessions become HTTP errors.

Use add_csrf_verification=True on endpoints that change state:

@app.post("/profile")
async def update_profile(
    session=Depends(auth_router.get_current_session(add_csrf_verification=True)),
):
    ...

verify_csrf() is available on its own if you only need the CSRF check.

License

MIT