FastAPI Trusted Devices¶
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
DeviceRepositoryprotocol, with an async SQLAlchemy 2.0 adapter included. - 🪝 Event hooks — async callbacks for
on_device_createdandon_device_revoked. - 📈 Device caps — optional
max_devices_per_userwith oldest-device eviction. - ⏱️ Mutation delays — optional minimum device age before rename/revoke.
- ⌨️ Fully typed — ships
py.typed,mypy --strictclean, tested on Python 3.10–3.13.
Documentation¶
- Installation — install and optional extras.
- Quickstart — a working app in ~30 lines.
- Configuration — every
TrustedDeviceConfigfield. - API Reference — endpoints, schemas, and the facade.
- Storage & Repository — the
DeviceRepositoryprotocol and custom adapters. - Events — device lifecycle hooks.
- Exceptions — the error hierarchy and JSON format.
Install¶
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.