--- title: MFA Device Authentications description: Initiate and complete PingOne MFA device authentication actions such as device selection, OTP validation, and assertion checks component: pingone-api page_id: pingone-api:mfa:mfa-authentication/mfa-device-authentications/index canonical_url: https://developer.pingidentity.com/pingone-api/mfa/mfa-authentication/mfa-device-authentications/index.html llms_txt: https://developer.pingidentity.com/pingone-api/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2026-08-11 section_ids: device-authentication-with-pingid-desktop: Device authentication with PingID Desktop device-authentications-data-model: Device authentications data model device-authentication-events-generated: Device authentication events generated --- # 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 authentication with PingID Desktop Authentication using PingID Desktop involves a sequence of requests and responses, including interaction with the Desktop API: 1. Send an Initiate Device Authentication request to the `deviceAuthentications` endpoint, providing the [ID of the user](initiate-device-authentication-desktop.html) or the [relying party ID](initialize_device_authentication_usernameless.html). 2. The response form the PingOne server contains a field called `pingIdDesktopCredentialRequestOptions`, which consists of a signed JWT. 3. Send a request to the Desktop API endpoint `http://localhost:9410/authenticate`. The body should consist of the JWT that was received from the PingOne server. 4. The response from the desktop agent will contain an assertion JWT. 5. Send a [Check Assertion request](check-assertion-desktop.html) to the `deviceAuthentications` endpoint, using the relevant header. The body of the request should consist of a field called `assertion`, whose value should be the JWT that was returned from the desktop agent. 6. The PingOne server returns a success response. ## 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. | | `assertion` | String | Required | Immutable | During the process of authenticating using the PingID Desktop application, you must send a request to the Desktop API's `authenticate` endpoint. The response from the desktop agent contains an assertion JWT. You must then send a request to the PingOne `deviceAuthentications` endpoint, with the body of the request consisting of the `assertion` field whose value should be the JWT that was returned from the desktop agent. | | `createdAt` | Date | N/A | Immutable | When the resource was created. | | `enrollment` | Object | N/A | Read-only | Included in the response to a device authentication initialization request when the Auto Enrollment option is enabled in the relevant MFA policy and the request contains the parameters required for auto-enrollment, `application.id` and `mobilePayload`. | | `enrollment.pairingKey` | String | N/A | Read-only | The pairing key that the end user should use to pair their device. | | `enrollment.pairingKeyId` | String | N/A | Read-only | The ID of the pairing key resource. | | `enrollment.status` | String | N/A | Read-only | Indication of whether the pairing key was generated and returned successfully. Value returned will be `SUCCESS` or `FAILED`. | | `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. | | `origin` | String | Required | Immutable | For authentication with the PingID Desktop application, when you make the second call to the PingOne server and include the assertion that was provided by the desktop agent, you must also include `origin` in the body of the request. The value should be a subdomain of the domain that was specified as the Relying Party ID in the MFA policy or the domain that was specified with `rp.id` in the initial call to the PingOne server. The format used should be a complete URL, for example, `https://app.pingone.eu`. | | `pingIdDesktopCredentialRequestOptions` | String | N/A | Read-only | During the process of authenticating with the PingID Desktop application, you initiate the process by sending a request to the PingOne `deviceAuthentications` endpoint. The response to the request contains a field called `pingIdDesktopCredentialRequestOptions`, which consists of a signed JWT. You then include the returned JWT in the subsequent request to the Desktop API's `authenticate` endpoint. | | `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](cancel_authentication.html) 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 example.com. If not provided, the relying party ID is taken from the associated FIDO2 policy. For authentication with the PingID Desktop application, the relying party ID is taken by default from the relevant MFA policy. However, you have the option of including `rp.id` in the body of the initial call to the PingOne server if you would like to override the value from the MfA policy with a different domain. | | `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](../../../platform/reference/audit-reporting-events.html) for the events generated.