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 are ACTIVE and ACTIVATION_REQUIRED.
type A string that specifies the device type which must be provided. Options are SMS and EMAIL.
user.​id A string that specifies the identifier of the user resource referenced by this relationship.

Response codes

Code Message
200 Successful operation.
400 The request was invalid.
401 You weren’t authenticated to perform this operation.
403 You lack either the necessary permissions or the licensing to perform this operation.
404 The specified object doesn’t exist.
500 Unexpected server error.

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 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data 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"
        }
    },
    "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": "ACTIVE",
    "createdAt": "2018-07-31T19:55:14.991Z"
}

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 to 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 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

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"
}'

Note: 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/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/devices/458a5f81-fd1d-4f8c-458a-5f81fd1d4f8c"
        }
    },
    "id": "458a5f81-fd1d-4f8c-458a-5f81fd1d4f8c",
    "environment": {
        "id": "02d37832-476a-431b-8a60-d77cecd7005c"
    },
    "user": {
        "id": "9a774ad6-b6b6-4179-af87-226cd68955f0"
    },
    "phone": "+1.5125201234",
    "type": "SMS",
    "status": "ACTIVE",
    "createdAt": "2018-07-31T20:14:05.035Z"
}

If the actor is making the request on behalf of another user, the status can be one of: ACTIVE (default, if not provided), ACTIVATION_REQUIRED. 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).

Note: An actor making a self request must have an access token that includes the p1:create:self:device scope.

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 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \

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