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 (MFA bypass)

Endpoints Summary

Method	Path	Description
`GET`	`/api/user/devices`	List user’s devices (paginated)
`GET`	`/api/user/devices/:device_id`	Get specific device details
`PATCH`	`/api/user/devices/:device_id`	Update device display name
`POST`	`/api/user/devices/:device_id/revoke`	Revoke specific device access
`POST`	`/api/user/devices/:device_id/trust`	Manually mark device as trusted
`POST`	`/api/user/devices/revoke-all`	Revoke all devices except current

Data Models

User Device Object

{
  "id": "device-uuid-1",
  "device_name": "Chrome on macOS",
  "first_seen_at": "2025-01-10T08:00:00Z",
  "last_used_at": "2025-01-15T10:30:00Z",
  "expires_at": "2025-02-15T10:30:00Z",
  "registration_ip": "192.168.1.1",
  "risk_score": 0.15,
  "is_trusted": true
}

List Devices

GET /api/user/devices

List all devices associated with the current user with pagination support.

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`sort_by`	string	`last_seen_at`	Sort field: `last_seen_at`, `name`, `created_at`
`sort_order`	string	`desc`	Sort order: `asc`, `desc`

Example Request:

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

Response (200 OK):

{
  "devices": [
    {
      "id": "device-uuid-1",
      "device_name": "Chrome on macOS",
      "first_seen_at": "2025-01-10T08:00:00Z",
      "last_used_at": "2025-01-15T10:30:00Z",
      "expires_at": "2025-04-15T10:30:00Z",
      "registration_ip": "192.168.1.1",
      "risk_score": 15,
      "is_trusted": true
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

Get Device Details

GET /api/user/devices/:device_id

Retrieve detailed information for a specific device.

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",
  "device_name": "Chrome on macOS",
  "first_seen_at": "2025-01-10T08:00:00Z",
  "last_used_at": "2025-01-15T10:30:00Z",
  "expires_at": "2025-04-15T10:30:00Z",
  "registration_ip": "192.168.1.1",
  "risk_score": 15,
  "is_trusted": true
}

Update Device Name

PATCH /api/user/devices/:device_id

Update the display name for a device to make it easier to recognize.

Request Body:

Field	Type	Required	Description
`device_name`	string	Yes	New name for the device

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 '{
    "device_name": "Work MacBook Pro"
  }'

Revoke Device

POST /api/user/devices/:device_id/revoke

Permanently revoke access for a specific device. This invalidates all sessions and refresh tokens associated with this device.

Request Body:

Field	Type	Required	Description
`reason`	string	No	Optional reason for revocation

Example Request:

curl -X POST https://sso.example.com/api/user/devices/device-uuid-1/revoke \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -d '{"reason": "Device lost"}'

Response (200 OK):

{
  "message": "Device has been revoked",
  "success": true
}

Mark as Trusted

POST /api/user/devices/:device_id/trust

Manually mark a device as trusted and extend its trust expiration. Trusted devices can bypass MFA for 90 days.

Example Request:

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

Revoke All Devices

POST /api/user/devices/revoke-all

Revoke access for all devices associated with the user account, except for the current active session.

Example Request:

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

Response (200 OK):

{
  "message": "1 devices have been revoked",
  "success": true
}

Device Trust & Risk

Trusted Devices

A device becomes “trusted” when:

It passes MFA verification and the user selects “Remember this device”
An administrator manually trusts the device via the API

Trust Duration: 90 days from the last trust operation or manual extension.

Risk Scoring

AuthOS calculates a risk score for every device interaction based on:

Heuristics: Age of device, frequency of use, and consistency of IP address.
Location: Geolocation anomalies (impossible travel).
History: Previous failed login attempts or suspicious activity.

Risk scores range from 0 (low risk) to 100 (high risk). Scores above 70 typically trigger mandatory MFA even on trusted devices.