---
title: Device self-service in JavaScript apps
description: Learn how to manage user authentication devices, such as renaming or deleting them, in your JavaScript applications using the Ping Identity SDK.
component: orchsdks
page_id: orchsdks:journey:use-cases/device-self-service/javascript-device-self-service
canonical_url: https://developer.pingidentity.com/orchsdks/journey/use-cases/device-self-service/javascript-device-self-service.html
revdate: Fri, 20 Feb 2026 16:09:20 +0100
keywords: ["PingOne Advanced Identity Cloud", "PingAM", "Journeys", "JavaScript", "Device Management", "MFA", "FIDO", "WebAuthn", "OATH", "Push", "SDK"]
section_ids:
  android_device-profile_modules: Installing modules
  initializing_the_device_client: Initializing the device client
  listing_registered_devices: Listing registered devices
  renaming_devices: Renaming devices
  deleting_devices: Deleting devices
---

# Device self-service in JavaScript apps

[icon: circle-check, set=far]PingOne Advanced Identity Cloud [icon: circle-check, set=far]PingAM [icon: js, set=fab]JavaScript

The **Device Client** module for JavaScript provides a comprehensive and unified API for managing Multi-Factor Authentication (MFA) devices and user profile devices registered with Advanced Identity Cloud or PingAM servers.

The module simplifies the process of retrieving, updating, and deleting various types of authentication devices, enabling you to build secure and user-friendly device management experiences within your JavaScript applications.

## Installing modules

The **Device Client** client module for JavaScript as available as an **npm** module at [@forgerock/device-client](https://www.npmjs.com/package/@forgerock/device-client?activeTab=readme).

To install the module into your JavaScript project, run the following `npm` command:

```shell
npm install @forgerock/device-client@2.0.0
```

After installation, import the `deviceClient` module and `ConfigOptions` type into your app as follows:

```typescript
import { deviceClient } from '@forgerock/device-client';
import type { ConfigOptions } from '@forgerock/device-client/types';
```

## Initializing the device client

The **Device Client** module uses the REST-based device management endpoints provided by Advanced Identity Cloud and PingAM.

The **Device Client** module requires the session token when making calls to the device management endpoints. In a JavaScript app, the session cookie is automatically attached to outgoing calls to the REST API.

Session tokens often have a short duration and might expire after 5 minutes. If the client does not have an active session token you should trigger an authentication journey to obtain a new session token before attempting to manage registered devices.

The following code shows how to initialize the device client module after authenticating a user and obtaining their session token:

Initializing a device client on JavaScript

```javascript
const config: ConfigOptions = {
  serverConfig: {
    baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am',
  },
  realmPath: 'alpha',
};

const deviceClient = deviceClient(config);
```

The configuration properties for the device client are as follows:

**Device client parameters on JavaScript**

| Parameter                         | Description                                                                                                                                                                       | Required? |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `serverConfig/baseUrl` (*String*) | The base URL of your server.- Advanced Identity Cloud example

  `https://openam-forgerock-sdks.forgeblocks.com/am`

- PingAM example

  `https://openam.example.com:8443/openam` | Yes       |
| `realmPath` (*String*)            | The authentication realm.- Advanced Identity Cloud example

  `alpha`

- PingAM example

  `root`                                                                                 | Yes       |

## Listing registered devices

For each type of registered device you can call the `devices()` method to retrieve a list from the server. Pass the ID of the user whose device you want to list in the `userId` parameter, and the realm in the `realm` parameter.

* Advanced Identity Cloud example

  ```json
  {
    userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
    realm: 'alpha'
  }
  ```

  |   |                                                                                                                             |
  | - | --------------------------------------------------------------------------------------------------------------------------- |
  |   | Advanced Identity Cloud references users by their `_id` value.You can get this ID from the raw JSON for the user's profile. |

* PingAM example

  ```json
  {
    userId: 'demo',
    realm: 'root'
  }
  ```

The available types of device are as follows:

**Getting lists of registered devices by type on JavaScript**

| Registered device type         | Listing method                |
| ------------------------------ | ----------------------------- |
| WebAuthn / FIDO authenticators | `deviceClient.webAuthn.get()` |
| Bound devices                  | `deviceClient.bound.get()`    |
| Profiled devices               | `deviceClient.profile.get()`  |
| Push MFA devices               | `deviceClient.push.get()`     |
| OATH MFA devices               | `deviceClient.oath.get()`     |

Each method returns a promise for improved error handling and functional programming support.

The different device types return different relevant information that you can access and display to the user as appropriate, such as the current name or when the device was last used.

The following code shows how to obtain lists of the different devices from the server:

* WebAuthn / FIDO

* Bound devices

* Profiled devices

* Push devices

* OATH devices

Listing WebAuthn devices on JavaScript

```javascript
const webAuthnQuery: WebAuthnQuery = {
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha',
};

const devices = await apiClient.webAuthn.get(webAuthnQuery);
console.log('WebAuthn Devices:', devices);
```

Listing bound devices on JavaScript

```javascript
const bindingQuery: GetBoundDevicesQuery = {
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha',
};

const devices = await apiClient.bound.get(bindingQuery);
console.log('Bound Devices:', devices);
```

Listing Profiled devices on JavaScript

```javascript
const profileQuery: GetProfileDevices = {
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha',
};

const devices = await apiClient.profile.get(profileQuery);
console.log('Device Profiles:', devices);
```

Listing Push devices on JavaScript

```javascript
const pushQuery: PushDeviceQuery = {
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha',
};

const devices = await apiClient.push.get(pushQuery);
console.log('Push Devices:', devices);
```

Listing OATH devices on JavaScript

```javascript
const oathQuery: RetrieveOathQuery = {
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha',
};

const devices = await apiClient.oath.get(oathQuery);
console.log('Oath Devices:', devices);
```

## Renaming devices

You can rename registered devices and update the user's account with the new details by using the `update()` method.

You'll need to identify the device to update by using the `device` query parameter. You can obtain an array of device objects from the call to `get()` earlier.

You also need to specify the owner of the device in the `userId` parameter, and the realm in the `realm` parameter. The **Device Client** module uses these parameters to form the REST endpoint it uses for device management.

For example, the following code renames a registered bound device that has the UUID `ee19db01-7c1a-41b3-971b-646341189d42`:

Renaming a bound device on JavaScript

```typescript
const updateBoundQuery = {
  userId: 'ee19db01-7c1a-41b3-971b-646341189d42',
  realm: 'alpha',
};

const updatedDevice = await apiClient.bound.update({
  ...updateBoundQuery,
  device: { ...device, deviceName: 'My Updated Device Name' },
});

if ('error' in updatedDevice) {
  console.error(`Failed to update device: ${updatedDevice.error}`);
}

console.log('Updated bound device', updatedDevice);
```

|   |                                                                                                                                                                                                                                                                                                                                                        |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|   | All update operations automatically include an `If-Match: *` HTTP header.This header is used for optimistic concurrency control to prevent conflicts when multiple clients attempt to modify the same device simultaneously.The wildcard `*` value allows updates regardless of the current ETag, ensuring the update succeeds if the resource exists. |

## Deleting devices

You can delete or deregister a device, with the caveat that the authentication journey that provided the users' session must fulfill one or more of the following criteria:

* Used same multi-factor authentication method as the device you want to delete.

  For example, to delete a WebAuthn device the authentication journey that created the session must also authenticate using a WebAuthn device.

* Used the [Enable Device Management node](https://docs.pingidentity.com/auth-node-ref/latest/enable-device-management.html) that alters the **Device Check Enforcement Strategy**.

Use the `delete()` method to delete a device from the user's profile.

You'll need to identify the device to update by using the `device` query parameter. You can obtain an array of device objects from the call to `get()` earlier.

You also need to specify the owner of the device in the `userId` parameter, and the realm in the `realm` parameter. The **Device Client** module uses these parameters to form the REST endpoint it uses for device management.

Deleting a Push authenticator device on JavaScript

```typescript
const deletePushQuery = {
  userId: 'ee19db01-7c1a-41b3-971b-646341189d42',
  realm: 'alpha',
};

const deletedDevice = apiClient.push.delete({
  ...deletePushQuery,
  device,
});

if (deletedDevice !== null && deletedDevice.error) {
  console.error(`Failed to delete device: ${deletedDevice.error}`);
}

console.log('Device deleted', deletedDevice);
```