Work with 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 service provides 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. For more information, see Work with user roles.

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

Add 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": "+972.503392962"
}'

Note: A valid phone number string consists of a leading plus sign (+), one to three-digit country code, dot separator (.), four to fourteen-digit phone number, and an optional one to eight-digit extension. The following sample shows a valid phone attribute value with a four-digit extension:

+1.3034682900x1234

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/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": "+972.503392962",
    "type": "SMS",
    "status": "ACTIVE",
    "createdAt": "2018-07-31T20:14:05.035Z"
}

If the actor making the request is an administrator creating the device for another user, the device is created with a status of ACTIVE. If the actor making the request is the same as the user for whom the device is created, the device is created with a status of ACTIVATION_REQUIRED.

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

Activate a device

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.

Remove a device

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.