Enable user devices


Devices

To enable multi-factor authentication, the user resource must have a device associated with its user ID. PingOne supports email and SMS-capable device types for use in a multi-factor authentication flow. Multiple devices can be associated with a user ID, and devices must be in the active state to be used in the multi-factor login flow.

The devices endpoints provide operations to create, read, activate, and remove device resources associated with a specified user ID. The examples below show common actions to manage user devices. You need the Identity Data Admin role to perform operations on user resources.

Devices API operations

The devices endpoints support the following operations:

For hands-on experience with the devices API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Devices model properties

Property Description
email A string that specifies the email address, which is required only if the device type is EMAIL and must be valid.
id A string that specifies the device resource’s unique identifier.
phone The phone number, which is required only if the device type is SMS. It must be a well-formed phone number consisting of a leading plus sign, 1 to 3-digit country code, dot separator, and 4 to 14-digit phone number (e.g. +1.1234567890).
status A string that specifies the device status. Options:
  • ACTIVE
  • ACTIVATION_REQUIRED
type A string that specifies the device type which must be provided. Options:
  • EMAIL
  • MOBILE
  • SMS
user.​id A string that specifies the identifier of the user resource referenced by this relationship.

Mobile device properties

Devices whose type is MOBILE also have the following properties:

Property Description
os.type The device’s operating system.
os.version The device’s operating system version.
model.name The device’s model name.
model.marketingName The model’s marketing name.
apiVersion The mobile SDK API version.
rooted Whether the device is rooted.
lockEnabled Whether the device is lock enabled.
locale The device’s locale.
pushToken The push token for this application on this device (for internal use).
application.id the ID of the native application associated with this device.
application.nativeName The name of the application retrieved from the mobile app in runtime.
application.version The version of the application retrieved from the mobile app in runtime.
application.pushSandbox Indicates if the native application uses production or sandbox push credentials (if the app was built and installed by a developer from Xcode, or installed ad hoc).

Response codes

Code Message
200 Successful operation.
400 The request was invalid.
400 The request could not be completed.
401 You do not have access to this resource.
403 You do not have permissions or are not licensed to make this request.
404 The requested resource was not found.
500 Unexpected server error.

Filtering result data

You can filter collection results by applying a SCIM filtering expression to the request URL. For large collections, a filtering expression appended to the query returns a targeted, more useful data set. For example, the following URL-encoded SCIM filter returns a list of SMS devices that require activation:

https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/devices?filter=(status%20eq%20%22ACTIVATION_REQUIRED%22)%20and%20(type%20eq%20%22SMS%22)

SCIM operators can be applied to the following attributes:

Collection Attribute Supported operators Valid values
Devices status eq (equals) “ACTIVE”, “ACTIVATION_REQUIRED”
Devices type eq (equals) “SMS”, “EMAIL”, “MOBILE”

Endpoint examples

Get devices

The following sample shows the GET /environments/{environmentId}/users/{userId}/devices operation to return a list of all device resources associated with the specified user.

curl -X "GET" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/{userId}/devices" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
   "_links": {
       "self": {
           "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/devices"
       }
   },
   "_embedded": {
       "devices": [
           {
               "_links": {
                   "self": {
                       "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/devices/4ca9eb79-be29-4a1f-9a23-b29d58606e18"
                   },
                   "environment": {
                       "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
                   },
                   "user": {
                       "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772"
                   }
               },
               "id": "4ca9eb79-be29-4a1f-9a23-b29d58606e18",
               "environment": {
                   "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
               },
               "user": {
                   "id": "8ce55f02-2077-4493-9a6d-0385df1f0772"
               },
               "type": "SMS",
               "status": "ACTIVE",
               "createdAt": "2019-05-07T16:40:31.711Z",
               "updatedAt": "2019-05-07T16:40:31.711Z",
               "phone": "+1.5125201234"
           },
           {
               "_links": {
                   "self": {
                       "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/devices/78beb667-b275-4d88-b0af-ee9b70b518f5"
                   },
                   "environment": {
                       "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
                   },
                   "user": {
                       "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772"
                   }
               },
               "id": "78beb667-b275-4d88-b0af-ee9b70b518f5",
               "environment": {
                   "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
               },
               "user": {
                   "id": "8ce55f02-2077-4493-9a6d-0385df1f0772"
               },
               "type": "EMAIL",
               "status": "ACTIVE",
               "createdAt": "2019-05-16T20:15:48.725Z",
               "updatedAt": "2019-05-16T20:15:48.725Z",
               "email": "joe@example.com"
           }
       ]
   },
   "count": 2,
   "size": 2
}

The type property shows that this user has an EMAIL device defined for use in a multi-factor authentication flow. The status property shows that the device is ACTIVE.

If a device is inactive, the status property is set to ACTIVATION_REQUIRED and the _links property includes the activate link. The response data for an inactive device looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/devices/4f248b88-e69e-4d90-4f24-8b88e69e4d90"
        },
        "activate": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/devices/4f248b88-e69e-4d90-4f24-8b88e69e4d90"
        }
    },
    "id": "4f248b88-e69e-4d90-4f24-8b88e69e4d90",
    "environment": {
        "id": "02d37832-476a-431b-8a60-d77cecd7005c"
    },
    "user": {
        "id": "9a774ad6-b6b6-4179-af87-226cd68955f0"
    },
    "email": "joe@pingidentity.com",
    "type": "EMAIL",
    "status": "ACTIVATION_REQUIRED",
    "createdAt": "2018-07-31T19:55:14.991Z"
}

Get one device

The following sample shows the GET /environments/{environmentId}/users/{userId}/devices/{deviceId} operation return information about the device resource specified by its ID in the request URL.

curl -X "GET" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/{userId}/devices/{deviceId}" \
-H 'Authorization: Bearer jwtToken'

The following response snippet shows sample extended information for a device whose type is MOBILE:

"os": {
	  "version": "9",
	  "type": "ANDROID"
	},
	"model": {
	  "name": "SM-G950F",
	  "marketingName": "Galaxy S8"
	},
	"manufacturer": "samsung",
	"apiVersion": "1.0",
	"sdkVersion": "1.0(1438)",
	"rooted": false,
	"lockEnabled": true,
	"locale": "en-US",
	"pushToken": "****",
	"application": {
	  "id": "1e23abc1-1234-456c-987a-abc0e9871234",
	  "nativeName": "PingOneExample",
	  "version": "1.0",
	  "pushSandbox": false
	}

Create devices

The following sample shows the POST /environments/{environmentId}/users/{userId}/devices operation to add an SMS device to the specified user resource.

curl -X "POST" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/9a774ad6-b6b6-4179-af87-226cd68955f0/devices" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "type": "SMS",
  "phone": "+1.5125201234",
  "status": "ACTIVE"
}'

The status parameter is optional. Use cases:

  1. If the actor makes the request on behalf of another user, the value assigned to status can be one of:
    • ACTIVE (default, if not provided): The device is pre-paired for the user. The user is not required to activate the device before performing its first authentication.
    • ACTIVATION_REQUIRED: The user must activate the device before performing its first authentication.
  2. If the actor making the request is the same user for whom the device is created, the status can only be ACTIVATION_REQUIRED (default, if not provided). Thus in this case, a user is required to activate the device before performing its first authentication.

A valid phone number string can be provided in international format (includes a leading + character), or in any format as long as the region (country code) where the number originates can be determined. The input string is checked to determine whether it is a viable phone number (for example, whether it has too few or too many digits, cannot start with a 1) or if no country code is supplied.

The following sample shows acceptable valid phone attribute formatting for the same number:

+1.5125201234
+15125201234
+1.512.520.1234
15125201234
1-512-520-1234
+1 (512) 520-1234

The response data for the request looks like this:

{
   "_links": {
       "self": {
           "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/devices/4ca9eb79-be29-4a1f-9a23-b29d58606e18"
       },
       "environment": {
           "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
       },
       "user": {
           "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772"
       }
   },
   "id": "4ca9eb79-be29-4a1f-9a23-b29d58606e18",
   "environment": {
       "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
   },
   "user": {
       "id": "8ce55f02-2077-4493-9a6d-0385df1f0772"
   },
   "type": "SMS",
   "status": "ACTIVE",
   "createdAt": "2019-05-07T16:40:31.711Z",
   "updatedAt": "2019-05-07T16:40:31.711Z",
   "phone": "+1.5125201234"
}

Activate devices

Devices with a status of ACTIVATION_REQUIRED are activated using a valid one-time password (OTP). The OTP is sent to the phone number or email address specified in the device resource’s properties.

The following sample shows the POST /environments/{environmentId}/users/{userId}/devices/{deviceId} operation to activate the device specified in the request URL. This operation uses the application/vnd.pingidentity.device.activate+json custom content type in the request header to specify the activation action.

curl -X "POST" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/9a774ad6-b6b6-4179-af87-226cd68955f0/devices/4f248b88-e69e-4d90-4f24-8b88e69e4d90" \
-H 'Content-type: application/vnd.pingidentity.device.activate+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "otp": "123456"
}'

When the activation action is completed successfully, the response returns a 200 OK message and the device status property is changed to ACTIVE.

Delete devices

Devices are deactivated by deleting the device. The following sample shows the DELETE /environments/{environmentId}/users/{userId}/devices/{deviceId} operation to remove the device specified in the request URL.

curl -X "DELETE" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/9a774ad6-b6b6-4179-af87-226cd68955f0/devices/4f248b88-e69e-4d90-4f24-8b88e69e4d90" \
-H 'Authorization: Bearer jwtToken'

When the device is removed successfully, the response returns a 204 Successfully deleted message.