List registered devices over REST

PingOne Advanced Identity Cloud 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. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/alpha.

The following examples assume that you have obtained an access token with the appropriate scopes.

The API calls reference the user by _id. You can get this ID from the raw JSON for the user’s profile.

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 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",
    "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 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",
    "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 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",
      "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 /sdks/latest/sdks/use-cases/how-to-bind-devices.html[device binding^].

The following example lists the 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": "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
}