User Devices

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

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:

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:

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:

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:

1. It passes MFA verification and the user selects “Remember this device”
2. 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.