PingOne Platform APIs

Getting Started with DaVinci

Getting started with PingOne DaVinci begins by looking at the big picture. With numerous options to build and execute orchestration flows, the first step might be to ask yourself these questions:

  • What use case do I want to solve?

  • Does the flow need an interface to prompt users for input or is it headless?

  • Where will the flow run: web, mobile, protocol (OIDC, SAML, RADIUS), PingFederate, or backend?

  • Which integration method fits the user experience: redirect, SDK, widget, or API?

  • Can I start from a pre-built flow instead of building from scratch?

Working with flows

This introduction does not provide guidance on how to build flows with DaVinci Admin APIs. While the APIs include endpoints to create and update DaVinci flows, the request body can require thousands of lines of JSON. Instead, you’ll want to use the DaVinci graphical interface. Moreover, there are additional tools that you can use to design and configure flows to accelerate your progress.

Download MarketPlace flows

The Marketplace offers a curated collection of complete and tested flows. You can download and import these flows from the Ping Identity Marketplace and use them as templates to explore additional flow-orchestration options. You can search the archive in its entirety for pre-built solutions that match the use case you’re trying to solve. Or, you can filter by capability, such as MFA & Passwordless solutions, Single Sign-On (SSO) configurations, Threat Protection, Verified Trust, and many more. Marketplace flows give you the advantage of starting your orchestration journey from a working flow while showing you how DaVinci flows are constructed.

Design with use case connectors

Use case connectors consolidate complex subflows into a single node for complex identity management actions such as sign-on, registration, password resets, agreements, and multi-factor authentication. These connectors appear as a single node on the canvas and are the fastest way to implement common user experiences compared with the more granular connector types. If the use case you’re trying to solve involves some of these common actions, the use case connectors give you complex functionality quickly.

Design with an integration method in mind

Before you build, you should consider how the flow will be integrated into your app. DaVinci supports several paths: redirect, widget, API, or SDK. Your choice can determine the configuration and property settings of the flow.

Redirect

Redirect integrations support PingOne flows. These flows redirect to the PingOne authorization server to initiate the flow. The flow starts with a request to the PingOne authorize endpoint that starts DaVinci flow orchestration to execute the actions in the DaVinci flow. After completing the DaVinci flow actions, the flow redirects back to the PingOne authorization server to call the token endpoint and generate the access token. The flow settings on the DaVinci flow must specify that you want to launch the flow through PingOne. In the API, this setting is configured through the trigger object in the flow settings properties.

  • OIDC and SAML protocol flows use the redirect method to implement PingOne triggered flows.

  • RADIUS protocol flows also use the redirect method to configure flows through PingOne. This approach configures DaVinci as an identity provider (IdP) in PingOne. For details, refer to Launching a PingOne flow with a redirect using an external IdP.

SDKs

The Ping SDKs support flows designed for native iOS, Android, or single-page app JavaScript experiences. These flows must use compatible connectors such as the HTTP Connector and its Custom HTML Template capability and the Form Connector and its Show Form capability. Like the redirect integration method, SDK integrations support PingOne flows launched through the PingOne authorization server. These flows must be configured as PingOne flows in the flow settings.

Widget

Widget integrations launch the flow in the user’s current page rather than redirecting to an authorization server. You cannot use the widget method for a flow designated as a PingOne flow. To run a flow with the embedded widget, you must integrate the davinci.js widget code directly into your website’s HTML/JavaScript to load the flow. This integration keeps the user on your application’s domain for all actions associated with the flow.

API call

API integrations support flows that process without interaction from the user. These flows are designed and configured to accept API data as input and return a JSON response. The request body of the API call is a JSON object that matches the properties defined in your flow’s input schema. The result of the API call can be a JSON success reponse (if the flow completes) or a flowResponse object with instructions for the next step in the flow.