PingAM

Rename registered devices over REST

AM 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, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/customers/realms/europe.

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 named bjensen in a realm called alpha:

    $ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/users/bjensen/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 "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \
--data '{
    "deviceName": "Work Laptop"
}' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/users/bjensen/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 lists the bound devices for a user named bjensen in a realm called alpha:

    $ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/users/bjensen/devices/2fa/binding?_queryFilter=true'
{
  "result": [
    {
      "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "_rev": "192142989",
      "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 "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \
--data '{
    "deviceName": "Work Phone"
}' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/users/bjensen/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.