--- title: Authentication API description: The PingFederate authentication API is a JSON-based API that enables external web applications to handle end-user interactions like credential prompts.It does this by providing access to the current state of the flow as an end-user proceeds through a PingFederate authentication policy. component: pingfederate version: 13.1 page_id: pingfederate:developers_reference_guide:pf_authentication_api canonical_url: https://docs.pingidentity.com/pingfederate/13.1/developers_reference_guide/pf_authentication_api.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: March 5, 2026 section_ids: key-concepts: Key concepts session-management: Session management authentication-api-explorer: Authentication API Explorer javascript-widget-for-the-pingfederate-authentication-api: JavaScript widget for the PingFederate authentication API --- # Authentication API The PingFederate authentication API *(tooltip: \
\

A specification of interactions available for building software to access an application or service.\

\
)* is a JSON-based API that enables external web applications to handle end-user interactions like credential prompts.It does this by providing access to the current state of the flow as an end-user proceeds through a PingFederate authentication policy. Authentication flows are initiated through browser-based single sign-on (SSO) *(tooltip: \
\

The process of authenticating an identity (signing on) at one website (usually with a user ID and password) and then accessing resources secured by other domains without reauthenticating.\

\
)* application endpoints, such as `/idp/startSSO.ping`, or a protocol request, such as an OpenID Connect (OIDC) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* authentication request received at the authorization endpoint: `/as/authorization.oauth2`. As PingFederate runs the configured authentication policy, if it encounters an API-capable adapter or selector, and an authentication application is configured for the policy, PingFederate redirects to the authentication application's URL, passing the ID of the flow in the `flowId` query parameter. The authentication application can then retrieve the current state of the flow by issuing a `GET` request to the `/pf-ws/authn/flows/{flowId}` endpoint. The `links` field in the response lists the available authentication actions that can be performed from the current state. To invoke an action, the authentication application sends a `POST` request to the `/pf-ws/authn/flows/{flowId}` endpoint. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Authentication API requests are serviced by the `/pf-ws/authn/flows` endpoint, with flow IDs being passed as additional path information. If you're protecting the endpoint with a Web Application Firewall (WAF), you should apply the firewall to `/pf-ws/authn/flows` instead of `/pf-ws/authn/flows/{flowId}`. | The API client can choose authentication actions using either an `action` query parameter or a custom content type. The `action` query parameter should be used when your networks block custom content types and is specified using the following format: ``` /pf-ws/authn/flows/{flowId}?action={actionID} ``` For example, to check username and password, pass the `checkUsernamePassword` action ID through the query parameter as follows: ``` /pf-ws/authn/flows/{flowId}?action=checkUsernamePassword ``` For the custom content type, the action ID is specified using the Content-Type HTTP request header in the following format: ``` application/vnd.pingidentity.{actionId}+json ``` For example, to indicate a username and password check from the HTML Form Adapter, specify the following: ``` application/vnd.pingidentity.checkUsernamePassword+json ``` When the application invokes an action, PingFederate responds either with the next state for the flow or an error. When the user completes the authentication policy steps successfully, the authentication API returns a `RESUME` status to the authentication application. This status indicates that the API client should redirect the user's browser to the `resumeUrl` specified in the response. PingFederate is then responsible for the final step in the flow, such as passing a SAML assertion to a partner. A `RESUME` status is also sent if PingFederate encounters an identity provider (IdP) *(tooltip: \
\

A service that manages identity information and provides authentication services to relying clients or SPs within a federated or distributed network.\

\
)* connection in the policy tree, or an IdP adapter or selector that isn't API-capable. When the API client redirects the user, PingFederate takes the steps needed to invoke the authentication source. If the user has interacted with an authentication application, and the flow terminates with an error, the API client receives a `FAILED` status from the API. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | To avoid issues with third-party cookies in some browsers, give the authentication application the same parent domain as the PingFederate authentication API URL that the application accesses. This could be a common domain of PingFederate's base URL or one of PingFederate's defined [virtual hosts](../administrators_reference_guide/pf_virtual_host_names.html). | ## Key concepts * Flow The SSO transaction invoking the authentication API. * States The available states (if any) for a given API-enabled adapter or selector. * Current state Indicates what the adapter or selector is ready to do next. * Actions The available actions (if any) for a given state. ## Session management The authentication API endpoint has the same domain as PingFederate's other application endpoints and shares the PingFederate session cookies with those endpoints. This ensures that session data created by API applications can be retrieved when the user interacts with PingFederate's other endpoints and vice versa. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Because the authentication API relies on the PingFederate session cookies, only browser-based web applications can currently make use of the API. Server-side web applications aren't supported. | In order for PingFederate to manage session cookies correctly, the JavaScript-written authentication application must set the `withCredentials` flag on the XMLHttpRequest object to `true`. To protect against cross-site request forgeries, API clients are also required to include an X-XSRF-Header HTTP request header with each request, for example: `X-XSRF-Header: PingFederate`. This custom header ensures that browsers enforce cross-origin resource sharing (CORS) policies when API requests are sent. This header can have any value. ## Authentication API Explorer PingFederate includes an API Explorer, which allows you to view the states, actions, and models available for the various API-capable adapters and selectors included in your PingFederate environment. The endpoint for the Authentication API Explorer is `/pf-ws/authn/explorer`. You can download a Postman collection file from **Authentication > Integration > Authentication API Applications**. The file contains information converted from the Explorer into a Postman collection. You can then import the collection file into the Postman application. The collection file provides every possible action of every state in every plugin deployed in the PingFederate instance. It contains: * All API-capable plugins, both adapters and selectors, with all of their states and actions. * A prepopulated body containing information about required information types and parameters. * Headers for API calls, both X-XSRF-Header and Content-Type. Learn more in [Exploring the authentication API](pf_exploring_authentication_api.html). ## JavaScript widget for the PingFederate authentication API The JavaScript Widget for the PingFederate authentication API is a customizable JavaScript library that provides the capabilities of the HTML Form Adapter and Identifier First Adapter through the authentication API: * User Login * Trouble Signing in * Trouble with Username * Password Reset The widget is a ready-to-use drop-in bundle with CSS and customizable templates. This alternative to the PingFederate templates provides a sign-on experience as a single page application. You can find the widget in the [JavaScript Widget for the PingFederate Authentication API](https://github.com/pingidentity/pf-authn-js-widget) GitHub repository.