These early access features are available for preview purposes only, and are not covered under standard Support SLAs. You can open support cases for feedback, bug reports, configuration questions, or other inquiries related to early access features, but resolution times for these cases will vary. These cases often require collaboration with our Engineering and Product teams, so timelines might exceed the usual SLAs for your Support package.

We encourage you to use any of the early access features you find applicable. You'll need to enable each feature you'd like to use. See Early Access Features for instructions.

The early access APIs in Flows and Forms document the deprecated Flow Definitions service in PingOne. The Flow Definitions service was replaced by PingOne DaVinci.

If you want to use Postman

You can download or fork the Postman collection for the early access Flows and Forms APIs, and test them in your Postman environment. If you don't already have a Postman installation, you can install the free version. See Download Postman.

Import or fork the Postman collection PingOne Flows and Forms APIs - Early Access into your Postman installation by clicking the Run in Postman button below:

Refer to Postman and the PingOne APIs for more information.

The external services API allows you to make outbound HTTP requests from PingOne to an external resource server. It functions like a PingOne HTTP client. By configuring an external service resource in PingOne, you configure how to send an HTTP request at invocation time.

PingOne external services configurations integrate with PingOne flows, which allows for outbound HTTP requests in the context of a flow.

Terminology

• External Service

  External services are a group of requests and additional configuration information to support the requests. Some configuration properties, such as variables and secrets, can be referenced by any of the external service’s requests.

• Request

  The HTTP request configuration includes properties such as a URL, headers, and body to define the request to the external resource server. When an external service request is invoked, PingOne uses the defined configuration to create and send an HTTP request.

• PingOne's expression language

  External service requests use PingOne's expression language, which is based on SPEL, to give you flexibility to define complex configuration attributes. For more information, see PingOne's expression language.

Frequently asked questions

Data models

See the following topics for data model property definitions:

• For external services base data model properties, see External Services.

• For external services secrets data model properties, see External Services Secrets.

• For external services invoke data model properties, see External Services Requests.

The Getting Started topics show you how to create an external service with four requests:

• one request that uses static values
• one request that uses a variable
• one request that uses a secret
• one request that uses an input

After creating the external service configuration with these four requests successfully, additional topics show you how to invoke all four external service requests.

Click the Run in Postman button below to download a Postman collection that includes the requests described in this section.

The external services API provides endpoints to create, read, update, and delete external services resources.

External services data model

Requests schema data model

Response codes

You need the Environment Admin role to perform operations on external services resources.

The external services secrets endpoint provides operations to read and update the external service secret. The name property of the external service secret must be unique within the environment. A secret resource is a name-value pair configured by the administrator and applicable to the entire external service. Secret values are encrypted and can be referenced in the external service configuration.

External services secrets data model

Response codes

The external services requests endpoint provides operations to invoke the external service request. The inputs property specifies the inputs required by the request. The request can have several inputs, specified in the following format in the request body:

{
    "inputs": {
        "input1": "input1Value",
        "input2": {
            "aProperty": "aValue"
        },
        "input3": [ { "aProperty": "aValue" } ]
    }
}

External services invocation request data model

External services invocation response data model

Response codes

Flow definitions define a series of steps that designate the actions of a workflow. The flow execution endpoint references a flow definition resource that specifies an initial step and all additional steps required to complete the flow execution. For more information about flow executions, see Flow Executions.

Flow definitions include step definitions that define an operational step to perform a specific work action, which generates output that is processed by the flow. A flow step can also designate flow-control actions that branch or end the flow. For more information, see Flow Definition Steps.

The flow definitions API provides operations to create, read, update, and delete flow definitions. It also provides endpoints to get and enhance flow definition step schema metadata. For information about flow definition step schema metadata, see Flow Definition Steps.

Flow definitions data model

Response codes

Flow definition steps specify the actions of a workflow. The step definition performs a specific operation, which generates output that is processed by the flow. A flow step can also designate flow-control actions that branch or end the flow.

Step definitions data model

Step type metadata data model

Step type metadata enrichment data model

Flow and step definition context placeholders

Flow definition step types

The following section documents the supported flow definition step types and the request schema, response schema, the supported results, and the custom content type (if applicable) associated with any step type actions.

For more information about flow definitions and step types, see Flow Definitions.

This step type specifies a user's consent to an agreement. The result reflects the user's decision to consent to an agreement and saves the user's consent.

Step properties used with flow definitions

The following properties are returned for the SAVED result.

Step properties used with flow executions

This step type specifies a request for consent from the user. Submitting the form initiates a user.consent action to accept or deny consent to the agreement. The following step type definition properties are used with flow definition and flow execution resources.

Step properties used with flow definitions

The following properties are returned for the ACCEPTED result.

Step properties used with flow executions

This step type specifies a request for consent from the user to update the user's consent to an agreement. This step presents a form to the end user to prompt for renewed consent to an agreement. Submitting the form initiates a user.consent action to accept or deny consent to the agreement.

Step properties used with flow definitions

The following properties are returned for the SAVED result.

Step properties used with flow executions

This step type makes an API request to a third-party service.

Step properties used with flow definitions

The following properties are returned for the SUCCEEDED result.

Step properties used with flow executions

This step type branches the flow based on one or more conditions. The step returns a NO_MATCH result if no condition is met. For information about the common policy language used to specify conditions, see Sign-On Policy Actions.

Step properties used with flow definitions

The following properties are returned for the NO_MATCH result.

Step properties used with flow executions

This step type completes the flow and returns a result.

Step properties used with flow definitions

Step properties used with flow executions

This step type creates a risk evaluation in PingOne.

Step properties used with flow definitions

The step returns the risk level of the transaction, which can be evaluated as HIGH, MEDIUM, or LOW. The following properties are returned for the HIGH, MEDIUM, or LOW risk levels.

The following properties are always returned in the risk evaluation.

The following properties are returned in the risk evaluation only for environments with data consent enabled.

Step properties used with flow executions

This step type creates a new user in PingOne.

Step properties used with flow definitions

The following properties are returned for the SUCCEEDED result.

Step properties used with flow executions

This step type prompts the end user to submit a custom form. The step might include additional results for any buttons on the form.

Step properties used with flow definitions

The following properties are returned for the SUBMITTED result.

Step properties used with flow executions

This step type delegates user authentication to an external identity provider.

Step properties used with flow definitions

The following properties are returned for the ACCOUNT_LINKED result.

The following properties are returned for the ACCOUNT_LINKING_REQUIRED result.

Step properties used with flow executions

Properties for the EXTERNAL_AUTHENTICATION_REQUIRED flow state

Flow execution actions

externalAuthentication.check action

This step type invokes an external service request. Note that the input properties in the request and the output properties in the response are generated dynamically based on the input and output schemas defined in the external service configuration.

Step properties used with flow definitions

The following properties are returned for the INVOCATION_OUTPUT result.

Step properties used with flow executions

This step type pairs an MFA offline device automatically with the user account during MFA enrollment.

Step properties used with flow definitions

The following properties are returned for the ENROLLED result.

The following properties are returned for the NOT_APPLICABLE result.

Step properties used with flow executions

This step type performs a multi-factor authentication in PingOne. The step returns a SUCCEEDED result.

Step properties used with flow definitions

The following properties are returned for the SUCCEEDED result.

Step properties used with flow executions

Properties for the DEVICE_SELECTION_REQUIRED flow state

Properties for the OTP_REQUIRED flow state

Properties for the ASSERTION_REQUIRED flow state

Properties for the PUSH_CONFIRMATION_REQUIRED flow state

Properties for the PUSH_CONFIRMATION_TIMED_OUT flow state

Flow execution actions

Device device.select action

Device otp.check action

Device assertion.check action

This step type pairs an MFA device with the user account during MFA enrollment. The step returns either the ENROLLED or SKIPPED result.

Step properties used with flow definitions

The following properties are returned for the ENROLLED result.

The following properties are returned for the SKIPPED result.

Step properties used with flow executions

Properties for the DEVICE_ENROLLMENT_REQUIRED flow state

Properties for the ACTIVATION_REQUIRED flow state

Properties for the PAIRING_REQUIRED flow state

Properties for the MOBILE_PAIRING_FAILURE flow state

Flow execution actions

Device create device.create action

Device activate device.activate action

Device skip device.skipEnrollment action

Device delete device.delete action

Resend OTP otp.resend action

This step type pairs an MFA mobile device with the user account during MFA enrollment.

Step properties used with flow definitions

The following properties are returned for the ENROLLMENT_INITIATED result.

The following properties are returned for the NOT_APPLICABLE result.

Step properties used with flow executions

This step type specifies an action to check a PingOne user's password.

Step properties used with flow definitions

The following properties are returned for the PASSWORD_VALID result.

The following properties are returned for the PASSWORD_EXPIRED result.

The following properties are returned for the MUST_CHANGE_PASSWORD result.

Step properties used with flow executions

This step type verifies an account by prompting for a verification code sent to the user through email. The step returns a VERIFIED result after the verification code is submitted successfully by the end user. The step can also return a SKIPPED result if the user chooses to skip the account verification step.

Step properties used with flow definitions

The following properties are returned for the VERIFIED result.

The following properties are returned for the SKIPPED result.

Step properties used with flow executions

Account verification user.verify action

Account verification user.sendVerificationCode action

Account verification user.skipVerification action

This step type authenticates users with PingID. It is used for passwordless login on Windows devices.

Step properties used with flow definitions

The following properties are returned for the SUCCEEDED result.

Step properties used with flow executions

This step type reads user account data for the user specified by the ID in the input property.

Step properties used with flow definitions

The following properties are returned for the SUCCEEDED result.

Step properties used with flow executions

This step type specifies an action to reset a user's password using the current password.

Step properties used with flow definitions

The following properties are returned for the SUCCEEDED result.

Step properties used with flow executions

This step type specifies an action to send a recovery code to recover a forgotten password.

Step properties used with flow definitions

The following properties are returned for the SUCCEEDED result.

Step properties used with flow executions

This step type ends the flow and returns an error message.

Step properties used with flow definitions

Step properties used with flow executions

This step type specifies an action to update the user record in PingOne.

Step properties used with flow definitions

The following properties are returned for the SUCCEEDED result.

Step properties used with flow executions

This step type that specifies a user lookup action to determine the authentication authority. The response returns either a PING_ONE_USER_MATCHED or IDENTITY_PROVIDER_USER_MATCHED result.

Step properties used with flow definitions

The following properties are returned for the PING_ONE_USER_MATCHED result.

The following properties are returned for the IDENTITY_PROVIDER_USER_MATCHED result.

Step properties used with flow executions

This step type verifies an account by prompting for a verification code sent to the user through email. The step returns a VERIFIED result after the verification code is submitted successfully by the end user. The step can also return a SKIPPED result if the user chooses to skip the account verification step.

Step properties used with flow definitions

The following properties are returned for the VERIFIED result.

The following properties are returned for the SKIPPED result.

Step properties used with flow executions

Account verification user.verify action

Account verification user.sendVerificationCode action

Account verification user.skipVerification action

The forms API, which supports the form builder interface in the PingOne Admin Console, provides tools for administrators to create custom forms presented to users during the authentication workflow. This capability allows administrators to:

• Define the interactive fields and the corresponding data to be collected during a registration or sign-on flow, which could include text inputs, checkboxes, dropdowns, and radio buttons with the potential for dynamic options or dynamically static options (dropdowns with options saved as part of the form or as input for an argument).

• Define the user experience that they want to deliver to the customer, such as field ordering, labeling, control over input validation and error feedback, and support for contextual or formatting items such as text (headers, explanatory text) images, and dividers.

The forms API provides endpoints to create, read, update, and delete form builder resources.

Forms category types

The API allows the following form types:

• REGISTRATION

  A registration form that allows administrators to configure the controls and the information gathered during the registration flow. This form type allows form fields that do not map directly to PingOne user schema properties.

• SELF_SERVICE

  A self-service form that allows administrators to configure the controls and the information gathered during a self-service flow. All fields in the self-service form must be associated with PingOne user schema properties.

• PROGRESSIVE_PROFILING

  A custom registration form that prompts the user for additional information during the registration or sign-on flow. All fields in the progressive profiling form must be associated with PingOne user schema properties.

• CUSTOM

  A custom registration form that allows form fields that do not map directly to PingOne user schema properties. For example, the form could include radio buttons with options of “employee” or “contractor” that the flow manager processes to direct the user to the next relevant form.

Forms data model

Form components data model

FormField data model

• FormElement represents a FormField of types TEXT, PASSWORD, RADIO, CHECKBOX, DROPDOWN.
• FormItem represents a FormField of types DIVIDER, PARAGRAPH, EMPTY_FIELD, ERROR_DISPLAY.
• FormElementPasswordVerify represents a FormField of type PASSWORD_VERIFY.
• FormSubmit represents a FormField of type SUBMIT_BUTTON.
• FormFlowLink represents FormField of type FLOW_LINK.
• FormFlowButton represents a FormField of type FLOW_BUTTON.
• FormRecaptchaV2 represents a FormField of type RECAPTCHA_V2.
• FormQrCode represents a FormField of type QR_CODE.

FormElement data model

FormElementPasswordVerify data model

The FormElementPasswordVerify object is an extension of FormElement and contains all of the same fields in FormElement as well as those listed below.

FormItem data model

Response codes

The Recaptcha configuration API provides support for a Recaptcha V2 field in a form definition. It includes operations to read, update, and delete the environment's Recaptcha configuration.

Recaptcha V2 data model

Response codes

The Configuration Management service gives you a secure and flexible approach to automating (promoting) configurations across multiple environments, enabling the seamless creation, updating, and deletion of resources while supporting dynamic configurations through variable management. Resource dependencies are maintained, ensuring smooth cross-environment transitions and promotions. Auditing and reporting enhance oversight and compliance.

To use the Configuration Management service you need to have the Environment Admin role for at least two environments. The general workflow is:

• Select configurations that you want to promote from one environment to another (generally, through development, testing, and production stages).
• If desired, use promotion variables to dynamically substitute different property values for a configuration resource included in a promotion operation.
• Execute the promotion plan returned by the Read One Promotion or Read All Promotions to move the configuration from the source environment to the target environment.

The Configuration Management service is comprised of these sub-services:

• Snapshots
• Promotions
• Promotion Variables
• Promotion Configuration

Resources requiring special handling

Certificates

Certificates are not a promotable resource in PingOne, however special handling of them is required for resources that reference them. Certificate references can be promoted in using either default certificates or through the use of promotion variables:

• Default certificates

  When a configuration resource is using the default certificate as its signing key (a SAML application, for example), the application can be promoted, and will reference the default signing key existing in the target environment. Certificate rotation for the signing key can be done by setting a new default certificate in the target environment, and then promoting the configuration resource or resources using the default signing key in the source environment.

• Certificates as promotion variables

  You can handle all certificate references other than default certificates using promotion variables. You'll need to create a promotion variable with the certificate ID in each environment. When the resource or resources referencing the certificate are promoted, the promotion operation will use the variable value to substitute the correct certificate in the target environment or environments. If there are other configuration resources that use the certificate, they will also use the correct certificate when any of these configuration resources are promoted to the same target environment or environments.

Attributes

You can promote individual attributes in the schema. However if you're promoting an application that references a custom attribute, the promotion plan will include all attributes in the schema. In this case, you can then exclude the unnecessary attributes by editing the promotion plan prior to starting the promotion operation.

If you want to use Postman

You can download or fork the Postman collection for the early access Configuration Management APIs, and test them in your Postman environment. If you don't already have a Postman installation, you can install the free version. See Download Postman.

Import or fork the Postman collection PingOne Configuration Management APIs - Early Access into your Postman installation by clicking the Run in Postman button below:

Refer to Postman and the PingOne APIs for more information.

A snapshot is a point in time representation of any configuration resource in PingOne. A snapshot is triggered when the request POST {{apiPath}}/environments/{{envID}}/snapshots is called. The configuration resource, and optionally all of its dependencies, are then stored by the Snapshot service. The snapshots are stored and indexed using the original identifier (ID) of the configuration resource. For example, an applications snapshot will be stored using the ID of the application. Subsequent calls to the request POST {{apiPath}}/environments/{{envID}}/snapshots for the same configuration resource generates a new version of the configuration resource each time the request is called. You can retrieve the version history of any configuration resource using the original identifier of the resource. You'll use the snapshot created for a configuration resource to promote (apply) the configuration resource from the source environment to another environment.

Snapshots data model

A promotion includes, at a minimum, source and target environment references, automatically generated source and target snapshots, the resource or resources to promote to the target environment, and a promotion plan for the promotion operation. You need to have the Environment Admin role for both the source and target environments. You can optionally include a specific source environment snapshot to use, as well as a mapping of the source environment configuration resource or resources to the target environment configuration resource or resources.

A PingOne admin having Environment Admin permissions can review the promotion plan, and update the promotion mapping and variable definitions or declarations as needed. The promotion plan is then regenerated based on the updates. Use the Read One Promotion or Read All Promotions to view the promotion plan.

If you do not set any promotion variables, the configuration resource or resources that you specify for the source or target environment will be used as is, and cannot be changed during the promotion operation. See Promotion Variables for more information.

When you choose to start the promotion operation, the promotion plan supplies the promotion operation instructions to the Promotions service. The Promotions service then:

• Filters out any configuration resources that haven't changed, and calls the required target environment API using the new or altered resources.
• Sets the promotion’s started_at and status values.
• Collects any errors into a JSON array, and returns the errors.
• Updates the promotion's completedAt and status values when the promotion operation is complete.

Promotions data model

Currently, not all resources, services, or products can be used in a promotion operation.

Excluded products or services

• PingOne DaVinci (except for Forms)
• PingOne Authorize

Excluded resources

Some resources can never be promoted, while others will be supported for promotion, but currently are not.

Permanently excluded resources

These resources are expected to never be supported for promotion:

• Active Identity Counts
• Activities
• Adaptive Trust Policies
• Applications Role Assignments
• Application Signons
• Application Signons Statistics
• Certificates
• Connectors
• Dashboards
• Data Exploration Batches
• Data Explorations
• Data Exploration Templates
• Licenses
• Licenses Expires At
• Licenses Metrics Active Identity Counts
• Licenses Name
• PingOne for Enterprise Orchestrations
• PingOne for Enterprise Callback

Currently excluded resources

These resources will be supported for promotion, but are not currently:

• Admin Config
• API Servers
• Application Entitlements
• Application Permissions
• Application Resources
• Application Roles
• Applications Secret
• Authorization Attributes
• Authorization Changes
• Authorization Conditions
• Authorization Connector Templates
• Authorization Policies
• Authorization Processors
• Authorization Rules
• Authorization Services
• Authorization Statements
• Branding Settings
• Connector Instances
• Credential Counts
• Credential Issuer Profile
• Credential Types
• Custom Domains
• Davinci Applications
• Decision Endpoints
• Delegated Admins
• Device Authentications
• Digital Wallet Applications
• External Services
• Fido Devices Metadata
• Flow Definitions
• Flow Metadata
• Flow Policies
• Flows
• Fraud Evaluations
• Fraud Events Details
• Fraud Feedbacks
• Fraud Sessions
• Identity Cloud
• Identity Cloud Orchestrations
• Images
• Integrations
• Languages
• Legacy
• Locales
• Metrics
• Migrate
• Notification Callback
• Notification Callback AWS email
• Notification Callback Syniverse
• Notification Callback Twilio
• Notification Callback Whatsapp
• Notifications
• Notifications Quota
• OAuth Jobs
• OAuth Tokens
• Organization Quota
• Password Storage Scheme Config
• Pingid
• Pingid Mobile App Versions
• Pingid Mobile Display Names
• Pingid Mobile Os Versions
• Portal
• Presentation Sessions
• Promotions
• Promotion Variable Declarations
• Propagation
• Propagation Mappings
• Propagation Plans
• Propagation Provisioning Syncs
• Propagation Revisions ID
• Propagation Revisions ID Latest
• Propagation Rules
• Propagation Store Metadata
• Propagation Stores
• QS Dashboards
• Rate Limit IP Configs
• Recaptcha V2 Config
• Resources Secret
• Risk Evaluations
• Risk Feedback
• Roles
• Seen Devices
• Sessions
• Snapshots
• Software Licenses
• Solutions
• Subscriptions
• Tiles
• Total Identities
• Translations
• Users
• Variables
• Voice Phrases

Use promotion variables to to account for environment-specific differences, such as 3rd party integrations or URLs. You can specify configuration resource property values for either the source or target environment to be substituted for existing property values by the promotion operation. Only the promotion variables you set can change property values for use by the promotion operation. If you do not set any promotion variables, the configuration resource or resources that you specify for the source or target environment will be used as is, and cannot be changed during the promotion operation.

To use promotion variables, you need to:

1. Specify the configuration resource to be promoted in a snapshot.
2. Define the variable or variables to be used for a source or target environment configuration resource property. See Variable Definitions.
3. Declare the variables to be used by the promotion operation. See Variable Declarations.

A few things to be aware of:

• The variables are scoped only to the specified configuration resources, and are not applied to any dependent resources.
• Variables are not versioned with a snapshot, so for each promotion operation, you need to ensure the variable settings for a configuration resource are correct.
• Any configuration resources that you change directly without updating the variables will be overwritten by a subsequent promotion operation. This is because the promotion operation will use the existing variable set.

Not all configuration resources or properties can be used as promotion variables. Here's the listing of configuration resources, and the associated properties that are supported as promotion variables:

When promoting a configuration, you need to define any variables you intend to use to substitute for existing property values. Once defined, you'll need to then declare a variable. See Variable Declarations for details.

Variable definitions data model

Before you can declare a variable (POST {{apiPath}}/environments/{{envID}}/promotionVariableDeclarations), you need to define the variable that you intend to use. See Variable Definitions for details.

Variable declarations data model

The promotionConfiguration endpoint sets and reads default target environment to be used for promotions. When you know that you'll be working with a specific target environment, you can set this environment as the default for the promotions you're doing.

The PingOne Authorize trust framework service provides endpoints to define the entities and configurations to target policies and rules when making dynamic authorization requests.

The trust framework is based on attributes. These attributes have resolvers which bring contextual data values into the attribute. Resolvers can be conditional using an embedded condition or they can be a reference to a condition entity.

A service resolver references a service that can call out to a third-party HTTP service or the PingOne Protect service. Attributes can transform the value received from resolvers using embedded processors or referenced processors.

To create and manage the attributes, services, conditions, and processors, required by the PingOne Authorize trust framework, see:

• Authorization attributes

  Provides endpoints to create, read, update, test, and delete trust framework authorization attributes.

• Authorization services

  Provides endpoints to create, read, update, test, and delete trust framework authorization services.

• Authorization conditions

  Provides endpoints to create, read, update, test, and delete trust framework authorization conditions.

• Authorization processors

  Provides endpoints to create, read, update, and delete trust framework authorization processors.

• Authorization connector templates

  Provides an endpoint to read trust framework authorization connector templates.

If you want to use Postman

You can download or fork the Postman collection for the early access PingOne Authorize Trust Framework APIs, and test them in your Postman environment. If you don't already have a Postman installation, you can install the free version. See Download Postman.

Import or fork the Postman collection PingOne Authorize Trust Framework APIs - Early Access into your Postman installation by clicking the Run in Postman button below:

Refer to Postman and the PingOne APIs for more information.

Authorization attributes provide contextual information that informs fine-grained dynamic authorization decisions. Attributes have the following characteristics:

• An attribute has zero or more resolvers that bring the contextual data into the attribute value. The list of ordered resolvers are evaluated sequentially until a successful value is returned.

• An attribute has zero or more processors that transform the data coming from the resolvers.

• An attribute has a valueType property value that specifies the final output type of the attribute.

Authorization attributes data model

Authorization attributes resolvers type data model

Event types

The audit reporting events applicable to the authorize attribute service are:

Response codes

Authorization services, also referred to as Policy Information Points or PIPs, represent third-party HTTP services or internal PingOne platform services (such as PingOne Protect) that may be called to retrieve data.

These endpoints provide operations to create, read, update, test, and delete authorization services.

Authorization services data model