--- title: Exploring the authentication API description: The Authentication API Applications window includes an Authentication API Explorer that lets you view the states, actions, and models available for the various API-capable adapters and selectors included in your PingFederate environment. component: pingfederate version: 13.1 page_id: pingfederate:developers_reference_guide:pf_exploring_authentication_api canonical_url: https://docs.pingidentity.com/pingfederate/13.1/developers_reference_guide/pf_exploring_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: July 8, 2024 section_ids: steps: Steps result: Result: result-2: Result: result-3: Result: result-4: Result: result-5: Result: --- # Exploring the authentication API The **Authentication API Applications** window includes an Authentication API Explorer that lets you view the states, actions, and models available for the various API-capable adapters and selectors included in your PingFederate environment. ## Steps 1. Enable the authentication API and Authentication API Explorer. 1. Go to **Authentication > Integration > Authentication API Applications**. 2. Select the **Enable Authentication API** checkbox. 3. Select the **Enable API Explorer** checkbox. 2. Configure an authentication application for the Authentication API Explorer. 1. Go to **Authentication > Integration > Authentication API Applications**. 2. Click **Add Authentication Application**. 3. In the **Authentication Application** window, configure each field as described in the following table. | Field | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Name** | A name of the authentication application, such as `Authentication API Explorer`. | | **Description** | An optional description of the authentication application, such as `[.codeph]`Explore the authentication API!` `` ` | | **URL** | A combination of the PingFederate base URL and the application path `/pf-ws/authn/explorer`.For example, if the base URL is https\://localhost:9031, enter: `https://localhost:9031/pf-ws/authn/explorer`.You can find your PingFederate base URL at **System > Server > Protocol Settings > Federation Info**. | | **Additional Allowed Origins** | Any additional allowed origins. For more information, see [Configuring authentication applications](../administrators_reference_guide/help_authenticationapplicationtasklet_authenticationapplicationstate.html).If you are using a PingFederate base URL of for testing purposes, you can skip this field. | 4. In the **Authentication Application** window, click **Save**. 5. In the **Authentication API Applications** window, click **Save**. 3. In the Authentication API Explorer, view the available states, actions, and models for any API-capable adapter or selector in your PingFederate environment: 1. Go to the URL of the Authentication API Explorer, such as https\://localhost:9031/pf-ws/authn/explorer. 2. In the **Authentication Adapter/Selector** list, select an authentication adapter or selector. ### Result: The Authentication API Explorer displays a list of states. You can then inspect the following items for any given state: * The state purpose * The state data model (if any) * The available action of actions (if any) * The action data model (if any) for a given action * The errors (if any) for a given action The developers of your web applications use this information to create the desired authentication experience. 4. Explore the authentication API through a request without an authentication policy: 1. Configure a use case to use an instance of the HTML Form Adapter for authentication. For example, you can create an service provider (SP) *(tooltip: \
\

In SAML, an entity that receives and accepts an authentication assertion issued by an IdP, typically for the purpose of allowing access to a protected resource.\

\
)* connection that uses an instance of the HTML Form Adapter for authentication. For more information, see [Configuring a sample use case](../administrators_reference_guide/pf_config_sample_use_case.html). 2. Go to **Authentication > Integration > Authentication API Applications**. 3. In the **Default Authentication Application** list, select the authentication application that represents the Authentication API Explorer. Click **Save**. 4. Initiate a request supported by the use case. ### Result: When PingFederate receives your request, it determines from your use case that it should invoke the HTML Form Adapter. Because the HTML Form Adapter is API-enabled and you have configured the Authentication API Explorer to be the default authentication application, instead of returning the **Sign On** page (from the HTML Form Adapter), PingFederate redirects the browser to the Authentication API Explorer with a `flowid` query parameter, such as https\://localhost:9031/pf-ws/authn/explorer?flowId=Tt9n7. The Authentication API Explorer opens and pre-populates the **Flow ID** field with the flow ID value generated by PingFederate. 5. In the Authentication API Explorer, click **Get** next to the pre-populated flow ID value. ### Result: The Authentication API Explorer displays a JSON response as the result of the GET request. This response contains information that the web application requires to proceed further. For instance, the `status` parameter value indicates the current state of the request. Because the sample request invokes the HTML Form Adapter, the current state should be `USERNAME_PASSWORD_REQUIRED`. At the end of the result is a hyperlink to the current state. In this example, when you select the current state link, the Authentication API Explorer jumps to the **USERNAME\_PASSWORD\_REQUIRED** state and expands its contents for further review. From this point, you can review the state data model and move the request further by selecting the appropriate action and action data, if it's required. 5. Explore the authentication API through a request with an authentication policy: 1. Go to **Authentication > Integration > Authentication API Applications**. 2. In the **Default Authentication Application** list, select **Select**. ### Result: No application is designated as the default authentication application. 3. Define an authentication policy to use the Authentication API Explorer: 1. Go to **Authentication > Policies > Policies**, and click **Add Policy**. 2. Enter a policy name and optionally a description. 3. In the **Authentication Application** list, select the authentication application that represents the Authentication API Explorer. 4. Select the HTML Form Adapter instance that has been mapped to the use case you configured in step **4a**. For both the **Fail** and **Success** policy paths, select **Done**. 1. Click **Done**. 2. Select the **IdP Authentication Policies** checkbox. 3. Click **Save**. 1. Initiate a request supported by the use case you configured in step **4a**. 2. Use the Authentication API Explorer to learn more about the authentication API. 6. Generate and configure a Postman collection JSON file. 1. Go to the **Authentication API Explorer**. 2. Click **What is the PingFederate Authentication API?** to expand the top panel 3. Click the **Postman Collection** button. ### Result: The **Authentication API Explorer** downloads the Postman collection file. 4. Open the Postman application, and import the file. 5. In Postman, manually configure the following: * The `flowid` collection variable. When PingFederate receives a request, it generates a `flowid`, such as`Tt9n7`, and displays it in the **Flow ID** field on the **Authentication API Explorer** page. * The `baseUrl` collection variable. This is the base URL of your Authentication API Explorer, such as https\://localhost:9031. * The PingFederate cookie. You must also modify the body, if one exists, to ensure that API calls work correctly.