PingOne Platform APIs

Detailed 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 HTML provides the frontend HTML you need to create the sign-on interface. It is the most direct way to render the interactive UI forms to collect user input.

To return HTML, the authorize request sets the response_mode property to pi.flow, but it omits the X-Requested-With HTTP header.

For example, the PingOne authorize request configured without the X-Requested-With HTTP header returns the following response:

{
  "id" : "howu8n9hsc",
  "companyId" : "499a5cea55...",
  "flowId" : "56cb88...",
  "connectionId" : "867ed43...",
  "capabilityName" : "customHTMLTemplate",
  "screen" : {
    "name" : "HTTP",
    "properties" : {
      "sktemplate" : {
        "type" : "string",
        "displayName" : "Template",
        "createdDate" : 1694542156374,
        "customerId" : "ecb9bf...",
        "companyId" : "singularkey"
      },
      "customHTML" : {
        "type" : "string",
        "displayName" : "HTML Template",
        "viewToggle" : true,
        "largePayload" : true,
        "value" : "<div class=\"app-container\" ..."
      },
      "validationRules" : {
        "type" : "object",
        "displayName" : "Form validation rules",
        "info" : "Rules to check to validate form inputs",
        "preferredControlType" : "validationRules"
      },
      "customCSS" : {
        "type" : "string",
        "displayName" : "CSS",
        "language" : "css",
        "maximizeToggle" : true,
        "largePayload" : true
      },
      "customScript" : {
        "type" : "string",
        "displayName" : "Script",
        "language" : "javascript",
        "maximizeToggle" : true,
        "info" : "Write custom JavaScript"."
      },
      "inputSchema" : {
        ...
      },
      "outputSchema" : {
        ...
      },
      "formFieldsList" : {
        "type" : "array",
        "constructType" : "formFieldsList",
        "displayName" : "Output Fields List",
        "preferredControlType" : "formFieldsList",
        "hideLabel" : false,
        "value" : [ {
          "preferredControlType" : "textField",
          "preferredDataType" : "string",
          "propertyName" : "username",
          "displayName" : "Username",
          "hashedVisibility" : false
        }, {
          "preferredControlType" : "textField",
          "preferredDataType" : "string",
          "propertyName" : "password",
          "displayName" : "Password",
          "hashedVisibility" : true
        }, {
          "preferredControlType" : "textField",
          "preferredDataType" : "string",
          "propertyName" : "buttonValue"
        } ]
      },
      "challenge" : {
        "type" : "string",
        "displayName" : "Challenge",
        "preferredControlType" : "textField",
        "enableParameters" : true
      },
      "button" : {
        "constructType" : "button",
        "displayName" : "Submit",
        "preferredControlType" : "button",
        "css" : {
          "backgroundColor" : "#1CAB42",
          "color" : "#ffffff"
        },
        "onClick" : {
          "constructType" : "skEvent",
          "eventName" : "continue",
          "eventType" : "post",
          "postProcess" : { }
        }
      },
      "showFooter" : {
        "value" : true
      },
      "returnRequestParameters" : {
        "value" : true
      },
      "messageTitle" : {
        "value" : "Information"
      },
      "message" : {
        "value" : ""
      },
      "showPoweredBy" : {
        "value" : false
      },
      "showContinueButton" : {
        "value" : false
      },
      "httpMethod" : {
        "value" : "GET"
      },
      "httpBody" : {
        "value" : "none"
      },
      "raw" : {
        "value" : ""
      },
      "signResponse" : {
        "value" : false
      },
      "additionalFieldsName" : {
        "value" : "additionalProperties"
      },
      "unsafeIgnoreTLSErrors" : {
        "value" : false
      },
      "delayTime" : {
        "value" : 50
      },
      "returnSuccess" : {
        "value" : true
      },
      "keepOutputIfNotValid" : {
        "value" : false
      },
      "fieldValidation" : {
        "value" : false
      },
      "outboundMtlsKey" : {
        "value" : "none"
      },
      "nodeTitle" : {
        "value" : "Username/Password Form"
      },
      "isLinkStyleSheetSupportEnabled" : {
        "value" : false
      }
    },
    "userViews" : [ {
      "screenTemplateName" : "CustomHTMLTemplate",
      "items" : [ {
        "propertyName" : "sktemplate"
      }, {
        "propertyName" : "customHTML"
      }, {
        "propertyName" : "validationRules"
      }, {
        "propertyName" : "customCSS"
      }, {
        "propertyName" : "customScript"
      }, {
        "propertyName" : "inputSchema"
      }, {
        "propertyName" : "outputSchema"
      }, {
        "propertyName" : "formFieldsList"
      }, {
        "propertyName" : "challenge"
      }, {
        "propertyName" : "button"
      } ]
    } ],
    "metadata" : {
      "colors" : {
        "canvas" : "#AFD5FF",
        "canvasText" : "#253746",
        "dark" : "#2E5EA6"
      },
      "logos" : {
        "canvas" : {
          "imageFileName" : "http.svg"
        }
      },
      "type" : "core",
      "vendor" : ""
    }
  },
  "interactionId" : "0344195d...7",
  "interactionToken" : "26bb08a75...",
  "skProxyApiEnvironmentId" : "us-west-2",
  "_links" : {
    "self" : {
      "href" : "https://auth.pingone.com/{{envID}}/davinci/policy/{{davinciFlowPolicyID}}/start"
    }
  }
}

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 PingOne flow with a redirect.

Flow execution

To execute a PingOne flow using APIs and receive verbose responses, 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 data is 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.

Step 2: Execute the next flow action

  1. Use the resource link returned in the response (example shown below) to execute subsequent steps of the flow.

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

    In this link, the {{connectionInstanceID}} value is the "connectionId" capability property in the previous API response. The {{capabilityName}} is the "capabilityName" property returned in the previous API response.

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"
 }

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.