PingOne Advanced Identity Cloud

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.

It’s not possible to rename OATH or push devices.

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.

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

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

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

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