Skip to content

FastAPI Trusted Devices

PyPI Python versions License: MIT CI

Trusted-device management and session security for FastAPI.

FastAPI gives you authentication primitives but no notion of which device a token belongs to. fastapi-trusted-devices adds that layer — bind every authenticated session to a known device, list and revoke devices, and react to device lifecycle events — without locking your app into a specific auth library or ORM.

Alpha

This is 0.1.0 — alpha. The core device registry and management endpoints are stable enough to use, but the public API may change before 1.0. See the Roadmap.

Features

  • 🔐 Device-bound sessions — associate each session with a device_uid.
  • 📋 List & revoke — list a user's active devices, revoke one, revoke all-but-current, or log out the current device.
  • 🛡️ Per-device permissions — control which devices may update or revoke other devices.
  • 🧩 Auth-agnostic — keep your own login/JWT flow; you pass two callables (get_user_id, get_device_uid).
  • 🗄️ Storage-abstracted — everything sits behind a DeviceRepository protocol, with an async SQLAlchemy 2.0 adapter included.
  • 🪝 Event hooks — async callbacks for on_device_created and on_device_revoked.
  • 📈 Device caps — optional max_devices_per_user with oldest-device eviction.
  • ⏱️ Mutation delays — optional minimum device age before rename/revoke.
  • ⌨️ Fully typed — ships py.typed, mypy --strict clean, tested on Python 3.10–3.13.

Documentation

Install

pip install fastapi-trusted-devices

At a glance

from fastapi import Depends, FastAPI
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine

from fastapi_trusted_devices import Base, TrustedDevices, TrustedDeviceConfig

engine = create_async_engine("sqlite+aiosqlite:///./devices.db")
sessionmaker = async_sessionmaker(engine, expire_on_commit=False)

td = TrustedDevices(
    config=TrustedDeviceConfig(max_devices_per_user=10),
    sessionmaker=sessionmaker,
    get_user_id=lambda request: request.headers["x-user-id"],
    get_device_uid=lambda request: request.headers.get("x-device-uid"),
)

app = FastAPI()
app.include_router(td.router, prefix="/trusted-devices", tags=["devices"])
td.install_exception_handlers(app)


@app.get("/me", dependencies=[Depends(td.require_trusted_device)])
async def me() -> dict[str, str]:
    return {"ok": "this route requires a recognized device"}

Continue to the Quickstart for the full runnable example.


If this project helps you, please ⭐ star it on GitHub — it really helps others find it.