TrustedDevice

Manages devices that users have marked as trusted to bypass two-factor authentication requirements. When a user successfully logs in with 2FA from a device, they can choose to 'Remember this device' or 'Trust this device for 30 days', which creates a trusted device record. This significantly improves user experience by not requiring 2FA on every login from frequently-used devices like their personal laptop or phone, while still maintaining security on unknown devices. The system creates a unique fingerprint for each device using various characteristics like browser type, operating system, screen resolution, and installed plugins - making it difficult for attackers to impersonate a trusted device. Trust can be time-limited (expires after 30 days) or revoked manually by the user or automatically if suspicious activity is detected. Users can view and manage all their trusted devices from their security settings, seeing details like when each device was last used and from what location. This feature balances security with usability, similar to how banks remember your computer but still require extra verification from new devices.

22 properties

Schema

Properties

Property	Type	Mode	Description	Required
deviceId	uuid	stored	Unique identifier for this trusted device	Required
userId	uuid	stored	User who has trusted this device	Required
deviceName	string	stored	User-friendly name for the device Example: `"John's MacBook Pro"`	Required
deviceType	string	enum	Category of the trusted device Values: `desktop, laptop, mobile, tablet, browser, api_client, smart_tv, wearable`	Required
deviceFingerprint	string	stored	Unique fingerprint combining multiple device characteristics	Required
userAgent	string	stored	Browser user agent string for device identification	Optional
operatingSystem	string	stored	Operating system name and version Example: `"macOS 14.2"`	Optional
browser	string	stored	Browser name and version Example: `"Chrome 121.0.6167.184"`	Optional
ipAddress	string	stored	Last known IP address of the device	Optional
location	string	stored	Approximate geographic location Example: `"San Francisco, CA, USA"`	Optional
trustedAt	DateTime	stored	When the device was first trusted	Required
trustedUntil	DateTime	stored	When the trust expires (null for permanent trust)	Optional
lastUsedAt	DateTime	stored	Most recent activity from this device	Optional
lastVerifiedAt	DateTime	stored	Last time the device passed trust verification	Optional
usageCount	integer	stored	Number of times this device has been used for login	Optional
isActive	boolean	stored	Whether the device is currently trusted	Optional
revokedAt	DateTime	stored	When trust was revoked for this device	Optional
revokedReason	string	stored	Why the device trust was revoked	Optional
riskScore	integer	stored	Calculated risk level for this device (0-100)	Optional
metadata	object	stored	Additional device characteristics and flags	Optional
createdAt	DateTime	stored	When this record was created	Required
updatedAt	DateTime	stored	Last modification of this record	Optional

Examples

Example 1

{
  "@type": "TrustedDevice",
  "deviceId": "dev_550e8400",
  "userId": "user_123456",
  "deviceName": "Sarah's Work Laptop",
  "deviceType": "laptop",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  "operatingSystem": "macOS 14.2",
  "browser": "Chrome 121.0.6167.184",
  "ipAddress": "192.168.1.100",
  "location": "New York, NY, USA",
  "trustedAt": "2024-01-15T10:00:00Z",
  "trustedUntil": "2024-04-15T10:00:00Z",
  "lastUsedAt": "2024-03-15T08:30:00Z",
  "lastVerifiedAt": "2024-03-15T08:30:00Z",
  "usageCount": 145,
  "isActive": true,
  "riskScore": 5,
  "metadata": {
    "screenResolution": "2560x1440",
    "colorDepth": 24,
    "timezone": "America/New_York",
    "language": "en-US"
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-03-15T08:30:00Z"
}

Example 2

{
  "@type": "TrustedDevice",
  "deviceId": "dev_mobile_789",
  "userId": "user_456789",
  "deviceName": "iPhone 14 Pro",
  "deviceType": "mobile",
  "userAgent": "MyApp/2.5.0 (iPhone; iOS 17.3)",
  "operatingSystem": "iOS 17.3",
  "browser": null,
  "ipAddress": "172.58.12.34",
  "location": "London, UK",
  "trustedAt": "2024-02-01T14:00:00Z",
  "trustedUntil": null,
  "lastUsedAt": "2024-03-14T19:45:00Z",
  "lastVerifiedAt": "2024-03-14T19:45:00Z",
  "usageCount": 89,
  "isActive": false,
  "revokedAt": "2024-03-15T09:00:00Z",
  "revokedReason": "User manually revoked after device was lost",
  "riskScore": 0,
  "metadata": {
    "appVersion": "2.5.0",
    "deviceModel": "iPhone15,2",
    "biometricEnabled": true,
    "jailbroken": false
  },
  "createdAt": "2024-02-01T14:00:00Z",
  "updatedAt": "2024-03-15T09:00:00Z"
}