PingOne Platform APIs

JSON Responses

PingOne flows use the PingOne authorize endpoint to start the flow. The authorize request must include the response_mode property set to pi.flow, which tells the authorization server to return a 200 OK response with a payload that can be either verbose (HTML and scripts to render the sign-on forms) or minimal (concise JSON responses that show the data properties and their values). Configuring your responses to return JSON gives you the flexibility to parse the response data, collect the information you need, and process it to suit your workflow.

To return JSON, the authorize request and every subsequent flow action request must include the X-Requested-With HTTP header with the value set to ping-sdk.

For example, the PingOne authorize request with X-Requested-With set to ping-sdk returns the following JSON response:

{
    "interactionId": "0964a6a0...",
    "connectorId": "api",
    "interactionToken": "e578ecc5c0f1b...",
    "success": true,
    "startUiSubFlow": true,
    "_links": {
        "next": {
            "href": "https://auth.pingone.asia/{{envID}}/davinci/connections/{{connectionInstanceID}}/capabilities/customHTMLTemplate"
        }
    },
    "eventName": "continue",
    "isResponseCompatibleWithMobileAndWebSdks": true,
    "id": "65u7m8cm28",
    "companyId": "424d6ac2...",
    "flowId": "1041e80...",
    "connectionId": "867ed4...",
    "capabilityName": "customHTMLTemplate",
    "formData": {
        "value": {
            "username": "",
            "password": ""
        }
    },
    "form": {
        "name": "Sign On Form",
        "description": "Prompt for username and password",
        "category": "CUSTOM_HTML",
        "components": {
            "fields": [
                {
                    "type": "TEXT",
                    "key": "username",
                    "label": "Username"
                },
                {
                    "type": "PASSWORD",
                    "key": "password",
                    "label": "Password"
                },
                {
                    "type": "SUBMIT_BUTTON",
                    "label": "Sign On",
                    "key": "SIGNON"
                },
                {
                    "type": "FLOW_BUTTON",
                    "label": "No account? Register now!",
                    "key": "REGISTER"
                },
                {
                    "type": "FLOW_BUTTON",
                    "label": "Having trouble signing on?",
                    "key": "TROUBLE"
                }
            ]
        }
    }
}

Use cases

DaVinci and PingOne configuration requirements

In DaVinci, you must configure your application, the flow, and the flow policy to meet the requirements below:

  • A DaVinci application.

  • A DaVinci flow designated as a PingOne flow.

  • A DaVinci flow policy that includes the PingOne flow.

  • A PingOne OIDC application that is associated with the DaVinci flow policy.

For PingOne flows, in addition to defining an application in DaVinci, you must also configure a PingOne OIDC application and map it to a DaVinci flow policy ID. The PingOne application ID is the client_id parameter value in the authorize request. For information about DaVinci configuration, refer to Launching a flow with a Ping SDK.

Flow execution

To execute a PingOne flow using APIs and receive JSON responses (instead of the usual HTML responses returned by DaVinci endpoints), follow these steps:

Step 1: Initiate the flow through a PingOne authorize request

  1. Use the PingOne /as/authorize OIDC endpoint to initiate authorization.

  2. In the authorize request, set the response_mode property value to pi.flow. The pi.flow value specifies a non-redirect flow where the redirect_uri parameter is not required and authorization response parameters are encoded as a JSON object and returned directly to the client.

  3. Set the client_id (the PingOne application client ID mapped to the DaVinci flow policy), the response_type, and scopes properties for the authorize request. For information about PingOne authorize endpoint properties, refer to Authorization.

  4. Add the X-Requested-With HTTP header and set the value to ping-sdk. The JSON response from the authorization server returns a next link that provides the request URL to proceed to the next step of the flow.

Step 2: Execute the next flow action

  1. Use the next link returned in the response (example shown below) to execute subsequent steps of the flow. For information about building the next link’s request body, refer to DaVinci Flow Capabilities.

     "_links": {
     "next": {
     "href": "{{authPath}}/{{envID}}/davinci/connections/{{connectionInstanceID}}/capabilities/{{capabilityName}}"
     }
 },

    The capability specified by {{capabilityName}} in the next link determines the action of the node in the flow. The flow uses the customHTMLTemplate or customForm capabilities to create an HTML page (or form) to prompt for required information to complete the flow action. The flow returns the following capabilities in the response JSON, depending on the success or failure of the sign-on action:

    • returnSuccessResponseRedirect

      If the action is successful, this capability (returned in the response’s next link) redirects to the next action in the flow.

    • customErrorMessage

      If the action fails, this capability returns a JSON error response.

  2. Add the X-Requested-With HTTP header to each next request, and set its value to ping-sdk to ensure that the response returns JSON.

    The APIs pause execution only at user-interactive steps, such as nodes that use the customHTMLTemplate or customForm capability.

Step 3: Complete the flow

  1. On successful flow completion, the response includes the ST-Cookie and ST-NO-SS session cookies in the response headers to indicate that a session has been established.

  2. The response returns the returnSuccessResponseRedirect capability and the following JSON structure to PingOne:

     {
     "environment" : {
         "id" : "6baead75..."
     },
     "session" : {
         "id" : "8e918b54..."
     },
     "authorizeResponse" : {
         "access_token" : "eyJraWQiOiI3YT...",
         "id_token" : "eyJraWQiOiI3YTVh...",
         "token_type" : "Bearer",
         "expires_in" : 3600,
         "scope" : "openid profile"
     },
     "status" : "COMPLETED"
 }

The DaVinci SDK uses these APIs as a backend when the SDK is used to execute a DaVinci flow. At this time, the SDK supports only PingOne-designated DaVinci flows associated with PingOne applications that use the OpenID Connect protocol. For information and support considerations, refer to Launching a flow with a Ping SDK and Ping SDKs - DaVinci.

DaVinci flow capabilities data model properties

Property Type? Required? Mutable? Description

authorizeResponse

Object

N/A

Read only

The response from the authorization server.

authorizeResponse.code

String

N/A

Read only

The authorization code returned by the authorization server.

companyId

String

N/A

Read only

The company ID (same value as the PingOne environment ID).

capabilityName

String

N/A

Read only

The name of the associated capability used by the node.

connectionId

String

N/A

Read only

The connection ID of the connector used to send the event.

environment

Object

N/A

Read only

The environment object.

environment.id

String

N/A

Read only

The environment ID.

eventName

String

N/A

Read only

The event name.

flowId

String

N/A

Read only

The flow ID.

form

Object

Optional

Mutable

The form attributes object.

form.name

String

Optional

Mutable

The form name.

form.description

String

Optional

Mutable

The form description.

form.category

String

Optional

Mutable

The form category.

form.components

Object

Optional

Mutable

The form components object.

form.components.fields

Object

Optional

Mutable

The form fields object.

id

String

N/A

Read only

The resource ID.

interactionId

String

N/A

Read only

A unique identifier for the flow execution.

interactionToken

String

N/A

Read only

The flow execution interaction token.

isResponseCompatibleWithMobileAndWebSdks

Boolean

N/A

Read only

Specifies whether the response is compatible with the mobile and web SDKs.

parameters

Object

Required

Mutable

The form data attributes.

parameters.eventType

String

Required

Mutable

The event type. Options are action, and submit.

parameters.data

Object

Required

Mutable

The parameter data JSON object. Options are action, and submit.

parameters.data.actionKey

String

Required

Mutable

If the parameters.eventType is set to action, this property specifies the flow action.

parameters.data.formData

Object

Required

Mutable

The form data attributes.

parameters.data.formData.{{attribute}}

String

Required

Mutable

The form data attributes that are associated with fields in the form.

resetCookie

Boolean

N/A

Read only

Specifies whether the reset cookie feature is enabled.

session

Object

N/A

Read only

The session object.

session.id

String

N/A

Read only

The session ID.

status

String

N/A

Read only

The status of the DaVinci flow (for example, COMPLETE).

subFlowSettings

Object

N/A

Read only

The subflow settings JSON object.

success

Boolean

N/A

Read only

Specifies whether the flow was successful.