---
title: Rename registered devices over REST
description: Advanced Identity Cloud provides a REST API to rename MFA devices registered to a user.
component: pingoneaic
page_id: pingoneaic:am-authentication:rename-mfa-devices
canonical_url: https://docs.pingidentity.com/pingoneaic/am-authentication/rename-mfa-devices.html
section_ids:
  rename_oath_devices: Rename OATH devices
  rename_push_devices: Rename push devices
  rename_webauthn_devices: Rename WebAuthn devices
  rename_bound_devices: Rename bound devices
---

# Rename registered devices over REST

Advanced Identity Cloud provides a REST API to rename MFA devices registered to a user.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm. Prefix each realm in the hierarchy with the `realms/` keyword. For example, `/realms/root/realms/alpha`.

## Rename OATH devices

1. Obtain a list of the user's registered OATH devices.

   To retrieve the list of OATH devices registered to a user, query the `users/user/devices/2fa/oath` endpoint.

   The following example lists the OATH devices for a user in the `alpha` realm. The user's `_id` in this example is `014c54bd-6078-4639-8316-8ce0e7746fa4`.

   ```bash
   $ curl \
   --request GET \
   --header "authorization: Bearer access-token" \
   'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/oath?_queryFilter=true'
   {
     "result" : [
       {
         "_id" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
         "_rev" : "172031596",
         "createdDate": 1749572704744,
         "lastAccessDate": 1749658650801,
         "deviceName" : "OATH Device",
         "uuid" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
         "deviceManagementStatus" : false
       }
     ],
     "resultCount" : 1,
     "pagedResultsCookie" : null,
     "totalPagedResultsPolicy" : "NONE",
     "totalPagedResults" : -1,
     "remainingPagedResults" : -1
   }
   ```

2. Rename the required OATH device by sending an HTTP PUT request to the `users/user/devices/2fa/oath/device-id` endpoint, including the ID of the OATH device you want to rename. Specify the new `deviceName` in the PUT body:

   ```bash
   $ curl \
   --request PUT \
   --header "Accept-API-Version: resource=1.0" \
   --header "Content-Type: application/json" \
   --header "authorization: Bearer access-token" \
   --data '{
       "deviceName": "Work YubiKey"
   }' \
   'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/oath/ff1db8bf-d2d7-46e1-926a-568b877f87a5'
   {
     "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
     "_rev": "1642022518",
     "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
     "createdDate": 1749572704744,
     "lastAccessDate": 1749658650801,
     "deviceName" : "Work YubiKey",
     "deviceManagementStatus" : false
   }
   ```

3. Repeat step 2 to rename additional OATH devices for the user, if needed.

## Rename push devices

1. Obtain a list of the user's registered push devices.

   To retrieve the list of push devices registered to a user, query the `users/user/devices/2fa/push` endpoint.

   The following example lists the push devices for a user in the `alpha` realm. The user's `_id` in this example is `014c54bd-6078-4639-8316-8ce0e7746fa4`.

   ```bash
   $ curl \
   --request GET \
   --header "authorization: Bearer access-token" \
   'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/push?_queryFilter=true'
   {
     "result" : [
       {
         "_id" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
         "_rev" : "172031596",
         "createdDate": 1749572704744,
         "lastAccessDate": 1749658650801,
         "deviceName" : "Push Device",
         "uuid" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
         "deviceManagementStatus" : false
       }
     ],
     "resultCount" : 1,
     "pagedResultsCookie" : null,
     "totalPagedResultsPolicy" : "NONE",
     "totalPagedResults" : -1,
     "remainingPagedResults" : -1
   }
   ```

2. Rename the required push device by sending an HTTP PUT request to the `users/user/devices/2fa/push/device-id` endpoint, including the ID of the push device you want to rename. Specify the new `deviceName` in the PUT body:

   ```bash
   $ curl \
   --request PUT \
   --header "Accept-API-Version: resource=1.0" \
   --header "Content-Type: application/json" \
   --header "authorization: Bearer access-token" \
   --data '{
       "deviceName": "Work YubiKey"
   }' \
   'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/push/ff1db8bf-d2d7-46e1-926a-568b877f87a5'
   {
     "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
     "_rev": "1642022518",
     "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
     "createdDate": 1749572704744,
     "lastAccessDate": 1749658650801,
     "deviceName" : "Work iPhone",
     "deviceManagementStatus" : false
   }
   ```

3. Repeat step 2 to rename additional push devices for the user, if needed.

## Rename WebAuthn devices

1. Retrieve a list of WebAuthn devices associated with a user by querying the `users/user/devices/2fa/webauthn` endpoint.

   The following example retrieves a list of WebAuthn devices for a user in the `alpha` realm. The user's `_id` in this example is `014c54bd-6078-4639-8316-8ce0e7746fa4`.

   ```bash
   $ curl \
   --request GET \
   --header "authorization: Bearer access-token" \
   'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/webauthn?_queryFilter=true'
   {
     "result": [
       {
         "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
         "_rev": "163664231",
         "createdDate": 1749572704744,
         "lastAccessDate": 1749658650801,
         "credentialId": "XGJpYNYv4AHG9sHHgxFfTw",
         "deviceName": "New Security Key",
         "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
         "deviceManagementStatus": false
       }
     ],
     "resultCount": 1,
     "pagedResultsCookie": null,
     "totalPagedResultsPolicy": "NONE",
     "totalPagedResults": -1,
     "remainingPagedResults": -1
   }
   ```

2. Rename the required WebAuthn device for the user by sending an HTTP PUT request to the `users/user/devices/2fa/webauthn/device-id` endpoint, including the ID of the WebAuthn device you want to rename. Specify the new `deviceName` in the PUT body:

   ```bash
   $ curl \
   --request PUT \
   --header "Accept-API-Version: resource=1.0" \
   --header "Content-Type: application/json" \
   --header "authorization: Bearer access-token" \
   --data '{
       "deviceName": "Work Laptop"
   }' \
   'https://<tenant-env-fqdn>/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/webauthn/ff1db8bf-d2d7-46e1-926a-568b877f87a5'
   {
     "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
     "_rev": "1642022518",
     "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
     "recoveryCodes": [
       ...
     ],
     "createdDate": 1749572704744,
     "lastAccessDate": 1749658650801,
     "credentialId": "XGJpYNYv4AHG9sHHgxFfTw",
     "algorithm": "SHA256withECDSA",
     "deviceName": "Work Laptop",
     "signCount": 0,
     "key": {
       ...
     }
   }
   ```

3. Repeat step 2 to rename additional WebAuthn devices for the user, if needed.

## Rename bound devices

1. Retrieve a list of bound devices for a user by querying the `users/user/devices/2fa/binding` endpoint.

   The following example retrieves a list of bound devices for a user in the `alpha` realm. The user's `_id` in this example is `014c54bd-6078-4639-8316-8ce0e7746fa4`.

   ```bash
   $ curl \
   --request GET \
   --header "authorization: Bearer access-token" \
   'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/binding?_queryFilter=true'
   {
     "result": [
       {
         "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
         "_rev": "163664231",
         "createdDate": 1749572704744,
         "lastAccessDate": 1749658650801,
         "deviceId": "e2e84b5d2a927abdcb85570bac9701c390a92751",
         "deviceName": "iOS Device",
         "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
         "deviceManagementStatus": false
       }
     ],
     "resultCount": 1,
     "pagedResultsCookie": null,
     "totalPagedResultsPolicy": "NONE",
     "totalPagedResults": -1,
     "remainingPagedResults": -1
   }
   ```

2. Rename the required bound device for the user by sending an HTTP PUT request to the `users/user/devices/2fa/binding/device-id` endpoint, including the ID of the bound device you want to rename. Specify the new `deviceName` in the PUT body:

   ```bash
   $ curl \
   --request PUT \
   --header "Accept-API-Version: resource=1.0" \
   --header "Content-Type: application/json" \
   --header "authorization: Bearer access-token" \
   --data '{
       "deviceName": "Work Phone"
   }' \
   'https://<tenant-env-fqdn>/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/binding/ff1db8bf-d2d7-46e1-926a-568b877f87a5'
   {
     "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
     "_rev": "1642022518",
     "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
     "recoveryCodes": [
       ...
     ],
     "createdDate": 1749572704744,
     "lastAccessDate": 1749658650801,
     "deviceId": "e2e84b5d2a927abdcb85570bac9701c390a92751",
     "deviceName": "Work Phone",
     "signCount": 0,
     "key": {
       ...
     }
   }
   ```

3. Repeat step 2 to rename additional bound devices for the user, if needed.