--- title: JSON Responses description: 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. component: pingone-api page_id: pingone-api:auth:pingone-davinci/davinci-runtime-apis/pingflows-json canonical_url: https://developer.pingidentity.com/pingone-api/auth/pingone-davinci/davinci-runtime-apis/pingflows-json.html section_ids: davinci-and-pingone-configuration-requirements: DaVinci and PingOne configuration requirements flow-execution: Flow execution step-1-initiate-the-flow-through-a-pingone-authorize-request: "Step 1: Initiate the flow through a PingOne authorize request" step-2-execute-the-next-flow-action: "Step 2: Execute the next flow action" step-3-complete-the-flow: "Step 3: Complete the flow" davinci-connections-capabilities-data-model: DaVinci flow capabilities data model properties --- # 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: ```none { "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" } ] } } } ``` ## 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](https://docs.pingidentity.com/davinci/integrating_flows_into_applications/davinci_sdk_launching_a_flow_with_the_sdk.html). | ## 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](../../openid-connect-oauth-2/authorize-intro.html). 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](pingflows-json/auth-flow-capabilities.html). ```json "_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: ```json { "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](https://docs.pingidentity.com/davinci/integrating_flows_into_applications/davinci_sdk_launching_a_flow_with_the_sdk.html) and [Ping SDKs - DaVinci](https://docs.pingidentity.com/sdks/latest/davinci/index.html). | ## 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. |