--- title: PingFederate Authentication API support description: 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. component: otp page_id: otp::pf_otp_ik_authentication_api_support canonical_url: https://docs.pingidentity.com/integrations/otp/pf_otp_ik_authentication_api_support.html revdate: October 6, 2025 section_ids: models-objects-and-error-codes: Models, objects, and error codes objects: Objects error-codes: Error codes --- # 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: * [PingFederate Authentication API](https://docs.pingidentity.com/pingfederate/latest/developers_reference_guide/pf_authentication_api.html) * [Exploring the Authentication API](https://docs.pingidentity.com/pingfederate/latest/developers_reference_guide/pf_exploring_authentication_api.html) | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. > **Collapse: 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) *(tooltip: \
\

An electronic authentication method where a user is granted access only after presenting two or more verification factors for authentication.\

\
)*. | > | `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) *(tooltip: \
\

A passcode valid for only one sign-on or transaction on a computer system or other digital device. Also known as a one-time password, one-time PIN, or dynamic password.\

\
)* 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. | > **Collapse: 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": > "" > } > } > ``` | > | `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 > **Collapse: 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. | > **Collapse: 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. > **Collapse: 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. > **Collapse: Top level error codes** > > | 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` | > **Collapse: 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` | > **Collapse: 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. | |