Devices

The device concept plays an integral part in journeys. When your applications run on devices, they interact with the journeys and can influence the execution logic and UX.

By recognizing devices early in the journey, Mosaic can provide tailored identity experiences and foster the app's security posture. For example, users accessing an application from a recognized, secure device may experience a streamlined login process, while those connecting from an unrecognized or suspicious device may be prompted for additional verification steps.

In Mosaic, a Device entity is a logical endpoint that represents any device a user authenticates from — a specific mobile app installation or browser instance. This includes physical devices like smartphones and tablets running native apps, as well as browsers such as Chrome or Safari on desktop or mobile.

Each device is identified by a device_id. During registration, this identifier can be provided by Mosaic Fraud Prevention, another provider, or generated by the Orchestration SDK. If no external identifier is supplied, the SDK-generated ID is used as the fallback device_id.

Mosaic supports two device types:

• Mobile: smartphones and tablets running native apps
• Web: browsers such as Chrome or Safari accessing your web domain

Device identity is scoped per user and application. The same physical device used by two different users, or to access two different apps, produces separate Device entities. For example, a user accessing the Acme app from their Android phone and through Chrome on their laptop will have two Device entities for the Acme app. If the same device is used to access multiple apps, Mosaic maintains separate Device entities for each.

Devices are identified by the device_id, which is set when a device is created through the Register or Update Device journey step.

The Register or Update Device journey step also performs crypto-binding: the client SDK generates a cryptographic key pair on the device and exports the public key to Mosaic. The device_key_id is the identifier of this device cryptographic key and shouldn't be used to represent device entity.

To learn more about how devices work in Mosaic, see Device management.

Applications can configure a Device limits section in Advanced settings with separate limits for Web and Mobile devices. When a new device is registered, Mosaic checks only devices of the same type.

• If Allow auto deletion is enabled for that type, Mosaic removes the least recently used device of the same type and continues registration. The least recently used evaluation takes successful authentication and successful device validation into account.
• If Allow auto deletion is disabled for that type, registration fails.
• Delete device-bound authenticators controls whether automatic cleanup deletes device-bound authenticators and device keys for the removed device or only unlinks authenticators without deleting them or the device keys.

After any device operation in a journey (register, known device check, suspend, reactivate, delete, or get user devices), Mosaic outputs device information and makes it accessible via the journey context. You can use this context to build conditional logic — for example, routing the journey differently depending on device type, status, or how recently the device was last used.

{
  "device_key_id":"string",
  "device": {
    "user_id":"string",
    "device_id":"string",
    "status":"string",
    "display_name":"string",
    "device_type":"string",
    "hardware_model":"string",
    "os":"string",
    "browser":"string",
    "registered_ip":"string",
    "registered_region":"string",
    "last_authenticated":"string",
    "last_auth_attempt":"string",
    "created_at":"string",
    "updated_at":"string"
}
}

All authentication journey steps accept the Device context and can either obtain it from the journey itself or you can provide a device ID. Mosaic records device ID and device ownership (user-owned or non-user-owned) alongside every authentication. Authentication outcome is not affected, the parameter enriches observability and enables building adaptive logic based on device signals.

Integrate device recognition and management logic into journeys to:

• Create a customized user experience
• Use the device as a "something you have" factor in multi-factor authentication
• Enforce security policies, such as a single device policy
• Manage risks
• Enrich activity logs with device context

Below are journey steps that operate on devices. For detailed instructions on how to perform common device management tasks, see Manage devices.

• Register or Update Device: Creates (or updates) a device entity, cryptographically binds the device to the user, and enforces the application's device-limit settings when creating a new device. Returns both the device_key_id (identifier of device cryptographic key) and the device object.
• Known Device Status: Checks if the device is associated with the user. Returns the device_key_id and device object. Branches into Yes (known) or No (unknown).
• Suspend Device: Suspends a device so it can no longer be used in journeys. Also blocks linked device cryptographic keys and locks device-bound authenticators.
• Reactivate Device: Restores a suspended device to Active, activates its linked device cryptographic keys, and unlocks its device-bound authenticators.
• Delete Device: Removes a device from the user record and optionally deletes linked device-bound authenticators and the linked device cryptographic keys (unless associated with a different user)
• Get User Devices: Retrieves a list of devices associated with a user.