---
title: Authentication API states, actions, and models
description: To develop authentication API-capable adapters and selectors, you must understand the states, actions, and models of single sign-on (SSO) transactions through the PingFederate authentication API.
component: pingfederate
version: 13.1
page_id: pingfederate:sdk_developers_guide:pf_authentication_api_states_actions_and_models
canonical_url: https://docs.pingidentity.com/pingfederate/13.1/sdk_developers_guide/pf_authentication_api_states_actions_and_models.html
llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: February 6, 2023
section_ids:
  related-links: Related links
---

# Authentication API states, actions, and models

To develop authentication API-capable adapters and selectors, you must understand the states, actions, and models of single sign-on (SSO) transactions through the PingFederate authentication API.

PingFederate assigns a flow ID to each SSO transaction that uses the authentication API. PingFederate uses the flow ID to determine a transaction's state.

As a user steps through an SSO transaction, the transaction is always in some state. The state includes a status field and other fields specific to that state. The class containing those other fields is the model for the state.

The API endpoint returns the following when the user's SSO transaction has reached the `USERNAME_PASSWORD_REQUIRED` state for the form adapter.

```json
{
	"id": "PyH5g",
	"pluginTypeId": "7RmQNDWaOnBoudTufx2sEw",
	"status": "USERNAME_PASSWORD_REQUIRED",
	"showRememberMyUsername": false,
	"showThisIsMyDevice": false,
	"thisIsMyDeviceSelected": false,
	"showCaptcha": false,
	"rememberMyUsernameSelected": false,
	"_links": {
		"self": {
			"href": "https://localhost:9031/pf-ws/authn/flows/PyH5g"
		},
		"checkUsernamePassword": {
			"href": "https://localhost:9031/pf-ws/authn/flows/PyH5g"
		}
	}
}
```

The model for this state is the class `UsernamePasswordRequired`. It includes fields such as `showThisIsMyDevice`, which help the API client know how to render the credential prompt to the user.

The API response also includes a list of available actions. In this case, the only action available is `checkUsernamePassword`. The API client can select this action by sending a `POST` request with the `Content-Type` of `application/vnd.pingidentity.checkUsernamePassword+json`. Each action has its own model containing the fields that the `POST` body can provide. For the `checkUsernamePassword` action, the model is `CheckUsernamePassword`.

The `POST` body can be as simple as the following.

```json
{
	"username": "joe",
	"password": "2Federate"
}
```

After receiving this request, PingFederate calls the `lookupAuthN()` method of the form adapter. If the form adapter encounters an error while validating the credentials, it writes a JSON API error to the response. If the form adapter successfully validates the credentials, it returns `AUTHN_STATUS.SUCCESS` from its `lookupAuthN()`method. PingFederate then goes to the next step in the authentication policy. If the next step is an API-capable adapter, PingFederate calls `lookupAuthN()`on that adapter and the adapter determines its current state and writes it to the response, along with the available actions.

|   |                                                                                                                                                                                                                  |
| - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | The PingFederate authentication API follows a different naming convention for actions than PingOne. PingOne names actions as `noun.verb`, such as `otp.check`. PingFederate uses `verbNoun`, such as `checkOtp`. |

## Related links

* [Developing authentication API-capable adapters and selectors](pf_develop_auth_api_capable_adapt_selec.html)