The /deviceAuthentications endpoint initiates and completes an MFA action without requiring a call to the PingOne authorize service. It supports actions to select a supported MFA device device type and to validate a one-time passcode (OTP).

When a device authentication MFA flow is initiated, the flow returns a status property in the response that identifies the next action in the flow. The following flow states prompt for a specific flow action:

Device authentications data model

Property Type? Required? Mutable? Description
user.id String Required Mutable The requesting user’s unique identifier.
createdAt Date N/A Immutable When the resource was created.
updatedAt Date N/A Immutable When the resource was last updated.
_embedded.devices Array N/A Read-only The list of authenticating devices.
error Object N/A Read-only The error field indicating the reason for a device authentication failure.
error.code String N/A Read-only The error code.
error.message String N/A Read-only The error message.
id String N/A Read-only The resource’s unique identifier.
mobilePayload String N/A Read-only The JSON that is the result of a getMobilePayload call (mobile app to mobile SDK).
application.id String Optional Mutable The requesting application’s unique identifier. This identifier is required only during device authorization flows when the mobilePayload value is provided.
notification Object Optional Immutable Holds dynamic notification data.
notification.template Object Optional Immutable Holds dynamic template data.
notification.template.name String Optional Immutable The notification template name.
notification.template.variant String Optional Immutable The notification template variant.
notification.template.locale String Optional Immutable The notification template locale.
notification.template.variables Map Optional Immutable The notification template variables.
notification.clientContext Object Optional Immutable Holds dynamic mobile push data.
policy.id String Optional Mutable The device authentication policy ID.
publicKeyCredentialRequestOptions String N/A Read-only A JSON serialization of the client data passed on registration only.
selectedDevice.id String Optional Mutable The unique identifier of a user’s MFA device. You can use this property to specify that authentication should be carried out with a specific device if the user has more than one.
selectedDevice.oneTime.type String Optional Mutable For organizations that prefer to maintain their own user device information, you can use the oneTime object to specify how the user should be contacted. The type property indicates the method that should be used for contacting the user. The value can be SMS, VOICE, or EMAIL. If you are using the oneTime object, you should not include the selectedDevice.id property.
selectedDevice.oneTime.phone String Optional Mutable If selectedDevice.oneTime.type is set to SMS or VOICE, use the phone property to provide the user’s phone number.
selectedDevice.oneTime.email String Optional Mutable If selectedDevice.oneTime.type is set to EMAIL, use the email property to provide the user’s email address.
selectedDevice.oneTime.testMode Boolean Optional Mutable To simplify automated testing of your applications, you can create dedicated testing devices. When you use the API to send authentication requests to such a device, the OTP is not sent to the actual device, but instead is returned as part of the body of the response. To specify that a one-time device should serve as a testing device, set the value of testMode to true. If this parameter is not provided, the default value is false. For dedicated testing devices, the response includes the OTP value in the field test.otp.
test.otp String Optional Immutable If you are using a test device or you used the testMode parameter to specify that a one-time device should serve as a testing device, the response includes the OTP value in the field test.otp.
rp.id String Optional Mutable The ID of the relying party, used for logging in without having to provide a username. The value of the field should be a domain name, such as sample.com. Note that by default the usernameless authentication feature can be used for platform-based FIDO2 authentication. If you want to enable this feature for security key-based FIDO2 authentication, you must go to the relevant policy on the FIDO Policies page in the PingOne admin console, and change the FIDO resident key setting to Required. The feature will be enabled for any devices that are paired after this setting has been changed.
status String N/A Read-only The flow status. Options are DEVICE_SELECTION_REQUIRED, PUSH_CONFIRMATION_REQUIRED, PUSH_CONFIRMATION_TIMED_OUT, OTP_REQUIRED, ASSERTION_REQUIRED, COMPLETED, and FAILED.