User Device Management

Endpoints for managing user devices and trusted device sessions.

Overview

AuthOS tracks devices that users authenticate from. This enables:

Viewing active sessions across devices
Revoking access from specific devices
Device-based risk scoring
Trusted device recognition

Endpoints

Method	Path	Description
`GET`	`/api/user/devices`	List user’s devices
`GET`	`/api/user/devices/:id`	Get specific device
`PATCH`	`/api/user/devices/:id`	Update device name
`DELETE`	`/api/user/devices/:id`	Revoke device access

GET /api/user/devices

List all devices associated with the current user.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Authenticated User
Rate Limit	None

Request Headers

Header	Value	Required
`Authorization`	`Bearer {jwt}`	Yes

Example Request

curl -X GET https://sso.example.com/api/user/devices \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK)

{
  "devices": [
    {
      "id": "device-uuid-1",
      "name": "Chrome on MacBook Pro",
      "device_type": "browser",
      "browser": "Chrome",
      "os": "macOS",
      "last_used_at": "2025-01-15T10:30:00Z",
      "last_ip": "192.168.1.1",
      "is_current": true,
      "trusted": true,
      "created_at": "2025-01-10T08:00:00Z"
    },
    {
      "id": "device-uuid-2",
      "name": "Safari on iPhone",
      "device_type": "mobile",
      "browser": "Safari",
      "os": "iOS",
      "last_used_at": "2025-01-14T15:20:00Z",
      "last_ip": "10.0.0.50",
      "is_current": false,
      "trusted": true,
      "created_at": "2025-01-12T12:00:00Z"
    }
  ],
  "total": 2
}

Response Fields

Field	Type	Description
`id`	`string`	Device identifier
`name`	`string`	Device display name
`device_type`	`string`	`browser`, `mobile`, `desktop`, `cli`
`browser`	`string`	Browser name
`os`	`string`	Operating system
`last_used_at`	`string`	Last activity timestamp
`last_ip`	`string`	Last known IP address
`is_current`	`boolean`	True if this is the current session’s device
`trusted`	`boolean`	Device is trusted (MFA remembered)
`created_at`	`string`	First seen timestamp

GET /api/user/devices/:id

Get details for a specific device.

Path Parameters

Parameter	Type	Description
`id`	`string`	Device ID

Example Request

curl -X GET https://sso.example.com/api/user/devices/device-uuid-1 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK)

{
  "id": "device-uuid-1",
  "name": "Chrome on MacBook Pro",
  "device_type": "browser",
  "browser": "Chrome",
  "browser_version": "120.0.0",
  "os": "macOS",
  "os_version": "14.2",
  "last_used_at": "2025-01-15T10:30:00Z",
  "last_ip": "192.168.1.1",
  "last_location": {
    "city": "San Francisco",
    "country": "US"
  },
  "is_current": true,
  "trusted": true,
  "risk_score": 0.1,
  "created_at": "2025-01-10T08:00:00Z"
}

PATCH /api/user/devices/:id

Update a device’s display name.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Device must belong to user

Path Parameters

Parameter	Type	Description
`id`	`string`	Device ID

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	New device display name

Example Request

curl -X PATCH https://sso.example.com/api/user/devices/device-uuid-1 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Work Laptop"
  }'

Response (200 OK)

{
  "id": "device-uuid-1",
  "name": "Work Laptop",
  "device_type": "browser",
  "updated_at": "2025-01-15T10:35:00Z"
}

DELETE /api/user/devices/:id

Revoke access for a specific device. Invalidates all sessions from this device.

Synopsis

Property	Value
Authentication	Required (JWT)
Authorization	Device must belong to user
Idempotent	Yes

Path Parameters

Parameter	Type	Description
`id`	`string`	Device ID

Example Request

curl -X DELETE https://sso.example.com/api/user/devices/device-uuid-2 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK)

{
  "message": "Device access revoked"
}

Errors

Status	Code	Condition
`400`	`BAD_REQUEST`	Cannot revoke current device
`404`	`NOT_FOUND`	Device not found
`403`	`FORBIDDEN`	Device belongs to another user

Notes

Cannot revoke the current session’s device
User must use logout endpoint for current session
All refresh tokens for this device are invalidated

Device Trust

Trusted Devices

Trusted devices can bypass MFA for a configurable period:

Trust is established after successful MFA verification
Trust duration is organization-configurable (default: 30 days)
Users can revoke trust by revoking the device

Risk Scoring

Each device has a risk score (0.0 - 1.0) based on:

Factor	Impact
New device	+0.3
Unknown location	+0.2
Unusual login time	+0.1
VPN/Proxy detected	+0.1
Failed attempts	+0.2 per failure

High-risk devices (score > 0.7) may trigger additional verification.