PingOne Platform APIs

MFA Device Authentications

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:

  • OTP_REQUIRED

    For a status value of OTP_REQUIRED, the otp.check action validates the one-time passcode.

  • DEVICE_SELECTION_REQUIRED

    For a status value of DEVICE_SELECTION_REQUIRED, the device.select action prompts the user to select a supported device type for use in a multi-factor authentication flow.

  • ASSERTION_REQUIRED

    For a status value of ASSERTION_REQUIRED, the assertion.check action validates the assertion.

  • PUSH_CONFIRMATION_REQUIRED

    For a status value of PUSH_CONFIRMATION_REQUIRED, a push was sent to the specified mobile device to confirm the authentication.

  • PUSH_CONFIRMATION_TIMED_OUT

    For a status value of PUSH_CONFIRMATION_TIMED_OUT, a push was sent to the specified mobile device, but the mobile device did not answer the push during the allowed timeframe.

Device authentications data model

Property Type? Required? Mutable? Description

aggregateFido2Devices

Boolean

N/A

Read-only

Indication of whether the available authentication method list should include only a single generic FIDO2 option rather than including an entry for each paired FIDO2 device. The field is included in the response to the request to initiate an MFA device authentication flow (POST {{authPath}}/{{envID}}/deviceAuthentications).

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.

createdAt

Date

N/A

Immutable

When the resource was created.

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). Both mobilePayload and applicationId values are required to invoke the device authorization flow using the API.

notification

Object

Optional

Immutable

Holds dynamic notification data.

notification.clientContext

Object

Optional

Immutable

Holds dynamic mobile push data.

notification.policy.id

String

Optional

Mutable

The policy ID for the notification.

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.

policy.id

String

Optional

Mutable

The device authentication policy ID.

publicKeyCredentialRequestOptions

String

N/A

Read-only

A string that specifies the public key credential request options object generated for the selected device that should be used to call the navigator.credentials.get() on the browser to generate the assertion. If you are using dynamic linking to attach a unique identifier to a FIDO transaction, publicKeyCredentialRequestOptions will include the transaction information for your records.

reason

String

Optional

Mutable

In situations where the user wants to authenticate from a different device, you can cancel an authentication flow that has begun. For such requests, the body consists of a single field, reason, and the value should be set to CHANGE_DEVICE. For details, refer to the Cancel Device Authentication example.

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. If not provided, the relying party ID is taken from the associated FIDO2 policy.

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. In responses, the value is the ID of the device that was in fact used for authentication.

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. Note that the test.otp field is included in the response for authentication requests only when using the API directly or via DaVinci. The field is not included in the API response that is sent to the PingOne user interface.

selectedDevice.otp

String

Optional

Mutable

Enables the user to enter their OTP when triggering MFA.

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.

test.otp

String

N/A

Read-only

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. Note that the test.otp field is included in the response for authentication requests only when using the API directly or via DaVinci. The field is not included in the API response that is sent to the PingOne user interface.

updatedAt

Date

N/A

Immutable

When the resource was last updated.

user.id

String

Required

Mutable

The requesting user’s unique identifier.

webAuthn.challenge

String

Optional

Immutable

If you want to use dynamic linking to attach a unique identifier to a FIDO transaction, provide a value for the webAuthn.challenge parameter. The value should be a custom challenge to replace the automatically-generated challenge sent with the authentication request. Must be a valid and unique Base64URL string that decodes to a data array of at least 32 bytes. You can generate a challenge that meets these criteria by adding a random nonce to the transaction details to ensure uniqueness and then using SHA-256 to hash the information.

_embedded.devices

Array

N/A

Read-only

The list of authenticating devices.

_embedded.devices[].otpStatus.status

String

N/A

Read-only

Whether or not the device can be used currently for OTP-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where type is MOBILE.

_embedded.devices[].otpStatus.reason

String

N/A

Read-only

If the status is DISABLED, contains the reason that the device cannot be used for OTP-based authentication, for example, that the application used a version of the MFA SDK that does not support OTP. Relevant only for devices where type is MOBILE.

_embedded.devices[].pushStatus.status

String

N/A

Read-only

Whether or not the device can be used currently for push-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where type is MOBILE.

_embedded.devices[].pushStatus.reason

String

N/A

Read-only

If the status is DISABLED, contains the reason that the device cannot be used for push-based authentication, for example, that the push option was disabled for the application in the MFA policy. Relevant only for devices where type is MOBILE.

_embedded.devices[].usableStatus.status

String

N/A

Read-only

Whether or not the device can be used currently for authentication. Value returned is ENABLED or DISABLED.

_embedded.devices[].usableStatus.reason

String

N/A

Read-only

If the status is DISABLED, contains the reason that the device cannot be used for authentication, for example, that the defined daily notifications limit has already been reached.

Device authentication events generated

Refer to Audit Reporting Events for the events generated.