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.
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).
In most cases, the default device is automatically used for authentication. However, there are two exceptions:
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.
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.
If the default (first) device is deleted, the second active device on the order list becomes the default device.
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.
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.
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:
|
type |
Immutable A string that specifies the device type which must be provided. Options:
|
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. |
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. |
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. |
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:
|
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. |
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} . |
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 ). |
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. |
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. |
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.
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. |