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

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.

$ 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
}

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:

$ 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
}

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

Rename push devices

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.

$ 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
}

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:

$ 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
}

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

Rename WebAuthn devices

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.

$ 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
}

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:

$ 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": {
    ...
  }
}

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

Rename bound devices

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.

$ 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
}

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:

$ 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": {
    ...
  }
}

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

PingOne Advanced Identity Cloud

Rename registered devices over REST

Rename OATH devices

Rename push devices

Rename WebAuthn devices

Rename bound devices