The PingOne DaVinci Admin APIs provide access to DaVinci operations through the PingOne API resource server. These services are called using the api.pingone.com domain (or api.pingone.ca, api.pingone.eu, api.pingone.com.au, api.pingone.sg, and api.pingone.asia for other geographic regions) to manage DaVinci workflow configuration.

At this time, the following services are supported on the PingOne API resource server:

• DaVinci Admin Variables

  Endpoints for managing DaVinci variables and their context.

• DaVinci Admin Flows

  Endpoints for creating and managing DaVinci flows.

• DaVinci Admin Flow Versions

  Endpoints for managing DaVinci flow versions.

• DaVinci Admin Connector Instances

  Endpoints for managing DaVinci connector instances, which provide access to DaVinci connector capabilities.

• DaVinci Admin Applications

  Endpoints for managing DaVinci applications.

• DaVinci Admin Application Flow Policies

  Endpoints for managing DaVinci application flow policies.

• DaVinci Admin Connectors

  Endpoints for managing DaVinci connectors.

• DaVinci Admin UI Templates

  Endpoints for managing DaVinci UI templates.

PingOne DaVinci Admin Variables service provides endpoints to create, read, update, and delete DaVinci variables. Variables are values that can be read and modified during a flow. Every variable has a context, which determines how widely its value is shared.

The options for the variable's context types are:

• flow

  The variable is tied to a specific flow and has a single, persistent value until that value is changed.

• flowInstance

  The variable can be used in multiple flows.

  • If the variable's value is set within a flow, the variable instance in that flow gets the value set by the flow's execution.

  • If the variable's value is not set within a flow, the variable instance in that flow inherits the value.

• user

  The variable has a separate value for each user. If you use a variable with this context in a flow, the user must be identified.

• company

  The variable has a single value for the company. This value is used in all flows and for all users.

DaVinci Admin variable data model properties

Limiting and filtering data

These SCIM operators can be applied to the following attributes:

• eq (equals)

  Supports attributes of type STRING and BOOLEAN.

• sw (starts with)

  Supports attributes of type STRING.

• ew (ends with)

  Supports attributes of type STRING.

• co (contains)

  Supports attributes of type STRING.

• and (logical AND)

  Logical AND for building compound expressions in which both expressions are true.

• or (logical OR)

  Logical OR for building compound expressions if either expression is true.

For information about paging and ordering the response for Read All DaVinci Variables, refer to Paging, ordering, and filtering collections.

Response codes

PingOne DaVinci Admin Connector service provides endpoints to read DaVinci connector resources. Connectors give DaVinci the ability to integrate third party technologies, HTML pages, and other tools to create a sign-on flow. They define the capabilities that you can use as nodes in a flow. For example, an HTTP connector provides the capability to present an HTML form to collect and submit user information or make REST API calls.

DaVinci admin connector data model properties

DaVinci admin connectors details data model properties

Response codes

PingOne DaVinci Admin Connector Instances service provides endpoints to create, read, update, and delete DaVinci connector instances. A DaVinci connector instance is one instance of a DaVinci connector (the connection configuration specifies a connector by name). You can then use the capabilities provided by the connector inside a flow, and launch the flow through an application.

This service also includes an action to clone connector instance resources.

DaVinci admin connector instances data model properties

Response codes

DaVinci flows are constructed, logical paths that specify the workflow for the user's authorization and authentication experiences.

Flows consist of one or more nodes joined together. Each node performs a specific task, using one of the capabilities of your connectors. After completing the task, the flow determines which task to perform next until the flow is complete.

The PingOne DaVinci Admin Flows service provides endpoints to create, read, update, and delete DaVinci flows. This service also includes endpoints to enable, deploy, import, and clone flows.

DaVinci admin flow data model properties

Settings property data model

The following table lists the supported flow settings properties that can be used in the settings property.

Input schema for non-PingOne flows data model properties

Limiting and filtering data

You can limit the number of results returned on the Read DaVinci Flows and Read One DaVinci Flow requests with the attributes parameter. This parameter filters the response data returned by the request. The query accepts top-level DaVinci admin flow data model properties as a list of comma separated values. The query returns only the specified property values; it removes all other properties from the response. For example, the following request uses the attributes query parameter:

/environments/{{envID}}/flows/{{davinciFlowID}}?attributes=name,description

The response returns the following flow data:

{
   "_links": {...},
   "id": "{{resourceID}}",
   "name": "SomeFlow, 
   "description": "A brief description"
}

SCIM operators

These SCIM operators can be applied to the following attributes:

• eq (equals)

  Supports attributes of type STRING, DATE, NUMBER, and BOOLEAN.

• gt (greater than)

  Supports attributes of type DATE and NUMBER.

• ge (greater than or equal to)

  Supports attributes of type DATE and NUMBER.

• lt (less than)

  Supports attributes of type DATE and NUMBER.

• le (less than or equal to)

  Supports attributes of type DATE and NUMBER.

• sw (starts with)

  Supports attributes of type STRING.

• ew (ends with)

  Supports attributes of type STRING.

• co (contains)

  Supports attributes of type STRING.

• within (within a specified date)

  Supports attributes of type DATE.

• and (logical AND)

  Logical AND for building compound expressions in which both expressions are true.

• or (logical OR)

  Logical OR for building compound expressions if either expression is true.

Response codes

The PingOne DaVinci Admin Flow Versions service provides endpoints to read, update, and delete DaVinci flow versions. This service also includes endpoints to export, revert, and see details about a flow version.

DaVinci admin flow versions data model properties

Flow versions details property data model

The following table lists the supported flow versions details settings properties.

Flow versions graph data property data model

The following table lists the supported flow versions graph data settings properties.

Response codes

PingOne DaVinci Admin Applications service provides endpoints to create, read, update, and delete DaVinci applications. This service also includes endpoints to rotate the application key and application secret values.

A DaVinci application configuration is the link between your site and the sign-on flows you have created in DaVinci. The application configuration contains settings to determine how external sites can send requests for flows, what flows can be requested, and how users and resources from other sites are managed.

DaVinci Admin applications data model properties

Response codes

PingOne DaVinci Admin Application Flow Policies service provides endpoints to create, read, update, and delete DaVinci application flow policies. Application flow policies specify which flows are run through the application. A flow policy is an entity that points to one or more flows or versions of flows.

DaVinci Admin application flow policies data model properties

DaVinci Admin application flow policy event data model properties

Response codes

You can create user interface (UI) templates that match your company style and branding, which you can include in flows using an HTTP connector. The PingOne DaVinci Admin UI Templates service provides endpoints to create, read, and delete DaVinci UI templates.

DaVinci Admin UI templates data model properties

Response codes

If you want to start building your own workflows with PingOne APIs, the Workflow Library provides step-by-step workflows with linked Postman collections to help you start using the PingOne APIs in your Postman environment. For information about how PingOne secures APIs, resources, and data, and what you can do to implement security measures for your PingOne deployment and applications, refer to Platform security.

If you're new to PingOne and have not set up your test environment, refer to PingOne for Developers Getting Started. This guide helps you get an admin access token, which is required to make API calls to DaVinci Admin API resources.

PingOne API domains

This section discusses how PingOne API regional endpoints are entered in the domain name system (DNS). In DNS, and in our endpoints, the domain part of the uniform resource locator (URL) comprises three parts separated by periods, such as api.pingone.com: one of our service-specific subdomains, our PingOne domain name of pingone, and one of our top level domains.

We use Postman variables to manage this variety of domain parts in PingOne API endpoints. The later discussion is correct regarding the domain part that the variables evaluate to. However, to ease maintenance, the Postman environment template you get when you download a collection uses variables to isolate the TLD from the rest of the domain part and to isolate the domain part from the rest of the endpoint.

The environment template has a path variable for each subdomain. Each path variable uses another variable, {{tld}}, for the top level domain (TLD). Such as https://api.pingone.{{tld}}/v1 for {{apiPath}}. The tld variable is first in the environment template that you downloaded.

The table below shows the top level domain value for each region. To change your region, simply change the default {{tld}} value from com to your region's TLD.

The PingOne API includes the following domains:

The {{...Path}} variable in the sample requests stand for the PingOne service endpoint. Refer to Public endpoints in the PingOne for Developers Foundations guide for more information.

The Try a Request feature

Our documentation for the PingOne APIs includes an interactive Try a Request feature. Try a Request enables you to configure and send a PingOne API request and get a response from within the documentation. This is a quick way to interactively test a PingOne API request without needing to use either Postman or the command line.

Requests in Authentication and Authorization APIs do not have the Try a Request feature due to a Cross-Origin Resource Sharing (CORS) constraint.

Calling the PingOne APIs from the command line

Each PingOne API request in the documentation includes an example request and response. By default, the example request is displayed using cURL. However, a number of coding languages are available in the associated drop-down list. If you want to run a request from the command line, you can select the coding language and copy the displayed request. You'll need to replace any variables in the request with the appropriate values before running the request.

Using Postman collection-level authorization

Most APIs require authorization to ensure that client requests access data securely. Postman can pass along whatever authorization details necessary for the method demanded by the endpoint. You can manually include authorization data in the header, body, or as parameters to a request. However, the easiest way is to use the Authorization tab in Postman. Select an authorization Type on that tab and Postman offers a dialog to gather the information required by that Type. When you run a request, Postman uses the information from the Authorization tab to automatically add the necessary authorization header, body, or parameters to the request. Postman offers the Authorization tab on requests, folders, and collections.

In PingOne collections, the authorization method is defined at the collection level. Only those requests that require a specific authorization method have authorization defined on the request (roughly 10% of PingOne requests). This allows you to easily change the authorization used for most requests. Refer to Postman Collection-Level Authorization for more information.

We use Postman to create our PingOne DaVinci Admin API docs, and have supplied our Postman collections for you to download. There's also an accompanying Postman Environment template already populated with the variables used in the collections.

If you aren't currently using Postman, you can install the free version. Refer to Download Postman to install Postman, either locally, or in your browser.

Refer to The PingOne DaVinci Admin API Postman collections for the collections you can download or fork.

For more information about our Postman environment variables, refer to The PingOne Postman environment template.

You'll also find all of the Postman collections for our documented PingOne use cases in our Workflow Library.

You can get the PingOne DaVinci Admin API Postman collection by following either of these methods for retrieving a Postman collection into your workspace:

1. Fork the collection into your workspace. Postman retains an association between the source and your fork. If we update the source collection, you can pull those changes into the fork in your workspace.

2. Import the collection into your workspace. This is a one-time transfer and retains no association to the source collection.

To retrieve a collection

Refer to The PingOne DaVinci Admin API collections on this page.

1. Click the collection's Run In Postman button.

2. At the prompt, click Fork Collection at the bottom of the dialog or click import a copy near the bottom of the dialog.

   Note: You need to be logged in to your Postman account to retrieve the collection.

   

3. Follow the on-screen instructions to fork or import the collection. You're prompted to select a Postman workspace for the retrieved collection.

When you fork a Postman collection, you create a copy of it in a selected workspace. Forking a collection creates a linked version that synchronizes with its source collection. This synchronization is apparent when you click the three dots icon on the forked collection - you'll see Pull changes on the context menu. When you click Pull changes, Postman compares the fork to the source collection. If changes are available, you can pull those changes into your fork. If you also elect to watch the collection, you'll receive notifications when the source changes.

If you import a collection, a copy is created in the selected workspace with no link back to the source. The collection is static. This may be desirable for some use cases. For example, if you intend to keep and use only some requests in a collection, a link back to the source is not needed.

You're not limited to choosing one method or the other. You can fork a copy to track the source and import a copy for experimentation, if you like.

The PingOne DaVinci Admin API collections

These Postman collections include requests for all create, read, update, and delete (CRUD) operations for the PingOne DaVinci Admin APIs.

Collection	Description	Retrieve
PingOne DaVinci	Postman requests for the PingOne DaVinci Admin API. Includes all environment variables. No example responses to make it easy to get started.
PingOne DaVinci	Postman requests for the PingOne DaVinci Admin API. Includes all PingOne Platform API Reference documentation and example reponses. No environment variables are included.

For more information about the Postman environment variables included when you download or fork one of our Postman collections, refer to The PingOne Postman environment template.

Our Postman collections use variables in the request URLs to specify the UUIDs for PingOne resources. When you click the Run in Postman button for a collection, these environment variables are included in your download or fork. Use these environment variables as a template to assign your PingOne resource UUIDs with the common variables used in many of the requests.

For more information about using Postman environments, refer to the following topic in the Postman documentation: Environments in Postman.

POST requests in the PingOne DaVinci Admin API Postman collections that create a resource and return a resource ID include a Postman script. This script automatically adds a resource variable to your active Postman environment, and uses the newly created ID as the value.

For example, the following request creates a new DaVinci variable. This request URL contains variables for the API path and environment ID:

POST {{apiPath}}/environments/{{envID}}/variables

To run this request, you must ensure the {{apiPath}} in the Postman environment template has the regional top-level domain (TLD) associated with your organization. Refer to Variables you must value for more information.

Almost every request in PingOne requires an environment ID. If you are working primarily in one environment for testing purposes, you'll want to add your environment's UUID to your active Postman environment as the value for the {{envID}} variable.

Requests to PingOne Management API endpoints require a valid access token to authenticate the request. In the PingOne Postman collections, the token value is represented in the Postman environment template as the variable {{accessToken}}.

With the {{tld}} and {{envID}} variables defined in your Postman template, and with a valid token value defined in the {{accessToken}} variable, you can run the request shown above:

POST {{apiPath}}/environments/{{envID}}/variables

If the request is successful, Postman adds a {{variableID}} variable to the current Postman environment automatically, and associates the new user's id property value (the UUID of the new user) with this variable.

Notes about environment variables and security

It's important to understand how Postman allows you to Store and reuse values using variables. Postman has two values for each environment variable: an Initial value and a Current value. You'll want to pay particular attention to differences between Initial and current values. Initial values are saved to Postman's cloud, and available to anyone who has access to the environment. Current values are saved only locally and available only to you. Postman uses only the current value in requests. If an environment variable has an initial value but no current value, Postman doesn't copy it to the current value or use the initial value in the request, the request simply fails. In this case, you need to manually copy the initial value to the current value.

When you create a new variable with an initial value and save the environment, Postman autofills the current value. However, that is the only time that Postman autofills the current value. If you subsequently delete the current value, the variable is no longer valued in a request.

Saving initial values to the Postman cloud impacts security. These initial values are available to anyone who has access to the workspace. If a workspace is public, you have a security issue.

Postman's recommended solution to exposing secrets is to Store secrets in your Postman Vault. Remember that Postman uses only current values in requests.

Variables you must value

When you download or fork a PingOne Postman collection, your workspace receives a set of Postman environment variables for you to use as a template. The variables that represent a resource in PingOne automatically receive a value when you create a new PingOne resource using Postman. Our script associated with the request (shown on the request's Scripts tab) inserts the identifier of the resource it creates as the value of the variable associated with that resource. However, some variables essential to using Postman with PingOne do not have their values inserted automatically. You must manually add the correct value to these variables before making any requests in Postman: