PingAM 7.5.0

List registered devices over REST

AM provides a REST API to retrieve information about 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.

List OATH devices

To return a 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 named myUser in a realm called alpha:

$ curl \
--request GET \
--header "iplanetDirectoryPro: AQIC5w…​2NzEz*" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/myUser/devices/2fa/oath?_queryFilter=true'
{
  "result" : [ {
    "_id" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
    "_rev" : "172031596",
    "deviceName" : "OATH Device",
    "uuid" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
    "deviceManagementStatus" : false
  } ],
  "resultCount" : 1,
  "pagedResultsCookie" : null,
  "totalPagedResultsPolicy" : "NONE",
  "totalPagedResults" : -1,
  "remainingPagedResults" : -1
}

List push devices

To return a 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 named myUser in a realm called alpha:

$ curl \
--request GET \
--header "iplanetDirectoryPro: AQIC5w…​2NzEz*" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/myUser/devices/2fa/push?_queryFilter=true'
{
  "result" : [ {
    "_id" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
    "_rev" : "172031596",
    "deviceName" : "Push Device",
    "uuid" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
    "deviceManagementStatus" : false
  } ],
  "resultCount" : 1,
  "pagedResultsCookie" : null,
  "totalPagedResultsPolicy" : "NONE",
  "totalPagedResults" : -1,
  "remainingPagedResults" : -1
}

List WebAuthn devices

To return a list of WebAuthn devices registered to a user, query the users/user/devices/2fa/webauthn endpoint.

The following example lists the WebAuthn devices for a user named myUser in a realm called alpha:

$ curl \
--request GET \
--header "iplanetDirectoryPro: AQIC5w…​2NzEz*" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/myUser/devices/2fa/webauthn?_queryFilter=true'
{
  "result": [
    {
      "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "_rev": "163664231",
      "deviceName": "New Security Key",
      "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "deviceManagementStatus": false
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

List bound devices

To return a list of bound devices for a user, query the users/user/devices/2fa/binding endpoint. Learn more about binding devices to a user profile in device binding.

The following example lists the bound devices for a user named myUser in a realm called alpha:

$ curl \
--request GET \
--header "iplanetDirectoryPro: AQIC5w…​2NzEz*" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/myUser/devices/2fa/binding?_queryFilter=true'
{
  "result": [
    {
      "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "_rev": "192142989",
      "createdDate": 1715182923119,
      "lastAccessDate": 1715182923183,
      "deviceId": "e2e84b5d2a927abdcb85570bac9701c390a92751",
      "deviceName": "iOS Device",
      "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "key": {
        ...
      },
      "deviceManagementStatus": false
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}