The flow execution API defines triggers that initiate a flow execution. When a flow execution is triggered, the status of a flow is in either a terminal state (COMPLETED or ERROR) or in a progress state defined by the step definitions defined in the flow definition. For more information about flow definitions, see Flow Definitions and Flow Definition Steps.

After the flow execution completes, the end user can be redirected back to the workflow to complete authentication.

Flow execution walkthrough (registration example)

The following describes the flow execution workflow:

  1. The sign-on workflow is initiated through OAuth or SAML, which redirects to the sign-on screen (either the PingOne screen or a custom interface).

  2. The interface loads the flow, which includes a link to the /flowExecutions endpoint to trigger the flow configured for the sign-on policy action.

  3. The end-user clicks the link to trigger flow execution, which validates the redirect URI and transitions to the /experiences endpoint, and sets the flow execution session token cookie on the user agent.

  4. The end-user completes the flow execution, which, in the context of a registration flow, has created and optionally verified a user.

  5. The experience interface redirects the browser back to the redirect URI, which includes the flow execution ID as a query parameter.

  6. If the flow status is COMPLETED, it redirects to the resume URL (OAuth and SAML). If the flow is not complete, it redirects to the sign-on screen to allow the user to continue on with the flow.

Flow execution base data model

Property Description
createdAt The time this flow execution started.
environment.id A string that specifies the environment ID associated with this flow execution.
error An object that when the status is ERROR, it returns an error detail associated with this flow execution.
error.code A string that specifies the PingOne code for the error.
error.message A string that specifies the description of the error.
expiresAt The time this flow execution will expire due to an inactivity timeout based on a sliding window.
flowDefinition A reference to the PingOne flow definition associated with this flow execution. This property is required.
flowDefinition.id A string that specifies the flow definition ID associated with this flow execution. This property is required.
flowDefinition.name A string that specifies the flow definition name.
inputs An object that specifies trigger-specific input parameters.
outputs An object that specifies trigger-specific output parameters when the flow status is COMPLETED.
result A string that specifies the trigger-specific result code of the flow when a state is COMPLETED. For example, REDIRECT.
state A string that specifies the current state of this flow. Options are COMPLETED and ERROR.
trigger A string that specifies the trigger type used to initiate the flow. Currently, the only option is EXPERIENCE.
updatedAt The time this flow execution was last updated.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
302 Found.
400 The request could not be completed.
401 You weren’t authenticated to perform this operation.
403 You do not have permissions or are not licensed to make this request.