PingOne

Models, objects, and error codes

When using the PingOne MFA IdP Adapter through the PingFederate authentication application programming interface (API), the adapter uses the following state models, action models, objects, and error codes:

State models

The first state the adapter returns is either AUTHENTICATION_REQUIRED or ASSERTION_REQUIRED.

ASSERTION_REQUIRED

State details
Response model
devices (array[Device])

The list of all devices associated with the user. Refer to the Device object table.

user (User)

A user. Refer to the User object table.

selectedDeviceRef (ResourceRef)

A reference to a resource using an identifier. Refer to the ResourceRef object table.

publicKeyCredentialRequestOptions (PublicKeyCredentialRequestOptions)

The PublicKeyCredentialRequestOptions object containing data necessary to generate an assertion. Refer to the PublicKeyCredentialRequestOptions object table.

manualPairing (boolean)

Indicates whether the user has initiated the MFA pairing process.

userSelectedDefault (boolean)

Indicates whether the Method Selection list in the PingOne MFA policy is set to User selected default device, Prompt user to select, or Always display devices.

changeDevicePermitted (boolean)

Indicates whether the user can switch devices used for authentication.

manageDevicesAllowed (boolean)

Indicates whether the user can add or remove MFA devices at this stage in the authentication flow.

manualPairingPermitted (boolean)

Indicates whether manual pairing is permitted at this stage in the authentication flow.

Actions

  • checkAssertion

  • selectDevice

  • cancelAuthentication

  • manageDevices

Description

Indicates that authentication is required.

AUTHENTICATION_CODE_RESPONSE_REQUIRED

State details
Response model
authenticationCodeId (string)

A string that specifies the code request ID.

code (string)

A string that specifies the code. The code is eight characters in length, and it can include numbers and uppercase letters.

uri (string)

A string that specifies a universal link such as https://www.example.com/pingonesdk?authentication_code={{generated token}}).

This property can also set a link to a schema application such as pingoneapp://pingonesdk?authentication_code={{generated token}}).

If a universal link or schema application link is not set, the response does not include the pingonesdk?authentication_code={{generated token}} portion of the URL.

userApproval (string)

An enumeration that specifies whether the mobile device must verify that the user approves the authentication with the scanned code. Options are REQUIRED and NOT_REQUIRED.

expiresAt (string)

A date that specifies the expiration time of authentication code.

updatedAt (string)

A date that specifies when the resource was last updated.

createdAt (string)

A date that specifies when the resource was created.

application (Application)

Mobile application information. Refer to the Application object table.

clientContext (ClientContext)

Provides relevant information to the mobile application that can be shown to application users. Refer to the ClientContext object table.

lifeTime (LifeTime)

Specifies the length of time for this authentication code to be valid. Refer to the LifeTime object table.

requestStatus (string)

A string that specifies the status of the authentication code. Options are UNCLAIMED or CLAIMED.

Actions

  • poll

  • cancelAuthentication

Description

The user must complete MFA using an authentication code.

There might be values that you want the client to pass to PingFederate for step-up authentication and transaction approval, such as an SMS message or an email configuration type. However, these values cannot be sent using the PingFederate Authentication API because of security concerns. You can find information on the available parameters and instructions for sending them to PingFederate in Transaction approval setup.

AUTHENTICATION_REQUIRED

State details
Response model
user (User)

A user. Refer to the User object table.

Actions

  • authenticate

  • cancelAuthentication

Description

Indicates that authentication is required.

BIOMETRIC_DEVICE_AUTHENTICATION_INFO_REQUIRED

State details
Response model

This state has no model.

Actions

  • continueBiometricDeviceAuthentication

  • cancelAuthentication

Description

The user must provide the server name where the fetch originates.

DEVICE_PAIRING_METHOD_REQUIRED

State details
Response model
devicePairingMethods (array[DevicePairingMethod])

The list of available device pairing methods for MFA. Refer to the DevicePairingMethod object table.

Actions

  • selectDevicePairingMethod

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must select a device type for MFA to proceed.

DEVICE_SELECTION_REQUIRED

State details
Response model
devices (array[Device])

The list of all devices associated with the user. Refer to the Device object table.

user (User)

A user. Refer to the User object table.

maxAllowedDevices (integer)

Indicates the maximum number of devices and authentication methods that can be added.

manualPairing (boolean)

Indicates the user has initiated the MFA pairing process.

userSelectedDefault (boolean)

Indicates whether the Method Selection list in the PingOne MFA policy is set to User selected default device, Prompt user to select, or Always display devices.

changeDevicePermitted (boolean)

Indicates whether the user can switch devices used for authentication.

newPairingAuthRequired (boolean)

Indicates whether authentication is necessary to pair a new device. Learn more in Overview of the automatic device pairing flow.

manageDevicesAllowed (boolean)

Indicates whether the user can add or remove MFA devices at this stage in the authentication flow.

manualPairingPermitted (boolean)

Indicates whether manual pairing is permitted at this stage in the authentication flow.

usePasswordAuthenticationEnabled (boolean)

Indicates whether password authentication is enabled. Learn more in the Use Password Config Attribute table entry in PingOne MFA IdP Adapter settings reference.

Actions

  • cancelAuthentication

  • selectDevice

  • usePasswordAuthentication

  • manageDevices

Description

Indicates that device selection is required, and that the user has more than one device.

UPDATE_NICKNAME

State details
Response model

This state has no model.

Actions

  • skipUpdateDeviceNickname

  • updateDeviceNickname

Description

The user can nickname their device before completing device pairing.

EMAIL_ACTIVATION_REQUIRED

State details
Response model
otp (string)

When testMode is true, the response contains and returns an OTP.

otpLifetime (Lifetime)

The lifespan of the OTP, indicating the time period for which the OTP is valid.

notification (Notification)

Indicates the time until which the user must wait before being allowed to resend the OTP.

email (string)

The user’s specified email address for MFA.

Actions

  • activateEmailDevice

  • resendOtp

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit their email activation code to complete the device pairing.

EMAIL_PAIRING_TARGET_REQUIRED

State details
Response model
allowedValue (string)

If empty, a user can enter any email or phone number. Otherwise, only a pre-defined email or phone number is allowed.

Actions

  • submitEmailTarget

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit an email address for MFA.

MFA_COMPLETED

State details
Response model
code (string)

The success code. Learn more in PingOne MFA status attributes reference.

Actions

  • continueAuthentication

Description

Indicates a successful multi-factor authentication (MFA) attempt. The API client must call continueAuthentication in order to progress in the flow, and to complete it.

MFA_DEVICE_PAIRING_METHOD_FAILED

State details
Response model
code (string)

The error code.

message (string)

The developer-facing error message.

userMessage (string)

The user-facing error message.

Actions

  • cancelDevicePairing

  • cancelAuthentication

Description

The device pairing method has failed. The device integrity check determined that the device is jailbroken (iOS) or rooted (Android).

MFA_FAILED

State details
Response model
code (string)

The error code.

message (string)

The developer-facing error message.

userMessage (string)

The user-facing error message.

secondsUntilUnlock (integer)

The number of seconds until the account is automatically unlocked. Applies only when the account is locked.

You can find more information in the MFA_FAILED codes table.
Actions

  • cancelAuthentication

Description

Indicates a dead end. The API client can proceed in the flow by calling cancelAuthentication. The adapter will return a FAILURE status.

MFA_SETUP_REQUIRED

State details
Response model

This state has no model.

Actions

  • setupMfa

  • skipMfa

  • cancelAuthentication

Description

The user must set up a device for MFA.

MOBILE_ACTIVATION_REQUIRED

State details
Response model
applicationName (string)

The name of the native application associated with this device.

pairingKey (string)

The pairing key used to pair the mobile device.

Actions

  • poll

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must activate their mobile device to complete the device pairing.

MOBILE_PAIRING_REQUIRED

State details
Response model
serverPayload (string)

The PingOne ID token.

The server payload is a data package created by the SDK server, which should be passed to the SDK component in the customer mobile application. It contains instructions for pairing.

Actions

  • continueAuthentication

Description

Indicates that mobile pairing is required.

ONE_TIME_DEVICE_OTP_METHOD_TYPE_INPUT_REQUIRED

State details
Response model
devices (array[OneTimeDeviceInfo])

The list of all one-time device OTP objects.

changeDevicePermitted (boolean)

Indicates whether the user can switch devices used for authentication.

Actions

  • selectOneTimeDeviceMethod

  • cancelAuthentication

Description

The user must select the one-time device from the list to proceed ahead with authentication flow.

ONE_TIME_DEVICE_OTP_INPUT_REQUIRED

State details
Response model
devices (array[OneTimeDeviceForResponse])

The list of all one-time device OTP objects.

selectedDevice (OneTimeDeviceForResponse)

Refer to the OneTimeDeviceForResponse object table.

otpLifetime (Lifetime)

The lifespan of the OTP, indicating the time period for which the OTP is valid.

notification (Notification)

Indicates the time until which the user must wait before being allowed to resend the OTP.

changeDevicePermitted (boolean)

Indicates whether the user can switch devices used for authentication

Actions

  • checkOtp

  • selectOneTimeDeviceMethod

  • resendOtp

  • cancelAuthentication

Description

Indicates that OTP is required. This state is returned when the user is prompted to provide an OTP. The OTP is sent to the user in an SMS, voice call, or email.

OTP_REQUIRED

State details
Response model
devices (array[Device])

The list of all devices associated with the user. Refer to the Device object table.

user (User)

A user. Refer to the User object table.

selectedDeviceRef (ResourceRef)

A reference to a resource using an identifier. Refer to the ResourceRef object table.

otp (string)

The OTP used for MFA.

otpLifetime (Lifetime)

The lifespan of the OTP, indicating the time period for which the OTP is valid.

manualPairing (boolean)

Indicates the user has initiated the MFA pairing process.

userSelectedDefault (boolean)

Indicates whether the Method Selection list in the PingOne MFA policy is set to User selected default device, Prompt user to select, or Always display devices.

changeDevicePermitted (boolean)

Indicates whether the user can switch devices used for authentication.

manageDevicesAllowed (boolean)

Indicates whether the user can add or remove MFA devices at this stage in the authentication flow.

manualPairingPermitted (boolean)

Indicates whether manual pairing is permitted at this stage in the authentication flow.

Actions

  • cancelAuthentication

  • checkOtp

  • selectDevice

  • manageDevices

Description

Indicates that one-time passcode (OTP) is required. This state is returned when the user is prompted to provide an OTP. The OTP is either:

  • Sent to the user in an SMS, voice call, or email.

  • Displayed in the user’s authenticator app.

To resend the OTP, use the selectDevice action.

PUSH_CONFIRMATION_REJECTED

State details
Response model
devices (array[Device])

The list of all devices associated with the user. Refer to the Device object table.

user (User)

A user. Refer to the User object table.

reason (string)

The reason why the push confirmation was rejected. Possible values:

  • DENIED_BY_USER

selectedDeviceRef (ResourceRef)

A reference to a resource using an identifier. Refer to the ResourceRef object table.

manualPairing (boolean)

Indicates the user has initiated the MFA pairing process.

userSelectedDefault (boolean)

Indicates whether the Method Selection list in the PingOne MFA policy is set to User selected default device, Prompt user to select, or Always display devices.

changeDevicePermitted (boolean)

Indicates whether the user can switch devices used for authentication.

manualPairingPermitted (boolean)

Indicates whether manual pairing is permitted at this stage in the authentication flow.

Actions

  • cancelAuthentication

  • selectDevice

  • manageDevices

Description

Indicates that the user rejected the push notification.

PUSH_CONFIRMATION_TIMED_OUT

State details
Response model
devices (array[Device])

The list of all devices associated with the user. Refer to the Device object table.

user (User)

A user. Refer to the User object table.

selectedDeviceRef (ResourceRef)

A reference to a resource using an identifier. Refer to the ResourceRef object table.

manualPairing (boolean)

Indicates the user has initiated the MFA pairing process.

userSelectedDefault (boolean)

Indicates whether the Method Selection list in the PingOne MFA policy is set to User selected default device, Prompt user to select, or Always display devices.

changeDevicePermitted (boolean)

Indicates whether the user can switch devices used for authentication.

manualPairingPermitted (boolean)

Indicates whether manual pairing is permitted at this stage in the authentication flow.

Actions

  • cancelAuthentication

  • selectDevice

  • checkOtp

  • manageDevices

Description

Indicates a push timeout state.

PUSH_CONFIRMATION_WAITING

State details
Response model
devices (array[Device])

The list of all devices associated with the user. Refer to the Device object table.

user (User)

A user. Refer to the User object table.

selectedDeviceRef (ResourceRef)

A reference to a resource using an identifier. Refer to the ResourceRef object table.

numberMatching (NumberMatching)

Represents the configuration for mobile authentication number matching. Refer to the NumberMatching object table.

manualPairing (boolean)

Indicates the user has initiated the MFA pairing process.

userSelectedDefault (boolean)

Indicates whether the Method Selection list in the PingOne MFA policy is set to User selected default device, Prompt user to select, or Always display devices.

changeDevicePermitted (boolean)

Indicates whether the user can switch devices used for authentication.

manageDevicesAllowed (boolean)

Indicates whether the user can add or remove MFA devices at this stage in the authentication flow.

manualPairingPermitted (boolean)

Indicates whether manual pairing is permitted at this stage in the authentication flow.

Actions

  • poll

  • cancelAuthentication

  • selectDevice

  • checkOtp

  • manageDevices

Description

Indicates that a push was sent to the user.

To get the final push confirmation state, the API client can either call the poll, or call GET.

FIDO2_ACTIVATION_REQUIRED

State details
Response model
relyingParty (RelyingParty)

A relying party. Refer to the RelyingParty object table.

publicKeyCredentialCreationOptions (string)

A JSON serialization of the client data returned for registering a FIDO2 device.

Actions

  • activateFido2Device

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must pair their FIDO2 device with the browser to complete the pairing.

SECURITY_KEY_ACTIVATION_REQUIRED

State details
Response model
relyingParty (RelyingParty)

A relying party. Refer to the RelyingParty object table.

publicKeyCredentialCreationOptions (string)

A JSON serialization of the client data returned for registering a FIDO2 device.

Actions

  • activateSecurityKeyDevice

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must pair their security key with the browser to complete the device pairing.

PLATFORM_ACTIVATION_REQUIRED

State details
Response model
relyingParty (RelyingParty)

A relying party. Refer to the RelyingParty object table.

publicKeyCredentialCreationOptions (string)

A JSON serialization of the client data returned for registering a FIDO2 device.

Actions

  • activatePlatformDevice

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must pair their biometrics with the browser to complete the device pairing.

SMS_ACTIVATION_REQUIRED

State details
Response model
otp (string)

When testMode is true, the response contains and returns an OTP.

otpLifetime (Lifetime)

The lifespan of the OTP, indicating the time period for which the OTP is valid.

notification (Notification)

Indicates the time until which the user must wait before being allowed to resend the OTP.

phone (string)

The user’s specified phone number for MFA.

Actions

  • activateSmsDevice

  • resendOtp

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit their SMS activation code to complete the device pairing.

SMS_PAIRING_TARGET_REQUIRED

State details
Response model
allowedValue (string)

If empty, a user can enter any email or phone number. Otherwise, only a pre-defined email or phone number is allowed.

Actions

  • submitSmsTarget

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit a phone number for MFA.

TOTP_ACTIVATION_REQUIRED

State details
Response model
pairingKey (string)

The pairing key used to pair the mobile device.

keyUri (string)

The URI format of the QR code.

Actions

  • activateTotpDevice

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit their authenticator activation code to complete the time-based one-time passcode (TOTP) device pairing.

VOICE_ACTIVATION_REQUIRED

State details
Response model
otp (string)

When testMode is true, the response contains and returns an OTP.

otpLifetime (Lifetime)

The lifespan of the OTP, indicating the time period for which the OTP is valid.

notification (Notification)

Indicates the time until which the user must wait before being allowed to resend the OTP.

phone (string)

The user’s specified phone number for MFA.

Actions

  • activateVoiceDevice

  • resendOtp

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit their voice activation code to complete the device pairing.

VOICE_PAIRING_TARGET_REQUIRED

State details
Response model
allowedValue (string)

If empty, a user can enter any email or phone number. Otherwise, only a pre-defined email or phone number is allowed.

Actions

  • submitVoiceTarget

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit a phone number for MFA.

WHATSAPP_ACTIVATION_REQUIRED

State details
Response model
otp (string)

When testMode is true, the response contains and returns an OTP.

otpLifetime (Lifetime)

The lifespan of the OTP, indicating the time period for which the OTP is valid.

notification (Notification)

Indicates the time until which the user must wait before being allowed to resend the OTP.

phone (string)

The user’s specified phone number for MFA.

Actions

  • activateWhatsAppDevice

  • resendOtp

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit their WhatsApp activation code to complete the device pairing.

WHATSAPP_PAIRING_TARGET_REQUIRED

State details
Response model
allowedValue (string)

If empty, a user can enter any email or phone number. Otherwise, only a pre-defined email or phone number is allowed.

Actions

  • submitWhatsAppTarget

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit a phone number for MFA.

OATH_TOKEN_PAIRING_TARGET_REQUIRED

State details
Response model

This state has no models.

Actions

  • submitOathTokenTarget

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit a valid OATH token serial number to complete the device pairing.

OATH_TOKEN_ACTIVATION_REQUIRED

State details
Response model
serialNumber (string)

The user’s specified OATH token serial number for MFA.

Actions

  • activateOathTokenDevice

  • cancelDevicePairing

  • cancelAuthentication

Description

The user must submit their OATH token activation code to complete the device pairing.

DEVICE_MANAGEMENT

State details
Response model

This state has no model.

Actions

  • setDefaultDevice

  • setupMfa

  • removeDevice

  • updateDeviceNickname

  • resumeAuthentication

  • resyncOathToken

Description

The user can add a new device, set an existing device as the default device, remove an existing device, or rename an existing device.

Action models

checkAssertion

Action details
Request model
assertion (string) (required)

A string that specifies the authenticator assertion response, which contains the signed challenge needed to complete the MFA action.

origin (string) (required)

A string that specifies the server name where the fetch originates, providing the URI scheme and hostname.

compatibility (string) (required)

A string that specifies the browser compatibility to support webauthn. Options are FULL (compatible with FIDO2 biometrics and security key), SECURITY_KEY_ONLY (compatible with security key only), and NONE (browser is not compatible with the webauthn method).

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_ASSERTION

  • Error: REQUEST_FAILED

Description

Validate the assertion from the user.

selectDevice

Action details
Request model
deviceRef (ResourceRef) (required)

The device identifier.

mobilePayload (string)

The mobile payload is a small data package created by the PingOne Mobile SDK component that identifies the device, which is used as part of the device’s authorization.

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_DEVICE, INVALID_MOBILE_PAYLOAD, or CHANGE_AUTHENTICATION_METHOD_NOT_ALLOWED.

  • Error: REQUEST_FAILED

    ErrorDetail: OTP_RESEND_LIMIT, PUSH_FAILED, or TOTP_ATTEMPTS_LIMIT.

Description

Starts an authentication attempt with the specified device ID. For example:

{
  "deviceRef":
  {
    "id": "<device ID>"
  }
}

If another authentication attempt was already in progress, that in-progress attempt is canceled before the new attempt starts.

This action is available only when the user has at least one device. It can also be used as an authentication retry.

A mobile payload is required if a user requests access from an untrusted mobile app and needs to select one of their trusted devices to approve or deny access.

To return to the DEVICE_SELECTION_REQUIRED state, you must enter a request payload such as the following:

{
    "deviceRef": {
        "id": ""
    }
}

cancelAuthentication

Action details
Request model

This action has no model.

Errors

This action has no errors.

Description

This action cancels the current authentication step.

manageDevices

Action details
Request model

This action has no model.

Errors

This action has no errors.

Description

Starts the device management flow. If Bypass MFA for Device Management Attribute isn’t enabled and the user hasn’t completed MFA yet, they’ll be prompted to do so.

poll

Action details
Request model

This action has no model.

Errors

  • Error: REQUEST_FAILED

  • Error: VALIDATION_ERROR

Description

This action returns the authentication code request status.

authenticate

Action details
Request model
mobilePayload (string)

The mobile payload is a small data package created by the PingOne Mobile SDK component that identifies the device, which is used as part of the device’s authorization.

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_MOBILE_PAYLOAD

  • Error: REQUEST_FAILED

Description

Starts an authentication flow. The mobile payload is required in cases of mobile app access. The presence or absence of the mobile payload determines whether the flow is a mobile or web authentication, respectively. You cannot switch midway between mobile and web authentication flows.

continueBiometricDeviceAuthentication

Action details
Request model
origin (string)

A string that specifies the server name where the fetch originates.

Errors

  • Error: VALIDATION_ERROR

  • Error: REQUEST_FAILED

Description

Continue with biometric device authentication.

selectDevicePairingMethod

Action details
Request model
devicePairingMethod (DevicePairingMethod)

Refer to the DevicePairingMethod object table.

Errors

  • Error: VALIDATION_ERROR

    Error detail: INVALID_DEVICE_PAIRING_METHOD

Description

Select a device pairing method to pair as a new MFA device.

cancelDevicePairing

Action details
Request model

This action has no model.

Errors

This action has no errors.

Description

Cancel the MFA pairing process.

usePasswordAuthentication

Action details
Request model

This action has no model.

Errors

  • Error: VALIDATION_ERROR

  • Error: REQUEST_FAILED

Description

Exit from the MFA authentication flow with the UsePassword policy action to proceed with the next configured adapter for this policy action in the policy tree.

skipUpdateDeviceNickname

Action details
Request model

This action has no model.

Errors

This action has no errors.

Description

Skip updating the device nickname during the device pairing flow.

updateDeviceNickname

Action details
Request model
id (string) (required)

Unique identifier of a trusted device in the PingOne MFA server.

nickname (string) (required)

The device’s nickname.

Errors

  • Error: RESOURCE_NOT_FOUND

  • Error: REQUEST_FAILED

Description

Give a unique nickname to a device.

activateEmailDevice

Action details
Request model
otp (string) (required)

The OTP submitted by the user.

Errors

  • Error: VALIDATION_ERROR

    Error detail: INVALID_OTP

  • Error: REQUEST_FAILED

    Error detail: OTP_ATTEMPTS_LIMIT

Description

Submit the email activation code to complete the device pairing.

resendOtp

Action details
Request model

This action has no model.

Errors

  • Error: REQUEST_FAILED

    Error detail: OTP_RESEND_LIMIT

Description

Resend the OTP to the previously selected device.

submitEmailTarget

Action details
Request model
testMode (boolean)

Determines whether this MFA device is configured as a test device.

email (string) (required)

The user’s specified email address for MFA.

Errors

  • Error: VALIDATION_ERROR

    Error detail: INVALID_EMAIL or INVALID_REQUEST

Description

Pair an email address for use as a new MFA device.

continueAuthentication

Action details
Request model

This action has no model.

Errors

This action has no errors.

Description

This action continues the current authentication flow.

setupMfa

Action details
Request model

This action has no model.

Errors

  • Error: VALIDATION_ERROR

    Error detail: MAXIMUM_ALLOWED_METHODS_LIMIT

Description

Begins the MFA pairing process.

skipMfa

Action details
Request model

This action has no model.

Errors

This action has no errors.

Description

Skip the MFA pairing process.

selectOneTimeDeviceMethod

Action details
Request model
deviceRef (ResourceRef) (required)

Refer to the ResourceRef object table.

Errors

  • Error: VALIDATION_ERROR

  • Error: REQUEST_FAILED

Description

Starts the one-time device OTP authentication flow for the selected device.

checkOtp

Action details
Request model
otp (string) (required)

The OTP submitted by the user.

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_OTP

  • Error: REQUEST_FAILED

    ErrorDetail: OTP_ATTEMPTS_LIMIT

Description

Validates the provided OTP.

activateFido2Device

Action details
Request model
origin (string) (required)

A string that specifies the server name where the fetch originates, providing the URI scheme and hostname.

attestation (string) (required)

The attestation generated by the browser as a response to a user action, such as a fingerprint or click on the security key.

Errors

  • Error: VALIDATION_ERROR

Description

Submit the FIDO2 browser response to complete the device pairing.

activateSecurityKeyDevice

Action details
Request model
origin (string) (required)

A string that specifies the server name where the fetch originates, providing the URI scheme and hostname.

attestation (string) (required)

The attestation generated by the browser as a response to a user action, such as a fingerprint or click on the security key.

Errors

  • Error: VALIDATION_ERROR

Description

Submit the FIDO2 browser response to complete the device pairing.

activatePlatformDevice

Action details
Request model
origin (string) (required)

A string that specifies the server name where the fetch originates, providing the URI scheme and hostname.

attestation (string) (required)

The attestation generated by the browser as a response to a user action, such as a fingerprint or click on the security key.

Errors

  • Error: VALIDATION_ERROR

Description

The user must pair their biometrics with the browser to complete the device pairing.

activateSmsDevice

Action details
Request model
otp (string) (required)

The OTP submitted by the user.

Errors

  • Error: VALIDATION_ERROR

    Error detail: INVALID_OTP

  • Error: REQUEST_FAILED

    Error detail: OTP_ATTEMPTS_LIMIT

Description

Submit the SMS activation code to complete the device pairing.

submitSmsTarget

Action details
Request model
testMode (boolean)

Determines whether this MFA device is configured as a test device.

phone (string) (required)

The user’s phone number for MFA.

Errors

  • Error: VALIDATION_ERROR

    Error detail: INVALID_PHONE or INVALID_REQUEST

Description

Pair a phone number for use as a new MFA device.

activateTotpDevice

Action details
Request model
otp (string) (required)

The OTP submitted by the user.

Errors

  • Error: VALIDATION_ERROR

    Error detail: INVALID_OTP

  • Error: REQUEST_FAILED

    Error detail: OTP_ATTEMPTS_LIMIT

Description

Activate an authenticator for use as a new MFA device.

Submit the authenticator activation code to complete the device pairing.

activateVoiceDevice

Action details
Request model
otp (string) (required)

The OTP submitted by the user.

Errors

  • Error: VALIDATION_ERROR

    Error detail: INVALID_OTP

  • Error: REQUEST_FAILED

    Error detail: OTP_ATTEMPTS_LIMIT

Description

Submit the voice activation code to complete the device pairing.

submitVoiceTarget

Action details
Request model
testMode (boolean)

Determines whether this MFA device is configured as a test device.

phone (string) (required)

The user’s phone number for MFA.

Errors

  • Error: VALIDATION_ERROR

    Error detail: INVALID_PHONE or INVALID_REQUEST

Description

Pair a phone number for use as a new MFA device.

activateWhatsAppDevice

Action details
Request model
otp (string) (required)

The OTP submitted by the user.

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_OTP.

  • Error: REQUEST_FAILED

    ErrorDetail: OTP_ATTEMPTS_LIMIT.

Description

Submit the WhatsApp activation code to complete the device pairing.

submitWhatsAppTarget

Action details
Request model
testMode (boolean)

Determines whether this MFA device is configured as a test device.

phone (string) (required)

The user’s phone number for MFA.

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_PHONE or INVALID_REQUEST.

Description

Submit a phone number for use as a new multi-factor authentication device.

setDefaultDevice

Action details
Request model
deviceRef (ResourceRef) (required)

The device identifier. Refer to the ResourceRef object table.

Errors

  • Error: VALIDATION_ERROR

  • Error: REQUEST_FAILED

Description

Sets the user’s default authentication device. For example:

{
  "deviceRef":
  {
    "id": "<device ID>"
  }
}

If another authentication attempt was already in progress, that in-progress attempt is canceled before the new attempt starts.

This action is available only when the user has at least one device. It can also be used as an authentication retry.

A mobile payload is required if a user requests access from an untrusted mobile app and needs to select one of their trusted devices to approve or deny access.

removeDevice

Action details
Request model
deviceRef (ResourceRef) (required)

The device identifier. Refer to the ResourceRef object table.

Errors

  • Error: INVALID_REQUEST

  • Error: VALIDATION_ERROR

    ErrorDetail: FIELD_REQUIRED, INVALID_DEVICE, or UNRECOGNIZED_FIELD_NAME.

Description

Remove a device.

You can find an example deviceRef in the selectDevice table entry.

resumeAuthentication

Action details
Request model

This action has no model.

Errors

This action has no errors.

Description

Returns to the next step in the authentication flow after completing device management if MFA is already complete. Otherwise, returns to the DEVICE_SELECTION_REQUIRED state.

submitOathTokenTarget

Action details
Request model
serialNumber (string) (required)

The serial number of the OATH token device.

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_SERIAL_NUMBER or DUPLICATE_SERIAL_NUMBER.

  • Error: REQUEST_FAILED

    ErrorDetail: TOKEN_LOCKED.

Description

Submit an OATH token serial number to complete the device pairing.

activateOathTokenDevice

Action details
Request model
otp (string) (required)

The OTP submitted by the user.

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_OTP or EXTRA_OTP_REQUIRED.

  • Error: REQUEST_FAILED

    ErrorDetail: OTP_ATTEMPTS_LIMIT.

Description

Submit the OATH token activation code to complete the device pairing.

resyncOathToken

Action details
Request model
id (string) (required)

Unique identifier of a trusted device in the PingOne MFA server.

otp (string) (required)

The TOTP submitted by the user.

Errors

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_OTP, INVALID_DEVICE, or EXTRA_OTP_REQUIRED.

  • Error: REQUEST_FAILED

    ErrorDetail: OTP_ATTEMPTS_LIMIT or TOKEN_LOCKED.

Description

Re-sync the OATH token device.

Objects

Device object

Object details
Parameter name Type Description

id

String

The unique identifier of a trusted device in the PingOne MFA server.

type

String

The model of the device. For example, iPhone 5S. This parameter is empty for OTP devices (SMS, voice, email, TOTP).

target

String

The device’s masked email address or phone number.

name

String

The name of the device. For example, iPhone 5S. This parameter is empty for OTP devices (SMS, voice, email, TOTP).

applicationId

String

The ID of the customer mobile application.

applicationVersion

String

The device’s application version.

osVersion

String

The device’s operating system version.

usable

Boolean

Indicates whether the device is usable.

nickname

String

The device’s nickname.

rpId

String

The relying party identifier if the device type is Security Key or Platform (Biometrics).

pushEnabled

Boolean

Indicates whether the device is push enabled, if the device is a mobile application. For other device types, this attribute is omitted.

otpEnabled

Boolean

Indicates whether the device is OTP enabled, if the device is a mobile application. For other device types, this attribute is omitted.

defaultDevice

Boolean

Indicates whether this device is the default device.

applicationName

String

Application name for mobile device.

lock

Lock object

Contains lock details if the device is locked, otherwise null.

Refer to the Lock object table.

notification

Notification object

Represents notification details. Primarily used to track the cooldown period when a device is restricted from receiving further notifications due to the maximum limit being reached.

Refer to the Notification object table.

Lock object

Object details
Parameter name Type Description

status

String

Indicates whether the associated device is locked.

expiresAt

Integer

Indicates how long the associated device will remain locked.

Notification object

Object details
Parameter name Type Description

coolDownExpiresAt

Integer

Indicates when notifications will be sent to the associated device again.

status

String

Indicates whether the associated device is on a notification cooldown.

expiresAt

Integer

Indicates notification cooldown expiration of unusable devices.

Application object

Object details
Parameter name Type Description

id

String

A string that specifies the ID of a mobile application for which the code is valid. Only the specified mobile application can scan the QR code.

ClientContext object

Object details
Parameter name Type Description

header

String

The client information header.

body

String

The client information body.

LifeTime object

Object details
Parameter name Type Description

duration

Integer

Specifies the length of time for this authentication code to be valid.

timeUnit

String

A string that specifies the time unit for the lifeTime.duration property. Options are SECONDS and MINUTES.

User object

Object details
Parameter name Type Description

id

String

The user’s unique identifier.

username

String

The user’s PingOne user ID or username that was mapped into the adapter.

ResourceRef object

Object details
Parameter name Type Description

id

String

The resource’s identifier.

PublicKeyCredentialRequestOptions object

Object details
Parameter Name Type Description

challenge

Array

The challenge to generate.

timeout

Integer

Indicates how long in milliseconds, the challenge will remain valid.

rpId

String.

The relying party identifier.

userVerification

String

Indicates the relying party’s user verification requirements.

Learn more about user verification in Web Authentication: An API for accessing Public Key Credentials Level 2 (section 5.4.4) in the W3C documentation.

allowCredentials

Array (AllowCredentials)

An array of AllowCredentials objects.

You can find more information in the Allow credentials (AllowCredentials) object table.

AllowCredentials object

Object details
Parameter Name Type Description

type

String

The credential type.

id

Array

An array of bytes used to uniquely identify the credential.

DevicePairingMethod object

Object details
Parameter name Type Description

DevicePairingMethod object

deviceType

String

The type of the device.

MobileDevicePairingMethod object

applicationName

String

The name of the native application associated with this device, if the device is a mobile application. For other device types, this attribute is omitted.

applicationId

String

The ID of the native application associated with this device, if the device is a mobile application. For other device types, this attribute is omitted.

WebAuthnDevicePairingMethod object

relyingPartyId

String

Specifies the server name or relying party initiating the request. Required to initiate pairing requests of security key and biometrics devices. If not provided, the PingFederate domain is used.

relyingPartyName

String

Identifies the server name or relying party initiating the request. Required to initiate pairing requests of security key and biometrics devices. If not provided, the string PingFederate is used.

userAgent

String

User agent of the device initiating the pairing request. Applicable only for platform and biometrics device pairing requests. It is passed to PingOne so it can accurately capture additional platform information of the device.

OneTimeDeviceInfo object

Object details
Parameter name Type Description

type

String

The device type.

target

String

The device target.

id

String

The device id.

oneTimeDeviceForResponse

Device

Refer to the One-time device for response (OneTimeDeviceForResponse) object table.

OneTimeDeviceForResponse object

Object details
Parameter Name Type Description

type

String

The one-time device type. Possible values are SMS, voice, email.

target

String

The device’s masked email address or phone number.

id

String

Random ID to identify the device within the response.

NumberMatching object

Object details
Parameter name Type Description

number

Integer

The number displayed for mobile authentication number matching.

type

String

Determines whether users are required to either enter the number that was shown or select the displayed number out of a group of three numbers.

RelyingParty object

Object details
Parameter name Type Description

id

String

The relying party identifier.

name

String

The relying party’s human-readable display name.

Error codes

An error code is returned if the call flow state hasn’t reached a dead end and the user can still authenticate with a device. In cases where a flow reaches a dead end, the authentication API returns an MFA_FAILED state with a corresponding code.

Top level error codes

Error code details
Error code Message HTTP status

VALIDATION_ERROR

One or more validation errors occurred.

400

REQUEST_FAILED

The request couldn’t be completed. There was an issue processing the request.

400

INVALID_REQUEST

The request was malformed or invalid.

400

RESOURCE_NOT_FOUND

The requested resource wasn’t found.

404

Detail level error codes

Error code details
Error code Message userMessageKey Parent code

INVALID_OTP

An invalid or expired passcode was provided.

authn.api.invalid.otp

VALIDATION_ERROR

OTP_EXPIRED

The passcode has expired.

authn.api.otp.expired

REQUEST_FAILED

INVALID_DEVICE

An invalid device was provided.

VALIDATION_ERROR

OTP_ATTEMPTS_LIMIT

The user performed too many unsuccessful passcode attempts.

authn.api.otp.attempts.limit

REQUEST_FAILED

TOTP_ATTEMPTS_LIMIT

The user performed too many unsuccessful TOTP passcode attempts.

authn.api.totp.attempts.limit

REQUEST_FAILED

OTP_RESEND_LIMIT

The user has resent the passcode the maximum number of times.

authn.api.otp.resend.limit

REQUEST_FAILED

PUSH_FAILED

Failed to send the push message.

authn.api.push.failed

REQUEST_FAILED

INVALID_MOBILE_PAYLOAD

An invalid mobile payload was provided.

VALIDATION_ERROR

INVALID_DEVICE_PAIRING_METHOD

An invalid device pairing method was provided.

VALIDATION_ERROR

INVALID_DATA_DEVICE_PAIRING_METHOD

The request could not be completed. One or more validation errors were in the request.

VALIDATION_ERROR

INVALID_EMAIL

An invalid email address was provided.

pingone.mfa.email.pairing.invalid.email

VALIDATION_ERROR

INVALID_PHONE

An invalid phone number was provided.

pingone.mfa.sms.pairing.invalid.phone or pingone.mfa.voice.pairing.invalid.phone

VALIDATION_ERROR

MAXIMUM_ALLOWED_METHODS_LIMIT

Reached maximum number of allowed methods limit.

pingone.mfa.device.selection.maximum.allowed.methods.limit

VALIDATION_ERROR

EXTRA_OTP_REQUIRED

An additional OTP is required.

VALIDATION_ERROR

TOKEN_LOCKED

The OATH token is locked because too many OTP authentication attempts failed.

REQUEST_FAILED

INVALID_SERIAL_NUMBER

An invalid serial number was provided.

VALIDATION_ERROR

DUPLICATE_SERIAL_NUMBER

The provided serial number is already in use.

VALIDATION_ERROR

INVALID_ASSERTION

An invalid assertion was provided.

VALIDATION_ERROR

CHANGE_AUTHENTICATION_METHOD_NOT_ALLOWED

Users are not allowed to go back and change their authentication device during a sign-on session.

VALIDATION_ERROR

INVALID_REQUEST

testMode devices aren’t allowed.

VALIDATION_ERROR

MFA_FAILED codes

Error code details
Error code Message userMessageKey

SERVER_ERROR

Server error.

authn.api.server.error

SERVICE_UNAVAILABLE

Service unavailable.

authn.api.service.unavailable

OTP_RESEND_LIMIT

This error code can also be returned if this isn’t a dead end.

The user has resent the passcode the maximum number of times.

authn.api.otp.resend.limit

PUSH_FAILED

Failed to send the push message.

authn.api.push.failed

NO_RESPONSE_PASSIVE_PUSH

Mobile payload is valid, but the extra push verification didn’t arrive.

authn.api.no.response.passive.push

NO_USABLE_DEVICES

The user has no usable devices for the requested authentication policy.

authn.api.no.usable.devices

MFA_DISABLED

The user doesn’t have MFA enabled.

authn.api.mfa.disabled

USER_NOT_FOUND

The user isn’t enabled in PingOne or doesn’t exist.

authn.api.user.not.found

DEVICE_INTEGRITY_FAILED

Device integrity validation failed.

authn.api.device.rooted