# Manage devices

Mosaic provides a solution for managing devices as part of identity management. In this article, you'll learn how to implement basic device management tasks, such as identifying a returning device or deleting a device that is no longer in use. For more about the Device entity concept, see [How devices work](/guides/user/how_devices_work).

Note
This guide explains how to manage users' devices using Admin Portal and [journeys](/guides/journeys_intro).

## View devices

You can view devices in the Admin Portal (**Admin Portal** > **B2C Identity** or **B2B Identity** > **Users** > user > **Devices**). In the Admin Portal, switch between two views:

- **Device** view includes device entity-related data: device type, device ID, display name, status, last authentication timestamptetc.
- **Device keys** view includes details on the cryptographic keys residing on the devices and enriched with Fraud Prevetion data: device type, vendor device ID coming from the Fraud Prevetion (if available), browser, last activity, status, custom data, etc.


Additional details such as hardware model, OS, browser, and registration metadata (IP address, region) are also stored when available and can be obtained from the [journey context](/guides/orchestration/concepts/devices#device-context).

![Devices in Admin Portal](/assets/admin-portal-user-devices.4c1d0e7f049d197ba0dedeecd300415cf2e18825185c0f87d46933433f50f74e.2397ab79.png)

## Configure device limits

To configure device registration limits for an application, go to **Applications** > your app > **Advanced settings** > **Device limits**. In the Admin Portal, this section appears below **Token signing keys**.

For each device type, configure both cleanup behavior and the maximum number of registered devices allowed per user:

- **Web** provides **Allow auto deletion** and **Max web devices per user**. Auto deletion is enabled by default and the default limit is `10`.
- **Mobile** provides **Allow auto deletion** and **Max mobile devices per user**. Auto deletion is disabled by default and the default limit is `10`.
- Both maximum fields accept values from `1` to `100`.


Use **Delete device-bound authenticators** to control how automatic cleanup handles authenticators linked to a removed device:

- When enabled (default), device-bound authenticators are deleted, other authenticators are unlinked, and the removed device's device keys are deleted.
- When disabled, linked authenticators are unlinked but not deleted, and the device keys remain.


Note
Limits are enforced separately for web and mobile devices. Automatic cleanup only targets devices of the same type as the device currently being registered.

## Register device

Add a new device entity and establish a strong association between a device and a user using crypto-binding. After authenticating a user or onboarding a new user, include the [Register or Update Device](/guides/orchestration/journeys/register_device) step in the journey. During device registration, the SDK generates a cryptographic key pair on the device without requiring user interaction—though you can request the user's consent if needed. The device's public key is then exported and sent to Mosaic, while the private key remains securely on the device. As a result, Mosaic creates a Device entity. The step returns the `device_id`, which uniquely identifies the Device entity. You can provide it externally or let the SDK generate it.

If your application enforces device limits, registration applies those limits automatically. Depending on the configuration for the current device type, Mosaic either removes an older device of the same type or fails the registration.

Important
Registering a device should generally occur after user authentication to avoid associating devices with unconfirmed user identities. The only exception is during user onboarding, when the user and device are registered together.

If you're interested in recognizing devices before authentication, Mosaic Fraud Prevention collects various telemetry data, including device fingerprint. See [Secure device identity with Fraud Prevention](/guides/risk/secure_device_identity).

### Use case example: registering a new device

In the example journey below, the [Register or Update Device](/guides/orchestration/journeys/register_device) step is added after password authentication. After registering a device, Mosaic returns a `device_id` and associates a device with the logged-in user.

figure
a
img
figcaption
Click to open the image in a dedicated tab.
## Identify returning device

Identifying known devices early in a journey enhances security and allows you to build tailored user experiences. To check if this is a returning device, add the [Known Device Status](/guides/orchestration/journeys/validate_device) step to your journey. This step checks if the device is registered to a specific user in the app and branches based on the device's status.

The validation process involves Mosaic matching a user with a device and issuing a challenge to the client to sign using the private key stored on the user's device. This process is handled implicitly by the client SDK and no user interaction is required. If the device is recognized, the step returns the device information, populates journey context, and branches as follows:

- **Yes** (Known): the device is registered and associated with the user. The journey can proceed normally.
- **No**: the device is not associated with this user, is suspended, or an error occurred. You can design the journey to register the device, prompt additional verification, or reject access.


Note
The device can be recognized as known even if you haven't registered it using the [Register or Update Device](/guides/orchestration/journeys/register_device) journey step. Other Mosaic services, such as Fraud Prevention, can also perform device binding as part of an integration.

You can use this step as part of two-factor authentication, leveraging something the user has (their device) in addition to something the user knows (such as a password). You can also use it to elevate trust for known devices and reduce user friction.

### Use case example: login from registered devices only

For example, your app allows logging in via registered devices only. Add the [Known Device Status](/guides/orchestration/journeys/validate_device) step after the [Collect Information](/guides/orchestration/journeys/get_info_from_client) step.

Note
To identify a known device, the journey needs the user identifier. You can obtain it in several ways:

- After authenticating the user with [Login form](/guides/orchestration/journeys/login_form) and subsequent steps. In this case, the [user auth state](/guides/orchestration/concepts/users) is "authenticated" and the journey obtains the `user_id` from the user context.
- By collecting an identifier with [Collect information](/guides/orchestration/journeys/get_info_from_client) step.
- By storing a user identifier in the client SDK using the [Save Data in SDK](/guides/orchestration/journeys/store_data_on_sdk) step in a previous journey and returning it using `@policy.sdkSavedData()`.


Since the user isn't known yet, set the user authentication state to "The user is not authenticated", and have the journey obtain a user identifier provided in a previous step.

If the device is recognized and active, the journey allows the user to proceed to login. If the user tries to access the app from an unknown device, the journey rejects access.

figure
a
img
figcaption
Click to open the image in a dedicated tab.
## Enrich device info

Mosaic allows you to enrich the Device entity with additional data. This can be helpful if you're looking for a way to provide a customized user experience depending on which device the user is currently using. You can configure journeys to read information from the device entity and proceed accordingly.

### Use case example: adding data about a device

For example, a user wants to distinguish between their devices. To provide a user-friendly name for the current user's device, add the following steps to the journey:

Note
The journey assumes the user has already authenticated in the previous steps.

1. Start by validating if the device is registered to the **authenticated** user by adding [Known Device Status](/guides/orchestration/journeys/validate_device). If the device is recognized, the device information becomes available in the journey.
2. Add the [Collect information](/guides/orchestration/journeys/get_info_from_client) step to collect input from the user. For example, add the `device_name` string field to the schema. Once the user submits the name, it will be stored as `device_name` in the output variable `clientData`.
3. Add the [Register or Update Device](/guides/orchestration/journeys/register_device) step to update the device entity. Set `device_info.device.device_id` as Device ID and `clientData.device_name` as Display name.


figure
a
img
figcaption
Click to open the image in a dedicated tab.
### Use case example: reading device data

For example, a user wants to distinguish between their devices. To display a device name for the current user's device, add the following steps to the journey:

Note
The journey assumes the user has already authenticated in the previous steps.

1. Start by validating whether the device is registered to the **authenticated** user by adding [Known Device Status](/guides/orchestration/journeys/validate_device). If the device is recognized, the step returns information about the device.
2. Add the [Condition](/guides/orchestration/journeys/condition) step to act depending on the device name returned by the previous step. For example, to check if the device name is "My work cellphone", use `device_info.device.display_name == "My work cellphone"` expression. Alternatively, check for a device type (`device_info.device.device_type == "mobile"`) and branch accordingly.
3. Display "It's a work cellphone" using the [Display Information](/guides/orchestration/journeys/display_information) step if true.


figure
a
img
figcaption
Click to open the image in a dedicated tab.
## Pass device context to authentication

All authentication journey steps accept a **Device source**. By default, authentication steps pick up the `device_id` from journey context automatically after any device operation earlier in the journey. You can also provide it explicitly.

When device information is available, Mosaic records the `device_id` and device ownership (`user-owned` or `non-user-owned`) alongside every authentication event. Authentication outcome is not affected — device context enriches observability and enables adaptive logic.

### Use case example: detecting logins from unknown devices

For example, you want to surface an extra verification step when a user's password is used from a device not registered to their account.

Note
The journey assumes a Device entity was registered for the user in a previous journey.

1. Add [Known Device Status](/guides/orchestration/journeys/validate_device) right after the [Login Form](/guides/orchestration/journeys/login_form). This populates the `device` object in journey context, including the `device_id`.
2. Add the [Password Authentication](/guides/orchestration/journeys/authenticate_password) step. The journey proceeds to it irrespective of device status. The **Device source** (including `device_id`) is obtained from the journey.
3. Add a [Condition](/guides/orchestration/journeys/condition) step that checks whether the logged-in user matches the device owner (`@policy.userContext().user_id == device_info.device.user_id`). If yes, complete the journey. If the user logged in from a new device, route the journey to notify them about the unknown device and add an additional OTP verification step before completing.


figure
a
img
figcaption
Click to open the image in a dedicated tab.
## Count user devices

Keeping an inventory of devices linked to a user is helpful if you want to enforce policies, such as limiting the number of devices per user or implementing a single-device policy. The [Get User Devices](/guides/orchestration/journeys/get_user_devices) step returns a list of a user's devices with information about each device.

### Use case example: verifying the number of devices linked to a user

For example, your company is about to enforce a single-device policy. Before limiting access from multiple devices, you might want to let users check how many devices they have and display their names. Add the following steps to your journey to count user devices and act accordingly, depending on the result.

Note
The journey assumes the user has already authenticated in the previous steps.

1. Add the [Get User Devices](/guides/orchestration/journeys/get_user_devices) step to retrieve a list of all devices for a user. The step requires a user identifier as an input. Since the user has already authenticated, the journey holds information about the user in the user context. This step returns an array of Device objects filtered by user.
2. Add the [Condition](/guides/orchestration/journeys/condition) step to evaluate the output. In this example, the `@std.len(userDevices) == 1` condition checks whether the user has exactly one linked device, based on the result returned by the previous journey step. Depending on the output, you can customize a message for the user.


figure
a
img
figcaption
Click to open the image in a dedicated tab.
## Suspend device

Suspending devices is crucial for establishing strong security and privilege management. You might want to permanently restrict a malicious device from accessing your app resources, or temporarily suspend an employee's work device while not in use.

Add the [Suspend Device](/guides/orchestration/journeys/suspend_device) step to your journey, or suspend devices directly in the Admin Portal. Suspending a device changes its status to **Suspended** and also blocks its linked device cryptographic keys and locks device-bound authenticators (mobile biometrics and PIN).

Unlike deleting a device, suspending a device keeps the Device entity associated with the user. A suspended device is visible in the Admin Portal and can be discovered using the [Get User Devices](/guides/orchestration/journeys/get_user_devices) journey step. Suspended devices fail validation performed by [Known Device Status](/guides/orchestration/journeys/validate_device)—they are routed to the No branch rather than the success path. Suspended devices can also be reactivated if necessary.

## Reactivate device

When a suspended device needs to be restored, for example, when a lost device is recovered or a temporary restriction is lifted, use the [Reactivate Device](/guides/orchestration/journeys/reactivate_device) step or reactivate directly in the Admin Portal. This restores the device to the Active status, activates its linked device cryptographic keys, and unlocks its device-bound authenticators that were locked as a result of the suspension. Authenticators that were independently locked before the device was suspended remain locked.

## Forget device

Deleting a device is the final step in its identity lifecycle. Deleting irrelevant devices enhances security and provides visibility into identity management. For example, you might want to delete a device that is no longer in the user's possession, or if you enforce a single device policy that doesn't allow users to access your app from several devices.

The [Delete Device](/guides/orchestration/journeys/delete_device) step removes the Device entity from the user record. The next time the user tries to log in from this device, it will appear as new. Optionally, you can also delete device-bound authenticators (mobile biometrics and PIN) linked to the device.

Automatic cleanup triggered by **Device limits** is configured separately from the **Delete Device** step. Depending on the **Delete device-bound authenticators** setting, automatic cleanup can either delete device-bound authenticators and device keys for the removed device or leave authenticators unlinked.

### Use case example: single device policy

The example journey ensures the user can only have one device by registering a new device and removing the other device.

Note
The journey below assumes the user has already authenticated earlier in the journey.

1. Start by validating if the device is registered to the **authenticated** user by adding [Known Device Status](/guides/orchestration/journeys/validate_device). If the device is recognized and active, the journey completes.
2. In the case of a new device, retrieve the user's other devices. Add the [Get User Devices](/guides/orchestration/journeys/get_user_devices) step to retrieve a list of all devices for a user. This step returns a `userDevices` array of Device objects filtered by user.
3. Add the [Condition](/guides/orchestration/journeys/condition) step to evaluate the output. In this example, the `@std.len(userDevices) > 0` condition is used to check if the user has another device linked to their account.
4. Remove the previously registered device by adding the [Delete Device](/guides/orchestration/journeys/delete_device) step. Specify the device IDs to delete using the `let extractDeviceId = (device) => device.device_id return @std.map(userDevices, extractDeviceId)` expression.
5. If there are no devices associated with the user, register the current device with the [Register or Update Device](/guides/orchestration/journeys/register_device) step.


figure
a
img
figcaption
Click to open the image in a dedicated tab.
## Next steps

Create adaptive device management flows based on risk assessment data provided by Mosaic Fraud Prevention. See [Secure device identity](/guides/risk/secure_device_identity) for more information. Elevate trust and reduce friction for known and trustworthy devices, enforce step-up authentication in response to risky device activity, and suspend malicious devices based on risk analytics.