Quickstart¶
This walks through a minimal but complete app: bootstrap the tables, register a device on login, and protect a route so it only accepts recognized devices.
1. Configure the library¶
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,
# Tell the library how to identify the caller + their device from a request.
# Plug in your own auth here (decode a JWT, read a session, etc.).
get_user_id=lambda request: request.headers["x-user-id"],
get_device_uid=lambda request: request.headers.get("x-device-uid"),
)
get_user_id and get_device_uid are the only glue you write — they keep the
library auth-agnostic. get_device_uid may return None (e.g. on first
contact) and the request will be rejected for protected routes.
2. Mount the router and error handlers¶
app = FastAPI()
app.include_router(td.router, prefix="/trusted-devices", tags=["devices"])
td.install_exception_handlers(app)
@app.on_event("startup")
async def _startup() -> None:
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
In production, prefer Alembic migrations over create_all — Base.metadata
includes the trusted_devices table so it works with autogenerate.
3. Register a device at login¶
After your own login succeeds, register (or look up) the caller's device. The
facade exposes a one-shot helper that opens a session, commits, and returns the
Device:
@app.post("/login")
async def login(user_id: str) -> dict[str, str]:
# ... your real authentication happens here ...
device = await td.register_device(
user_id,
name="My laptop",
user_agent="Mozilla/5.0 ...",
ip_address="203.0.113.10",
)
# Hand the device_uid back to the client; it sends it on later requests
# (header, cookie, or embedded in your JWT — your choice).
return {"device_uid": str(device.device_uid)}
4. Protect routes¶
Add the dependency to any route (or whole router) that should require a known device:
@app.get("/me", dependencies=[Depends(td.require_trusted_device)])
async def me() -> dict[str, str]:
return {"ok": "this route requires a recognized device"}
Need the resolved device inside the handler? Depend on it directly:
from fastapi_trusted_devices import Device
@app.get("/whoami")
async def whoami(device: Device = Depends(td.require_trusted_device)) -> dict:
return {"device_uid": str(device.device_uid), "name": device.name}
5. Use the management endpoints¶
With the router mounted at /trusted-devices, your client can now:
| Method | Path | Purpose |
|---|---|---|
GET |
/trusted-devices/ |
List the current user's devices |
PATCH |
/trusted-devices/{device_uid} |
Rename / change permissions |
DELETE |
/trusted-devices/{device_uid} |
Revoke a specific device |
POST |
/trusted-devices/logout |
Revoke the current device |
POST |
/trusted-devices/revoke-all |
Revoke every device except the current one |
See the API Reference for request/response schemas, and Configuration for the available knobs.