One-Time Passcode Integration Kit

PingFederate Authentication API support

The PingFederate Authentication API provides access to the current state of the authentication flow as a user steps through the PingFederate authentication policy. You can use the PingFederate Authentication API to integrate the One-Time Passcode IdP Adapter into your application.

You can also explore the process using the PingFederate Authentication API Explorer. Learn more in the following sections of the PingFederate documentation:

HTTP method contract:

  • GET /pf-ws/authn/flows/{flowId} always returns the current state. The response never changes state, regardless of query parameters.

  • All state transitions are POST-only actions. A POST request that’s invalid for the current state returns an INVALID_ACTION_ID 400 error.

To integrate the One-Time Passcode IdP Adapter into your authentication flow, configure your application based on the information in this section.

Models, objects, and error codes

When using the One-Time Passcode Integration Kit through the PingFederate Authentication API, the adapter uses the following state models, action models, objects, and error codes.

State models
Status Request model Action Description

DEVICE_SELECTION_REQUIRED
devices

The list of devices associated with the user.

user

The authenticating user’s username.

userData

The user info object.

  • selectDevice

  • cancelAuthentication

Indicates that device selection is required because the user might have more than one device.

To continue, the user must select a device for multi-factor authentication (MFA).

OTP_REQUIRED
devices

The list of devices associated with the user.

user

The authenticating user’s username.

selectedDeviceRef

The device identifier.

userData

The user info object.

  • checkOtp

  • cancelAuthentication

  • selectDevice

  • resendOtp

Indicates that a one-time passcode (OTP) is required.

To continue, the user must enter the OTP sent to them through either SMS, voice call, or email.

OTP_VERIFIED

This state has no model.

  • continueAuthentication

Indicates that the user has completed MFA using an OTP.

MFA_FAILED
code

The error code.

message

The developer-facing error message.

userMessage

The user-facing error message.

  • cancelAuthentication

Indicates a dead end in the authentication flow.

The API client can proceed in the flow by calling cancelAuthentication. The adapter returns a FAILURE status.
Action models
Status Request model Action Description

selectDevice
deviceRef (required)

The device identifier.

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_DEVICE

Starts an authentication flow with the specified deviceId.

For example:

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

checkOtp
otp

The OTP submitted by the user.

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_OTP

Validates the submitted OTP.

resendOtp

This action has no model.

  • Error: REQUEST_FAILED

    ErrorDetail: OTP_RESEND_LIMIT

Re-sends an OTP to the previously selected device.

continueAuthentication

This action has no model.

This action has no errors.

This action continues the current authentication flow.

cancelAuthentication

This action has no model.

This action has no errors.

This action cancels the current authentication step.

Objects

Device object
Parameter Name Type Description

id

String

The unique identifier for this object.

type

String

The device delivery method type. The available options are SMS, VOICE, and EMAIL.

target

String

The device’s masked email address or phone number.
User object
Parameter Name Type Description

username

String

The user’s username that was mapped into the adapter.
userData object

Object with dynamic data populated based on adapter configuration.

Resource reference (ResourceRef) object
Parameter Name Type Description

id

String

The resource’s identifier.

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 MFA_FAILED state is returned with a corresponding code.

Top level error codes
Error code Message HTTP status

VALIDATION_ERROR

One or more validation errors occured.

400

REQUEST_FAILED

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

400
Detail level error codes
Error code Message userMessageKey Parent code

INVALID_OTP

An invalid or expired OTP was provided.

authn.api.invalid.otp

VALIDATION_ERROR

OTP_RESEND_LIMIT

This error code can also be returned by the MFA_FAILED state.

The OTP has been re-sent the maximum number of times.

authn.api.otp.resend.limit

REQUEST_FAILED

INVALID_DEVICE

An invalid device was provided.

VALIDATION_ERROR
MFA_FAILED codes
Error code Message userMessageKey

OTP_RESEND_LIMIT

This error code can also be returned if the call flow state hasn’t reached a dead end. To learn more, refer to the previous table, Detail level error codes.

The OTP has been re-sent the maximum number of times.

authn.api.otp.resend.limit

INVALID_DEVICE

An invalid device was provided.