API Reference¶
HTTP endpoints¶
The router returned by td.router exposes the endpoints below. Mount it at any
prefix; every endpoint requires a recognized device (it depends on
require_trusted_device internally).
| Method | Path | Summary | Request body | Response |
|---|---|---|---|---|
GET |
/ |
List my devices | — | list[DeviceOut] |
PATCH |
/{device_uid} |
Update a device | DeviceUpdate |
DeviceOut |
DELETE |
/{device_uid} |
Revoke a device | — | 204 No Content |
POST |
/logout |
Revoke the current device | — | 204 No Content |
POST |
/revoke-all |
Revoke all devices except this one | — | {"revoked": <int>} |
Schemas¶
class DeviceOut(BaseModel):
device_uid: uuid.UUID
name: str | None = None
user_agent: str | None = None
ip_address: str | None = None
last_ip: str | None = None
country: str | None = None
region: str | None = None
city: str | None = None
created_at: datetime
last_seen: datetime
can_update_other_devices: bool
can_delete_other_devices: bool
is_current: bool = False # True for the device that issued this request
TrustedDevices facade¶
The main entry point. Construct one and reuse it for the app's lifetime.
TrustedDevices(
*,
config: TrustedDeviceConfig,
sessionmaker: async_sessionmaker[AsyncSession],
get_user_id: Callable[[Request], str | Awaitable[str]],
get_device_uid: Callable[[Request], str | None | Awaitable[str | None]],
events: EventHooks | None = None,
now: Callable[[], datetime] = <utcnow>,
)
Attributes¶
| Attribute | Type | Description |
|---|---|---|
router |
APIRouter |
Mount it on your app at any prefix. |
require_trusted_device |
dependency | FastAPI dependency resolving to the caller's Device; raises if unknown. |
current_device |
dependency | Alias of require_trusted_device. |
events |
EventHooks |
The lifecycle-callback registry. See Events. |
Methods¶
Register JSON error handlers for allTrustedDeviceErrors on app. See
Exceptions.
async def register_device(
self,
user_id: str,
*,
name: str | None = None,
user_agent: str | None = None,
ip_address: str | None = None,
) -> Device
def build_service(self, session: AsyncSession) -> TrustedDeviceService
async def session_dependency(self) -> AsyncIterator[AsyncSession]
async def resolve_user_id(self, request: Request) -> str
async def resolve_device_uid(self, request: Request) -> uuid.UUID | None
TrustedDeviceService¶
The framework-free core. The facade builds one per request, but you can drive it directly (e.g. from a worker or test).
TrustedDeviceService(
repository: DeviceRepository,
config: TrustedDeviceConfig,
events: EventHooks,
*,
now: Callable[[], datetime] = <utcnow>,
)
| Method | Description |
|---|---|
register_device(user_id, *, name=None, user_agent=None, ip_address=None) -> Device |
Register a device; evict oldest if over the cap. |
list_devices(user_id) -> Sequence[Device] |
All of a user's devices. |
get_recognized(user_id, device_uid) -> Device |
Resolve the caller's device or raise. |
touch(device, *, ip_address=None) -> None |
Bump last_seen / last IP. |
update_device(actor, target_uid, payload: DeviceUpdate) -> Device |
Rename / change permissions, with permission + delay checks. |
revoke_device(actor, target_uid) -> Device |
Revoke another device, with permission + delay checks. |
logout(actor) -> Device |
Revoke the calling device (bypasses delete delay). |
revoke_all_others(actor) -> int |
Revoke every other device; returns the count. |
Storage details (the DeviceRepository protocol, the bundled SQLAlchemy adapter,
and the Device model) live in Storage & Repository.