To enable multi-factor authentication (MFA), the user resource must have an MFA method associated with its user ID. PingOne supports email, SMS, TOTP authenticator application, and mobile 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:

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 or SMS 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 either Email or SMS, 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 properties

Property Description
attestation A read-only string that specifies public key and signed challenge used to complete registration and device activation. Devices with a status of ACTIVATION_REQUIRED are activated using a valid attestation and origin. The attestation is generated by the browser as a response to a specific user action, such as a fingerprint or clicks on the security key. This is a required property for FIDO2 device activation.
environment.id Immutable A string that specifies the environment ID associated with the device resource.
id Immutable A string that specifies the device resource’s unique identifier.
origin A read-only string that specifies the originating server (for example, https://apps.pingone.com). This property and the attestation property are used to activate FIDO2 devices that have a status of ACTIVATION_REQUIRED. This is a required property for FIDO2 device activation.
status Immutable A string that specifies the device status. Options:
  • ACTIVE
  • ACTIVATION_REQUIRED
type Immutable A string that specifies the device type which must be provided. Options:
  • EMAIL
  • MOBILE
  • SMS
  • TOTP (third-party TOTP authenticator applications)
  • PLATFORM (FIDO2 bound biometrics devices)
  • SECURITY_KEY (FIDO2 or U2F security key devices)
user.​id Immutable A string that specifies the identifier of the user resource referenced by this relationship.
nickname Mutable User-defined string that identifies the authentication method in the UI. If defiined, this string also appears on the authentication screens. This property has a limit of 100 characters. All characters are supported. An empty string is also supported to delete the value. Use PUT /environments/{envID}/users/{userID}/devices/{deviceID}/nickname to set this property.

EMAIL device properties

Devices whose type is EMAIL also have the following properties:

Property Description
email Immutable A string that specifies the email address, which is required during POST only if the device type is EMAIL. The email address must be valid.
notification Immutable An optional object that contains notification information. When this property is supplied during device creation, the information within is used to create a custom device pairing notification. For more information, see Custom device pairing notification with device creation.
notification.template Immutable An object that contains template parameters.
notification.template.locale Immutable The ISO language code (string) used for the device created notification. For example, en.
notification.template.variant Immutable The unique user-defined name for the content variant that contains the message text used for the notification. For more information on variants, see Creating custom contents.
notification.template.variables Immutable An object of key:value pairs that defines the dynamic variables used by the content variant. For more information on dynamic variables, see Dynamic variables.

SMS device properties

Devices whose type is SMS also have the following properties:

Property Description
phone Immutable 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).
notification Immutable An optional object that contains notification information. When this property is supplied during device creation, the information within is used to create a custom device pairing notification. For more information, see Custom device pairing notification with device creation.
notification.template Immutable An object that contains template parameters.
notification.template.locale Immutable The ISO language code (string) used for the device created notification. For example, en.
notification.template.variant Immutable The unique user-defined name for the content variant that contains the message text used for the notification. For more information on variants, see Creating custom contents.
notification.template.variables Immutable An object of key:value pairs that defines the dynamic variables used by the content variant. For more information on dynamic variables, see Dynamic variables.

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).
logs.status The returned status of a request for logs from a particular user device. Possible values:
  • PENDING: The request for logs was issued. When the user connects to the app, it will send the logs.
  • RECEIVED: The logs were sent from the device, and received.
logs.expiresAt The date and time the request for expires, if the logs have not been sent yet. The value is set at 24 hours from the time of the request, and remains only while the logs.status is PENDING. logs.expiresAt is reset when the logs are sent, or when the system date reaches the request’s expiry time.

Time-based One-time Password (TOTP) authenticator application device properties

Devices whose type is TOTP also have the following properties:

Property Description
secret A string that specifies the unique secret key shared by the prover (token) and the verifier (authentication server).
keyUri A string that specifies the authenticator key URI (for example, otpauth://totp/abc@example.com?secret={secretValue}.

PLATFORM and SECURITY_KEY webauthn device data model

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

Property Description
platformType A string that specifies the type of platform associated with this MFA device. Options are BIOMETRICS, WINDOWS, ANDROID, MACINTOSH, and IPHONE. This property applies only to devices in which the type property is set to PLATFORM.
publicKeyCredentialCreationOptions A JSON serialization of the client data returned for registering a FIDO2 device with the webauthn navigator.credentials.create API. For more information, see FIDO2 Biomentrics Devices.
rp.id A string that specifies the relying party identifier, which is based on a host’s domain name but without a scheme or port (for example, acme.com or login.acme.com).
rp.name A string that specifies the relying party’s human-readable display name (for example, acme).

Device order properties

Property Description
order[] An array of objects that determines the explicit order of a user’s devices. The first device listed becomes the default device. This property is used as a body parameter to set the order of existing devices.

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 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. 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”, “TOTP”, “MOBILE”, “PLATFORM”, “SECURITY_KEY”

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

Expanding result data

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

Value Description
order The response is expanded to contain an array of activated device IDs listed according to device order. This value is relevant only if the devices are ordered. If devices are not ordered, and empty array is returned. For more information, see Setting device order.