PingOne Platform APIs

DaVinci Flow Capabilities (JSON)

POST {{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}

The POST {{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}} operation initiates the DaVinci authentication flow by specifying the connection and the capabilities associated with that connection. The capability name (for example, customHTMLTemplate) and the connection ID are specified in the request URL. This request uses the X-Requested-With HTTP header set to ping-sdk to ensure that the response returns JSON (instead of HTML). Also, the DaVinci interactionId and interactionToken should be set as headers in the request.

This sample request shows the customHTMLTemplate capability, which is a common capability to build a form for collecting user information required by the flow. The request body includes a formData property that specifies the form fields needed by the flow to register a new user. Note that this is just one sample usage of the customHTMLTemplate capability. If the actionKey property specified a sign-on action instead of registration, the flow might use different or fewer fields.

The parameters property includes the eventType value, which is submit for a SUBMIT_BUTTON and action for a FLOW_BUTTON. The actionKey property varies based on whether the flow needs to submit the form data using the SUBMIT_BUTTON or take a secondary action using the FLOW_BUTTON.

  • "eventType": "action" should be passed in the payload when a FLOW_BUTTON action is intended.

  • "eventType": "submit" should be passed in the payload when a SUBMIT_BUTTON action is intended.

The actionKey in both the above cases should be mapped to the key of the SUBMIT_BUTTON or FLOW_BUTTON.

The response includes a form property that builds the form. The components.fields property defines the fields and buttons presented to users to initiate the specified action.

This endpoint supports different request body property values depending on the flow action required. This specific example initiates the registration sub-flow, and for this call there are no formData parameters. However, the next call in the flow would prompt the user for an email address, a password, and any other data required by the registration node. Click the Request model heading below to show the required properties and additional sample request payloads for additional actions.
Request Model

Refer to the DaVinci flow capabilities data model properties for full property descriptions.

Property Type? Required?

eventName

String

Required

id

String

Required

interactionId

String

Required

parameters

Object

Required

parameters.eventType

String

Required

parameters.data

Object

Required

parameters.data.actionKey

String

Required

parameters.data.formData

Object

Required

parameters.data.formData.{{attribute}}

String

Required

Request body properties for actions

The following request body samples show the different request payloads for the most common flow actions.

Secondary action, navigate to register route

{
   "id": "0mkskx7cez",
   "eventName": "continue",
   "parameters": {
     "eventType": "action",
     "data": {
       "actionKey": "REGISTER",
       "formData": {
       }
     }
   }
 }

Submit action where form details are submitted

 {
   "id": "x0txd3bdfn",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "REGISTER",
       "formData": {
         "email" : "DummyEmail@dummydomain.com",
         "password" : "DummyPassword@1234"/       }
     }
   }
 }

Resend verification code during registration

{
   "id": "o4yhix414e",
   "eventName": "continue",
   "parameters": {
     "eventType": "action",
     "data": {
       "actionKey": "RESEND",
       "formData": {
       }
     }
   }
 }



 {
   "id": "o4yhix414e",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "VERIFY",
       "formData": {
         "passcode" : "1ki2dsaq"
       }
     }
   }
 }

Last step to get the PingOne session token

{
   "id": "h2cy2gkjip",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "NEXT",
       "formData": {
       }
     }
   }
 }


 {
   "id": "65u7m8cm28",
   "eventName": "continue",
   "parameters": {
     "eventType": "action",
     "data": {
       "actionKey": "TROUBLE",
       "formData": {
       }
     }
   }
 }

From forgot password, to cancel and go back

{
   "id": "afyus0g868",
   "eventName": "continue",
   "parameters": {
     "eventType": "action",
     "data": {
       "actionKey": "CANCEL",
       "formData": {
       }
     }
   }
 }

Enter email for forgot password to send a recovery code to the id

{
   "id": "afyus0g868",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "CONTINUE",
       "formData": {
         "username":"DummyEmail@dummydomain.com"
       }
     }
   }
 }

Resend verification code to email if needed

{
   "id": "9gi11xivkc",
   "eventName": "continue",
   "parameters": {
     "eventType": "action",
     "data": {
       "actionKey": "RESEND",
       "formData": {
       }
     }
   }
 }

Enter recovery code, new password, and confirm new password

{
   "id": "9gi11xivkc",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "UPDATE",
       "formData": {
         "recoveryCode" : "sv4tk2oe",
         "newPassword" : "*******",
         "verifyNewPassword" : "*******"
       }
     }
   }
 }

Password recovery is successful. Submit form to get a PingOne session token

{
   "id": "c28j6unuv1",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "NEXT",
       "formData": {
       }
     }
   }
 }

Successful login

{
   "id": "65u7m8cm28",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "SIGNON",
       "formData": {
         "username" : "DummyEmail@dummydomain.com",
         "password" : "DummyPassword"

       }
     }
   }
 }

Incorrect login details

{
   "id": "dnu7jt3sjz",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "SIGNON",
       "formData": {
         "username" : "DummyEmail@dummydomain.com",
         "password" : "DummyPassword"
       }
     }
   }
 }

Incorrect registration

{
   "id": "65u7m8cm28",
   "eventName": "continue",
   "parameters": {
     "eventType": "action",
     "data": {
       "actionKey": "REGISTER",
       "formData": {
       }
     }
   }
 }


 {
   "id": "leznhnimpg",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "REGISTER",
       "formData": {
         "email" : "DummyEmail@dummydomain.com",
         "password" : "******"
       }
     }
   }
 }

Sign on with expired password and password reset

{
   "id": "65u7m8cm28",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "SIGNON",
       "formData": {
         "username" : "DummyEmail@dummydomain.com",
         "password" : "******"
       }
     }
   }
 }


 {
   "id": "yscz5j5r84",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "UPDATE",
       "formData": {
         "currentPassword" : "******",
         "newPassword" : "*******",
         "verifyNewPassword" : "******"
       }
     }
   }
 }


 {
   "id": "3rcqks6t1v",
   "eventName": "continue",
   "parameters": {
     "eventType": "submit",
     "data": {
       "actionKey": "NEXT",
       "formData": {
       }
     }
   }
 }

Headers

Content-Type      application/json

X-Requested-With      ping-sdk

interactionId      {{interactionID}}

interactionToken      {{interactionToken}}

Body

raw ( application/json )

{
  "id": "0mkskx7cez",
  "eventName": "continue",
 "interactionId": "095036ef-2270-4f40-99ba-9e7f83379868",
  "parameters": {
    "eventType": "action",
    "data": {
      "actionKey": "REGISTER",
      "formData": {

      }
    }
  }
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}' \
--header 'X-Requested-With: ping-sdk' \
--header 'interactionId: {{interactionID}}' \
--header 'interactionToken: {{interactionToken}}' \
--header 'Content-Type: application/json' \
--data '{
  "id": "0mkskx7cez",
  "eventName": "continue",
 "interactionId": "095036ef-2270-4f40-99ba-9e7f83379868",
  "parameters": {
    "eventType": "action",
    "data": {
      "actionKey": "REGISTER",
      "formData": {

      }
    }
  }
}'
var options = new RestClientOptions("{{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("X-Requested-With", "ping-sdk");
request.AddHeader("interactionId", "{{interactionID}}");
request.AddHeader("interactionToken", "{{interactionToken}}");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@"  ""id"": ""0mkskx7cez""," + "\n" +
@"  ""eventName"": ""continue""," + "\n" +
@" ""interactionId"": ""095036ef-2270-4f40-99ba-9e7f83379868""," + "\n" +
@"  ""parameters"": {" + "\n" +
@"    ""eventType"": ""action""," + "\n" +
@"    ""data"": {" + "\n" +
@"      ""actionKey"": ""REGISTER""," + "\n" +
@"      ""formData"": {" + "\n" +
@"        " + "\n" +
@"      }" + "\n" +
@"    }" + "\n" +
@"  }" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "{{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}"
  method := "POST"

  payload := strings.NewReader(`{
  "id": "0mkskx7cez",
  "eventName": "continue",
 "interactionId": "095036ef-2270-4f40-99ba-9e7f83379868",
  "parameters": {
    "eventType": "action",
    "data": {
      "actionKey": "REGISTER",
      "formData": {

      }
    }
  }
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("X-Requested-With", "ping-sdk")
  req.Header.Add("interactionId", "{{interactionID}}")
  req.Header.Add("interactionToken", "{{interactionToken}}")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
POST /{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}} HTTP/1.1
Host: {{authPath}}
X-Requested-With: ping-sdk
interactionId: {{interactionID}}
interactionToken: {{interactionToken}}
Content-Type: application/json

{
  "id": "0mkskx7cez",
  "eventName": "continue",
 "interactionId": "095036ef-2270-4f40-99ba-9e7f83379868",
  "parameters": {
    "eventType": "action",
    "data": {
      "actionKey": "REGISTER",
      "formData": {

      }
    }
  }
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"id\": \"0mkskx7cez\",\n  \"eventName\": \"continue\",\n \"interactionId\": \"095036ef-2270-4f40-99ba-9e7f83379868\",\n  \"parameters\": {\n    \"eventType\": \"action\",\n    \"data\": {\n      \"actionKey\": \"REGISTER\",\n      \"formData\": {\n        \n      }\n    }\n  }\n}");
Request request = new Request.Builder()
  .url("{{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}")
  .method("POST", body)
  .addHeader("X-Requested-With", "ping-sdk")
  .addHeader("interactionId", "{{interactionID}}")
  .addHeader("interactionToken", "{{interactionToken}}")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "X-Requested-With": "ping-sdk",
    "interactionId": "{{interactionID}}",
    "interactionToken": "{{interactionToken}}",
    "Content-Type": "application/json"
  },
  "data": JSON.stringify({
    "id": "0mkskx7cez",
    "eventName": "continue",
    "interactionId": "095036ef-2270-4f40-99ba-9e7f83379868",
    "parameters": {
      "eventType": "action",
      "data": {
        "actionKey": "REGISTER",
        "formData": {}
      }
    }
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}',
  'headers': {
    'X-Requested-With': 'ping-sdk',
    'interactionId': '{{interactionID}}',
    'interactionToken': '{{interactionToken}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "id": "0mkskx7cez",
    "eventName": "continue",
    "interactionId": "095036ef-2270-4f40-99ba-9e7f83379868",
    "parameters": {
      "eventType": "action",
      "data": {
        "actionKey": "REGISTER",
        "formData": {}
      }
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "{{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}"

payload = json.dumps({
  "id": "0mkskx7cez",
  "eventName": "continue",
  "interactionId": "095036ef-2270-4f40-99ba-9e7f83379868",
  "parameters": {
    "eventType": "action",
    "data": {
      "actionKey": "REGISTER",
      "formData": {}
    }
  }
})
headers = {
  'X-Requested-With': 'ping-sdk',
  'interactionId': '{{interactionID}}',
  'interactionToken': '{{interactionToken}}',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'X-Requested-With' => 'ping-sdk',
  'interactionId' => '{{interactionID}}',
  'interactionToken' => '{{interactionToken}}',
  'Content-Type' => 'application/json'
));
$request->setBody('{\n  "id": "0mkskx7cez",\n  "eventName": "continue",\n "interactionId": "095036ef-2270-4f40-99ba-9e7f83379868",\n  "parameters": {\n    "eventType": "action",\n    "data": {\n      "actionKey": "REGISTER",\n      "formData": {\n        \n      }\n    }\n  }\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
require "uri"
require "json"
require "net/http"

url = URI("{{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["X-Requested-With"] = "ping-sdk"
request["interactionId"] = "{{interactionID}}"
request["interactionToken"] = "{{interactionToken}}"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "id": "0mkskx7cez",
  "eventName": "continue",
  "interactionId": "095036ef-2270-4f40-99ba-9e7f83379868",
  "parameters": {
    "eventType": "action",
    "data": {
      "actionKey": "REGISTER",
      "formData": {}
    }
  }
})

response = http.request(request)
puts response.read_body
let parameters = "{\n  \"id\": \"0mkskx7cez\",\n  \"eventName\": \"continue\",\n \"interactionId\": \"095036ef-2270-4f40-99ba-9e7f83379868\",\n  \"parameters\": {\n    \"eventType\": \"action\",\n    \"data\": {\n      \"actionKey\": \"REGISTER\",\n      \"formData\": {\n        \n      }\n    }\n  }\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{authPath}}/{{envID}}/davinci/connections/{{connectionID}}/capabilities/{{capabilityName}}")!,timeoutInterval: Double.infinity)
request.addValue("ping-sdk", forHTTPHeaderField: "X-Requested-With")
request.addValue("{{interactionID}}", forHTTPHeaderField: "interactionId")
request.addValue("{{interactionToken}}", forHTTPHeaderField: "interactionToken")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Example Response

201 Created

{
    "interactionId": "0974be0a-ed91-43f0-bc28-1d804c5b35f6",
    "interactionToken": "ec8252657b1bab3...",
    "_links": {
        "next": {
            "href": "https://auth.pingone.asia/424d6ac2-9d99-418e-a7a7-10c91d650da9/davinci/connections/867ed4363b2bc21c860085ad2baa817d/capabilities/customHTMLTemplate"
        }
    },
    "eventName": "continue",
    "isResponseCompatibleWithMobileAndWebSdks": true,
    "id": "1k5y98i1v1",
    "companyId": "424d6ac2-9d99-418e-a7a7-10c91d650da9",
    "flowId": "1041e8016fd7c57f6551739cb6e10c99",
    "connectionId": "867ed4363b2bc21c860085ad2baa817d",
    "capabilityName": "customHTMLTemplate",
    "formData": {
        "value": {
            "email": "",
            "password": "",
            "givenName": "",
            "familyName": ""
        }
    },
    "form": {
        "name": "Registration Form",
        "description": "Collect Name, Email, Password",
        "category": "CUSTOM_HTML",
        "components": {
            "fields": [
                {
                    "type": "TEXT",
                    "key": "email",
                    "label": "Email"
                },
                {
                    "type": "PASSWORD",
                    "key": "password",
                    "label": "Password"
                },
                {
                    "type": "TEXT",
                    "key": "givenName",
                    "label": "Given Name"
                },
                {
                    "type": "TEXT",
                    "key": "familyName",
                    "label": "Family Name"
                },
                {
                    "type": "SUBMIT_BUTTON",
                    "label": "Continue",
                    "key": "REGISTER"
                },
                {
                    "type": "SUBMIT_BUTTON",
                    "label": "Already have an account? Sign On",
                    "key": "CANCEL"
                }
            ]
        }
    }
}