To enable multi-factor authentication (MFA), the user resource must have an MFA method associated with its user ID. PingOne supports email, SMS, voice, TOTP authenticator application, and native application method types for use in an MFA flow. Multiple MFA methods can be associated with a user ID. MFA methods must be in the active state to be used in the multi-factor login flow.

With this API, MFA methods are called MFA devices. The devices endpoints provide operations to manage device resources associated with a specified user ID. You need the Identity Data Admin role to perform operations on device resources.

Device order

With the release of the device order feature (Jan 11, 2021), the active devices of most users now have an order (first…last). By default, the order is according to the device activation time (oldest…newest). Each subsequently activated device is appended to the end of the order list. The first device on the list is designated the default device. In most cases, the default device is automatically used for authentication; users no longer need to select a device.

There are a small number of users whose devices do not have a default order with this feature. If a user has more than one active device as of the release of the device order feature, the current active devices and subsequently activated devices have no order. The user therefore has no default device and must choose a device each time they authenticate. In this case, the order must be explicitly set (see Setting device order).

Cases where the default device is not used for authentication

In most cases, the default device is automatically used for authentication. However, there are two exceptions:

• If authenticating from a native app and device authorization is enabled, the native device is used for seamless authentication (see Automatic device authorization under PingOne MFA Native SDK Flows).
• If the user is paired with a FIDO2 platform device and a session token cookie exists on the browser, the FIDO2 platform device is used for authentication even if it is not the default device.

Setting device order

The operation POST /environments/{{envID}}/users/{{userID}}/devices with required header Content-type: application/vnd.pingidentity.devices.reorder+json explicitly orders a user’s existing active devices according to the request body. The active device listed first becomes the default device.

After this operation explicitly sets device order, subsequently activated devices are appended to the end of the order list. You can use this operation to explicitly reorder active devices as many times as needed.

Retrieving an ordered list of devices

The operation GET /environments/{{envID}}/users/{{userID}}/devices returns the list of active devices sorted in their order, with the default device listed first. Devices with a status of ACTIVATION_REQUIRED are listed after the active devices, in no particular order. If devices have no order, GET /environments/{{envID}}/users/{{userID}}/devices returns the list of devices in no particular order.

You can expand the GET /environments/{{envID}}/users/{{userID}}/devices results with the expand=order query parameter. The response is then expanded to contain an array of activated device IDs listed according to device order. If devices have no order, an empty array is returned.

Deleting a default device

If the default (first) device is deleted, the second active device on the order list becomes the default device.

Removing device order

The operation POST /environments/{{envID}}/users/{{userID}}/devices with required header Content-type: application/vnd.pingidentity.devices.order.remove+json removes the ordering on a user’s active devices. With the execution of this operation, the user no longer has a default device.

Custom device pairing notification with device creation

To send a custom device pairing notification when a new email, SMS or voice device is created, add the notification property to the request body of POST /environments/{{envID}}/users/{{userID}}/devices. The status of the created device must be ACTIVATION_REQUIRED.

{
    “notification”: {
        “template”: {
            “locale”: “en”,
            “variant”: “variant_B”
            "variables": {
                        "sum": "1,000,000",
                        "currency": "USD",
                        "recipient": "Charlie Parker"
            }
       }
    }
}

When the device is created, a request is executed to select the content for the notification. The notification template is device_pairing. The deliveryMethod is Email, SMS or Voice, depending on the device created. The locale, variant, and all dynamic variables are defined in notification.

For more information on content selection, see Runtime logic for content selection. For more information on dynamic varables, see Dynamic variables.

Device failure in flows

When the flow returns a NO_USABLE_DEVICES error, and the user has devices that are temporarily unavailable (for example, the device is locked because of too many invalid OTP retries), the IDs of these devices are returned as part of the response.

In the flow response, the status property returns FAILED, and the error message includes the NO_USABLE_DEVICES error code. The following samples show common error messages for a device failure with identified unavailableDevices:

"status": "FAILED",
    "error": {
        "code": "NO_USABLE_DEVICES",
        "message": "Couldn't find authenticating device for user: {{userID}}",
      "unavailableDevices": [
            {
                "id": "edccc773-6f31-4d28-a8e1-0f427d9a9df8"
            }
        ]
    },

"status": "FAILED",
    "error": {
        "code": "NO_USABLE_DEVICES",
        "message": "Daily limit of SMS authentication attempts has been exceeded",
        "unavailableDevices": [
            {
                "id": "7ea99e29-6f8f-42be-af75-232588235e30"
            }
        ]
    },

Device properties {#device-properties}

EMAIL device properties

Devices whose type is EMAIL also have the following properties:

SMS/Voice device properties

Devices whose type is SMS or VOICE also have the following properties:

Native device properties

Devices whose type is MOBILE also have the following properties:

Time-based One-time Password (TOTP) authenticator application device properties {#totp-model}

Devices whose type is TOTP also have the following properties:

FIDO2 devices {#fido2-devices}

Devices whose type is FIDO2 also have the following properties:

PLATFORM and SECURITY_KEY webauthn device data model (deprecated, replaced by FIDO2 devices)

Devices whose type is PLATFORM or SECURITY_KEY also have the following properties:

Device order properties

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Response codes

Filtering result data

You can filter GET /environments/{{envID}}/users/{{userID}}/devices 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.

SCIM operators can be applied to the following attributes:

The logical operators and and or can also be used to combine filter statements.

For example, the following URL-encoded SCIM filter returns a list of SMS devices that require activation:

{{apiPath}}/environments/{{envID}}/users/{{userID}}/devices?filter=(status%20eq%20%22ACTIVATION_REQUIRED%22)%20and%20(type%20eq%20%22SMS%22)

This URL returns the device that matches the information contained in the specified payload from the PingOne Mobile SDK:

{{apiPath}}/environments/{{envID}}/users/{{userID}}/devices?filter=mobilePayload eq "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImRlNjJjZWYxLWQzNmQtNGMxMC05NDBkLTczNzQzZDk5NmYxZiJ9.eyJpc3MiOiIyNjdmNmEwMC1iZjg2LTQ4ODUtYjRjMi1mYjg5YzUzNzVlNGYiLCJmbnAiOiJiMDY4YjI2YTNhZTI2MTRmIiwiZHZjIjoiZGU2MmNlZjEtZDM2ZC00YzEwLTk0MGQtNzM3NDNkOTk2ZjFmIiwiZXhwIjoxNjg3OTQ4MTY1NTkwLCJqdGkiOiI1M2FlMmQ5YS04NmZiLTRmNGQtYjFlYS04M2MzMDQwNWU2OWEifQ.LxPIyD1mmdkXRLUmt2z3Fjeryev9b5oPgJGR2M5QxcuRR-tnd9nKNVB37CyS0W5Hj926W2U-MoSgpldvPM6-anpM4w4Ywa0a65_FB7PA0tzv-5LI4Pduat5fxhG78PTVRLXF_bwMe1hopUEFu6MBcKj13LIjz-rcrHIMoQV3OWUH5caX4mV3FXx1FPxoB-3Ighcc0-SotO4JZXvpZk2vsD-P2XJ1lFf-N2QhXnwfmBy7WthuPDCU8Rc6_a0Ca2cnv1bWDAKUKkndEsqm6S0_VFpLueCVxmHKdSy98owh86SAVhGtoZeHfOTB7WEbOb9aCAH_AinEh-JEhLKn_hMO3w"

Expanding result data

You can expand GET /environments/{{envID}}/users/{{userID}}/devices results with the expand=<value> query parameter. The following value is supported.

Related topics