Flows

The GET /{{envID}}/flows/{{flowID}} operation retrieves the flow specified by the flowID in the request URL. For more information about this flow action, refer to Get a flow.

Flow API actions

The flow endpoint operation, POST /{{envID}}/flows/{{flowID}}, supports several flow actions that are specified by the custom media type provided in the HTTP Content-Type request header. The following table lists the PingOne custom media types and their associated authentication flow actions:

Media type Flow action

Media type	Flow action
`application/vnd.pingidentity.session.reset+json`	Update or reset a flow
`application/vnd.pingidentity.usernamePassword.check+json`	Sign on with a username and password
`application/vnd.pingidentity.user.lookup+json`	Sign on with a username in a passwordless flow
`application/vnd.pingidentity.password.forgot+json`	Forgot password
`application/vnd.pingidentity.user.register+json `	Register a user
`application/vnd.pingidentity.usernamePassword.check+json`	Check a user’s password
`application/vnd.pingidentity.password.reset+json`	Reset a user’s password
`application/vnd.pingidentity.password.recover+json`	Recover a user’s password
`application/vnd.pingidentity.password.sendRecoveryCode`	Send the user a recovery code
`application/vnd.pingidentity.user.verify+json`	Verify a user
`application/vnd.pingidentity.user.sendVerificationCode+json`	Send the user a verification email
`application/vnd.pingidentity.device.select+json`	Select an MFA device
`application/vnd.pingidentity.otp.check+json`	Validate the one-time password
`application/vnd.pingidentity.user.update+json`	Submit profile data
`application/vnd.pingidentity.user.confirm+json`	Confirm account information
`application/vnd.pingidentity.assertion.check+json`	Check assertion
`application/vnd.pingidentity.user.consent+json`	Agreement Accept Consent
`application/vnd.pingidentity.kerberos.lookup+json`	Sign on using Kerberos
`application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json`	Confirm Device Activation Code
`application/vnd.pingidentity.deviceAuthGrant.consent+json`	Accept Device Authorization Grant Consent

application/vnd.pingidentity.session.reset+json

Update or reset a flow

application/vnd.pingidentity.usernamePassword.check+json

Sign on with a username and password

application/vnd.pingidentity.user.lookup+json

Sign on with a username in a passwordless flow

application/vnd.pingidentity.password.forgot+json

Forgot password

`application/vnd.pingidentity.user.register+json `

application/vnd.pingidentity.usernamePassword.check+json

Check a user’s password

application/vnd.pingidentity.password.reset+json

Reset a user’s password

application/vnd.pingidentity.password.recover+json

Recover a user’s password

application/vnd.pingidentity.password.sendRecoveryCode

Send the user a recovery code

application/vnd.pingidentity.user.verify+json

Verify a user

application/vnd.pingidentity.user.sendVerificationCode+json

Send the user a verification email

application/vnd.pingidentity.device.select+json

Select an MFA device

application/vnd.pingidentity.otp.check+json

Validate the one-time password

application/vnd.pingidentity.user.update+json

Submit profile data

application/vnd.pingidentity.user.confirm+json

Confirm account information

application/vnd.pingidentity.assertion.check+json

Check assertion

application/vnd.pingidentity.user.consent+json

Agreement Accept Consent

application/vnd.pingidentity.kerberos.lookup+json

Sign on using Kerberos

application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json

Confirm Device Activation Code

application/vnd.pingidentity.deviceAuthGrant.consent+json

Accept Device Authorization Grant Consent

Flows common response data model

These common properties are returned with the flow response.

Property Type Required? Mutable? Description

Property	Type	Required?	Mutable?	Description
`aggregateFido2Devices`	Boolean	N/A	Read-only	Indication of whether the available authentication method list should include only a single generic FIDO2 option rather than including an entry for each paired FIDO2 device.
`application`	Object		Immutable	A reference to the application that initiated the flow.
`application.id`	String		Immutable	A string that specifies the ID of the application that initiated the flow.
`application.name`	String		Immutable	A string that specifies the name of the application that initiated the flow.
`application.icon.id`	String		Immutable	A string that specifies the icon ID for the application that initiated the flow.
`application.icon.href`	String		Immutable	A string that specifies the URL of the icon for the application that initiated the flow.
`authenticator`	Array		Read only	An array that specifies the set of authentication methods that the user completed in this flow. The values returned by the flow must use the values defined in RFC 8176. The order of the methods returned by the flow might not reflect the order in which they were executed in the flow.
`authorizeResponse.access_token`	String		Read only	A string that specifies the access token returned by the flow in a non-redirect or MFA only authentication flow (for an `implicit` authorization request).
`authorizeResponse.id_token`	String		Read only	A string that specifies the ID token returned by the flow in a non-redirect or MFA only authentication flow (for an `implicit` authorization request).
`authorizeResponse.code`	String		Read only	A string that specifies the authorization code returned by the flow in a non-redirect or MFA only authentication flow (for an `authorization_code` authorization request).
`authorizeResponse.state`	String		Immutable	A string that specifies the authorization `state` (used to maintain state between the logout request and the callback to the redirect URI) returned by the flow in a non-redirect or MFA only authentication flow (for an `authorization_code` authorization request).
`completedSignOnPolicy.id`	String		Read only	A string that specifies the ID of the completed sign-on policy resource after the flow is `COMPLETED`.
`completedSignOnPolicy.name`	String		Read only	A string that specifies the name of the completed sign-on policy after the flow is `COMPLETED`.
`createdAt`	Date		Read only	The time the resource was created.
`expiresAt`	Date		Read only	The time this flow will expire due to inactivity timeout based on a sliding window.
`id`	String		Immutable	A string that specifies the flow resource’s unique identifier.
`identifier`	String		Immutable	A string that specifies a `username` value returned from the `login_hint` property.
`resumeUrl`	String		Immutable	A string that specifies where the flow handler UI will redirect the browser to after the flow is `COMPLETED` or `FAILED`.
`status`	String		Immutable	A string that specifies the status of the flow.
`user.id`	String		Immutable	A string that specifies the ID of the session user. This value is used for authentication flows initiated with an existing session’s unique ID.

aggregateFido2Devices

Boolean

N/A

Read-only

Indication of whether the available authentication method list should include only a single generic FIDO2 option rather than including an entry for each paired FIDO2 device.

application

Object

Immutable

A reference to the application that initiated the flow.

application.id

String

Immutable

A string that specifies the ID of the application that initiated the flow.

application.name

String

Immutable

A string that specifies the name of the application that initiated the flow.

application.icon.id

String

Immutable

A string that specifies the icon ID for the application that initiated the flow.

application.icon.href

String

Immutable

A string that specifies the URL of the icon for the application that initiated the flow.

authenticator

Array

Read only

An array that specifies the set of authentication methods that the user completed in this flow. The values returned by the flow must use the values defined in RFC 8176. The order of the methods returned by the flow might not reflect the order in which they were executed in the flow.

authorizeResponse.access_token

String

Read only

A string that specifies the access token returned by the flow in a non-redirect or MFA only authentication flow (for an implicit authorization request).

authorizeResponse.id_token

String

Read only

A string that specifies the ID token returned by the flow in a non-redirect or MFA only authentication flow (for an implicit authorization request).

authorizeResponse.code

String

Read only

A string that specifies the authorization code returned by the flow in a non-redirect or MFA only authentication flow (for an authorization_code authorization request).

authorizeResponse.state

String

Immutable

A string that specifies the authorization state (used to maintain state between the logout request and the callback to the redirect URI) returned by the flow in a non-redirect or MFA only authentication flow (for an authorization_code authorization request).

completedSignOnPolicy.id

String

Read only

A string that specifies the ID of the completed sign-on policy resource after the flow is COMPLETED.

completedSignOnPolicy.name

String

Read only

A string that specifies the name of the completed sign-on policy after the flow is COMPLETED.

createdAt

Date

Read only

The time the resource was created.

expiresAt

Date

Read only

The time this flow will expire due to inactivity timeout based on a sliding window.

id

String

Immutable

A string that specifies the flow resource’s unique identifier.

identifier

String

Immutable

A string that specifies a username value returned from the login_hint property.

resumeUrl

String

Immutable

A string that specifies where the flow handler UI will redirect the browser to after the flow is COMPLETED or FAILED.

status

String

Immutable

A string that specifies the status of the flow.

user.id

String

Immutable

A string that specifies the ID of the session user. This value is used for authentication flows initiated with an existing session’s unique ID.

These common links are returned with the flow response.

Links Description

Links	Description
`self`	The link to the current flow resource.
`session.reset`	The link to the session reset action. This link is present if the user has signed on previously on this device. It can be used to sign off the user and reset the flow.

self

The link to the current flow resource.

session.reset

The link to the session reset action. This link is present if the user has signed on previously on this device. It can be used to sign off the user and reset the flow.

These common embedded resources are returned with the flow response:

Embedded resources Description

Embedded resources	Description
`devices`	List of objects containing the properties of each devices associated with the user.
`devices[].otpStatus.status`	Whether or not the device can be used currently for OTP-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where `type` is MOBILE.
`devices[].otpStatus.reason`	If the status is DISABLED, contains the reason that the device cannot be used for OTP-based authentication, for example, that the application used a version of the MFA SDK that does not support OTP. Relevant only for devices where `type` is MOBILE.
`devices[].pushStatus.status`	Whether or not the device can be used currently for push-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where `type` is MOBILE.
`devices[].pushStatus.reason`	If the status is DISABLED, contains the reason that the device cannot be used for push-based authentication, for example, that the push option was disabled for the application in the MFA policy. Relevant only for devices where `type` is MOBILE.
`devices[].usableStatus.status`	Whether or not the device can be used currently for authentication. Value returned is ENABLED or DISABLED.
`devices[].usableStatus.reason`	If the status is DISABLED, contains the reason that the device cannot be used for authentication, for example, that the defined daily notifications limit has already been reached.
`user`	The link to the resource containing profile attributes of the actively signing-on or previously signed-on user.

devices

List of objects containing the properties of each devices associated with the user.

devices[].otpStatus.status

Whether or not the device can be used currently for OTP-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where type is MOBILE.

devices[].otpStatus.reason

If the status is DISABLED, contains the reason that the device cannot be used for OTP-based authentication, for example, that the application used a version of the MFA SDK that does not support OTP. Relevant only for devices where type is MOBILE.

devices[].pushStatus.status

Whether or not the device can be used currently for push-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where type is MOBILE.

devices[].pushStatus.reason

If the status is DISABLED, contains the reason that the device cannot be used for push-based authentication, for example, that the push option was disabled for the application in the MFA policy. Relevant only for devices where type is MOBILE.

devices[].usableStatus.status

Whether or not the device can be used currently for authentication. Value returned is ENABLED or DISABLED.

devices[].usableStatus.reason

If the status is DISABLED, contains the reason that the device cannot be used for authentication, for example, that the defined daily notifications limit has already been reached.

user

The link to the resource containing profile attributes of the actively signing-on or previously signed-on user.

Flows events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Code	Message
200	Successful operation.
201	Successfully created.
204	Successfully removed. No content.
400	The request could not be completed.
401	You weren’t authenticated to perform this operation.
404	The requested resource was not found.

Flow endpoints use a session token cookie to associate an authenticated user with the flow session. For flows started through the authorize endpoint that call the read flow endpoint, a session token cookie is set only after the identity of the user has been partially established. For example, if the sign-on policy specifies identifier first and MFA actions, then the cookie is set after the user is identified through a user lookup action and provides the correct password. Conversely, for a flow initiated in a browser that already has a valid session token cookie, calling the flow requires the session token cookie, which can be passed in as a request header (for example, -H "Cookie: ST=12345174-cf3b-47e4-b22a-12a76d0116a5").

Custom login application developers can handle cookies through a browser or, for non-browser authentication flows, in the same manner as a browser, by saving the cookies when returned in an HTTP response from PingOne, and including them on subsequent requests. Also, application developers should use the cookie handling features of the development platform or HTTP client library (or both) whenever possible.

PingOne Platform APIs

Flows

Flow API actions

Flows common response data model

Flows events generated

Response codes