Device Endpoints
The device management endpoints handle device fingerprinting, trusted device management, and device blocking. All endpoints require authentication. Served by DeviceController at /api/v1/devices.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/devices | List all devices |
| GET | /api/v1/devices/trusted | List trusted devices |
| POST | /api/v1/devices/register | Register or update device fingerprint |
| POST | /api/v1/devices/:deviceId/trust | Mark device as trusted |
| DELETE | /api/v1/devices/:deviceId/trust | Remove trust from device |
| PUT | /api/v1/devices/:deviceId/name | Rename a device |
| POST | /api/v1/devices/:deviceId/block | Block a device |
| DELETE | /api/v1/devices/:deviceId/block | Unblock a device |
| DELETE | /api/v1/devices/:deviceId | Remove a device |
| DELETE | /api/v1/devices/trusted/all | Untrust all devices |
POST /api/v1/devices/register
Registers or updates a device fingerprint. The client IP and User-Agent are captured automatically from the request.
{
"fingerprint": "a1b2c3d4e5f6...",
"deviceName": "Work Laptop",
"deviceType": "desktop",
"browser": "Chrome",
"browserVersion": "120.0",
"os": "macOS",
"osVersion": "14.2"
}DeviceResponse Structure
{
"id": 42,
"deviceName": "Work Laptop",
"deviceType": "desktop",
"browser": "Chrome",
"browserVersion": "120.0",
"os": "macOS",
"osVersion": "14.2",
"trusted": true,
"trustedAt": "2026-02-01T10:00:00Z",
"blocked": false,
"lastIpAddress": "192.168.1.100",
"lastSeenAt": "2026-02-12T14:30:00Z",
"useCount": 47,
"createdAt": "2026-01-15T08:00:00Z"
}Trust Management
Trusted devices may bypass MFA challenges based on the tenant security policy. There is a configurable maximum number of trusted devices per user.
| Endpoint | Effect |
|---|---|
POST /api/v1/devices/:deviceId/trust | Marks device as trusted (returns 400 if max reached) |
DELETE /api/v1/devices/:deviceId/trust | Removes trust (MFA required on next login) |
DELETE /api/v1/devices/trusted/all | Untrusts all devices, returns {"untrusted": count} |
Device Blocking
Blocked devices are denied authentication attempts entirely, regardless of valid credentials.
| Endpoint | Effect |
|---|---|
POST /api/v1/devices/:deviceId/block | Blocks device (optional reason in body) |
DELETE /api/v1/devices/:deviceId/block | Unblocks device |