--- title: DaVinci Flow Capabilities (JSON) description: 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. component: pingone-api page_id: pingone-api:auth:pingone-davinci/davinci-runtime-apis/pingflows-json/auth-flow-capabilities canonical_url: https://developer.pingidentity.com/pingone-api/auth/pingone-davinci/davinci-runtime-apis/pingflows-json/auth-flow-capabilities.html section_ids: request-body-properties-for-actions: Request body properties for actions headers: Headers body: Body example-request: Example Request example-response: Example Response --- # DaVinci Flow Capabilities (JSON) ## ```none 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. | > **Collapse: Request Model** > > Refer to the [DaVinci flow capabilities data model properties](../pingflows-json.html#davinci-connections-capabilities-data-model) 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** ```json { "id": "0mkskx7cez", "eventName": "continue", "parameters": { "eventType": "action", "data": { "actionKey": "REGISTER", "formData": { } } } } ``` **Submit action where form details are submitted** ```json { "id": "x0txd3bdfn", "eventName": "continue", "parameters": { "eventType": "submit", "data": { "actionKey": "REGISTER", "formData": { "email" : "DummyEmail@dummydomain.com", "password" : "DummyPassword@1234"/ } } } } ``` **Resend verification code during registration** ```json { "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** ```json { "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** ```json { "id": "afyus0g868", "eventName": "continue", "parameters": { "eventType": "action", "data": { "actionKey": "CANCEL", "formData": { } } } } ``` **Enter email for forgot password to send a recovery code to the id** ```json { "id": "afyus0g868", "eventName": "continue", "parameters": { "eventType": "submit", "data": { "actionKey": "CONTINUE", "formData": { "username":"DummyEmail@dummydomain.com" } } } } ``` **Resend verification code to email if needed** ```json { "id": "9gi11xivkc", "eventName": "continue", "parameters": { "eventType": "action", "data": { "actionKey": "RESEND", "formData": { } } } } ``` **Enter recovery code, new password, and confirm new password** ```json { "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** ```json { "id": "c28j6unuv1", "eventName": "continue", "parameters": { "eventType": "submit", "data": { "actionKey": "NEXT", "formData": { } } } } ``` **Successful login** ```json { "id": "65u7m8cm28", "eventName": "continue", "parameters": { "eventType": "submit", "data": { "actionKey": "SIGNON", "formData": { "username" : "DummyEmail@dummydomain.com", "password" : "DummyPassword" } } } } ``` **Incorrect login details** ```json { "id": "dnu7jt3sjz", "eventName": "continue", "parameters": { "eventType": "submit", "data": { "actionKey": "SIGNON", "formData": { "username" : "DummyEmail@dummydomain.com", "password" : "DummyPassword" } } } } ``` **Incorrect registration** ```json { "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** ```json { "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 ) ```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 ```shell 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": { } } } }' ``` ```csharp 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); ``` ```golang 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)) } ``` ```http 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": { } } } } ``` ```java 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(); ``` ```javascript 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); }); ``` ```javascript 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); }); ``` ```python 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 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(); } ``` ```ruby 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 ``` ```swift 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 ```json { "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" } ] } } } ```