Flow actions
The flow endpoint is used to interact with the end-user in a sign-on workflow. Flow endpoint operations are used only to implement custom authentication UIs. OIDC/OAuth 2 and SAML requests initiate the flow and redirect the browser to the custom authentication UI (which is configured in the application through the application’s loginPageUrl
property.)
Login actions
The flow endpoint can initiate login actions that specify the operations required to authenticate with a username and password.
Multi-factor authentication actions
The flow endpoint can also initiate multi-factor authentication (MFA) actions that specify the operations required to complete authentication using a registered user device and a one-time password (OTP).
Flow API operations
The flow endpoints support the following operations:
-
POST /{environmentId}/flows/{flowID}/steps/{stepId}
Login with username and password -
POST /{environmentId}/flows/{flowId}
Validate the one-time password -
POST /{environmentId}/flows/{flowId}
Recover a user password -
POST /{environmentId}/flows/{flowId}
Send verification email
For hands-on experience with the flow endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.
Flows data model
Property | Description |
---|---|
createdAt |
The time the resource was created. |
expiresAt |
The time this flow will expire due to inactivity timeout based on a sliding window. |
id |
A string that specifies the flow resource’s unique identifier. |
resumeUrl |
A string that specifies where the flow handler UI will redirect the browser to after flow is COMPLETED or FAILED . |
status |
A string that specifies the status of the flow. Options are COMPLETED , FAILED , or ACTION_REQUIRED , where the required action specifies the next action in the flow (for example, USERNAME_PASSWORD_REQUIRED ). |
user.id |
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. |
Login actions data model
Property | Description |
---|---|
action.id |
A string that specifies the identifier of the resource referenced by this relationship. |
action.type |
A string that specifies the type of the resource referenced by this relationship. |
currentPassword |
A string that specifies the user’s current password. |
flow.id |
A string that specifies the identifier of the resource referenced by this relationship. |
id |
A string that specifies the resource’s unique identifier. |
newPassword |
A string that specifies the user’s new password… |
password |
A string that specifies the password used to authenticate. |
status |
A string that specifies the status of the action. Action services can use any value except COMPLETED . |
username |
A string that specifies the username used to authenticate. |
Multi-factor authentication actions data model
Property | Description |
---|---|
action.id |
A string that specifies the identifier of the resource referenced by this relationship. |
action.type |
A string that specifies the type of the resource referenced by this relationship. |
currentPassword |
A string that specifies the user’s current password. |
device.id |
A string that specifies the device resource’s unique identifier. |
flow.id |
A string that specifies the identifier of the resource referenced by this relationship. |
id |
A string that specifies the resource’s unique identifier. |
otp |
A string that specifies the one-time password. |
selectedDevice.id |
A string that specifies the identifier of the resource referenced by this relationship. |
status |
A string that specifies the status of the action. Action services can use any value except COMPLETED . |
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. |
Endpoint examples
Reset a flow
The following sample shows the POST /{environmentId}/flows/{flowID}
operation that updates (or resets) a flow orchestration session. This operation uses the application/vnd.pingidentity.session.reset+json
custom media type as the content type in the request header.
curl -X POST \
'https://auth.pingone.com/{environmentId}/flows/{flowID}' \
-H 'Content-Type: application/vnd.pingidentity.session.reset+json' \
-H "Cookie: ST=<sessionToken>"
Get a flow
You can use the GET /{environmentId}/flows/{flowID}
operation to retrieve information about a flow specified by the flow ID in the request URL.
curl -X GET \
'https://auth.pingone.com/{environmentId}/flows/{flowID}' \
-H 'Content-Type: application/json' \
-H 'Cookie: ST=<sessionToken>'
The status
property in the response specifies the next action in the authentication flow. The response data looks like this:
{
"_links" : {
"self" : {
"href" : "https://auth.pingone.com/{environmentId}/flows/{flowID}"
},
"session.reset" : {
"href" : "https://auth.pingone.com/{environmentId}/flows/{flowID}"
},
"usernamePassword.check" : {
"href" : "https://auth.pingone.com/{environmentId}/flows/{flowID}"
}
},
"id" : "7b37d3e8-38b0-4469-b553-04b8bee08e6f",
"resumeUrl" : "https://auth.pingone.com/{environmentId}/as/resume?flowId={flowID}",
"status" : "USERNAME_PASSWORD_REQUIRED",
"createdAt" : "2018-09-20T13:40:56.977Z",
"expiresAt" : "2018-09-20T13:55:59.213Z",
}
Note: The response includes the HAL link to the usernamePassword.check
action, which is identified in the status
property as the next required operation. This link can be used to initiate the next step in the authentication flow.
Login with username and password
You can use the POST /{environmentId}/flows/{flowId}
operation to initiate an action to allow users to login the username and password. The request body requires the username
and password
attributes. The values for these properties provided by the user are verified in this action. This operation uses the application/vnd.pingidentity.usernamePassword.check+json
custom media type as the content type in the request header.
Note: If there is a user already associated with the current flow, and a username
value is provided in the request body, then the value of username
must identify the user associated with the session.
curl -X POST \
'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
-H 'Content-Type: application/vnd.pingidentity.usernamePassword.check+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
"username": "<username>",
"password": "<password>"
}'
The response data looks like this. In this case the status
property value in the response indicates that the one-time password validation step used in a multi-factor authentication flow is a required action. The validateOTP
HAL link to initiate this required step is also included in the response.
{
"_links": {
"self": {
"href": "https://auth.pingone.com/{environmentId}/flows/{flowID}"
},
"session.reset": {
"href": "https://auth.pingone.com/{environmentId}/flows/{flowID}"
},
"validateOTP": {
"href": "https://auth.pingone.com/{environmentId}/flows/{flowID}"
}
},
"id": "7b37d3e8-38b0-4469-b553-04b8bee08e6f",
"resumeUrl": "https://auth.pingone.com/{environmentId}/as/resume?flowId={flowID}",
"status": "OTP_REQUIRED",
"requiredStep": {
"id": "1a03bd20-4348-4b40-a4f9-e5a0c629aae1"
},
"selectedDevice": {
"id": "341762d5-22c4-bdf3-3417-62d522c4bdf3"
},
"createdAt": "2018-09-20T13:40:56.977Z",
"expiresAt": "2018-09-20T13:56:12.306Z",
"_embedded": {
"devices": [
{
"id": "341762d5-22c4-bdf3-3417-62d522c4bdf3",
"environment": {
"id": "{environmentId}"
},
"type": "EMAIL",
"email": "jo****@pingidentity.com",
"user": {
"id": "482a626f-a894-485d-b9f3-ba8f4ed0c58d"
}
}
],
"user": {
"id": "482a626f-a894-485d-b9f3-ba8f4ed0c58d",
"username": "johndoe",
"name": {
"given": "John",
"family": "Doe"
}
}
}
}
Validate the OTP
The multi-factor authentication flow uses a one-time password (OPT) sent to the user’s device to continue the login flow. The user receives the OTP and submits it as a step in the login process. The MFA actions service validates the OTP to complete the authentication flow.
The following sample shows the POST /{environmentId}/flows/{flowId}
operation to validate the OTP used in the multi-factor authentication flow. This operation uses the application/vnd.pingidentity.otp.check+json
custom media type as the content type in the request header.
curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}" \
-H 'Content-type: application/vnd.pingidentity.otp.check+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
"otp": "<otp>"
}'
The response data looks like this. If completed successfully, and if this action is the last action of the authentication flow, the status
property shows a value of COMPLETED
.
{
"_links": {
"self": {
"href": "https://auth.pingone.com/{environmentId}/flows/{flowId}"
},
"id": "7b37d3e8-38b0-4469-b553-04b8bee08e6f",
"resumeUrl": "https://auth.pingone.com/{environmentId}/as/resume?flowId={flowId}",
"status": "COMPLETED",
"createdAt": "2018-09-20T13:40:56.977Z",
"expiresAt": "2018-09-20T13:56:12.306Z",
"_embedded": {
"user": {
"id": "482a626f-a894-485d-b9f3-ba8f4ed0c58d",
"username": "johndoe",
"name": {
"given": "John",
"family": "Doe"
}
}
}
}
}
Forgot password
You can also use the POST /{environmentId}/flows/{flowId}
operation to initiate an action to recover a user’s forgotten password. The request body requires the username
attribute to identify the user and send a one-time password (OTP) that is used to set a new password. This operation uses the application/vnd.pingidentity.password.forgot+json
custom media type as the content type in the request header.
curl -X POST \
'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
-H 'Content-Type: application/vnd.pingidentity.password.forgot+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
"username": "<new password>"
}'
Register a user
You can use the POST /{environmentId}/flows/{flowId}
operation to initiate an action to register a user. The request body requires the username
, email
, and password
attributes needed to define a new user. This operation uses the application/vnd.pingidentity.user.register+json
custom media type as the content type in the request header.
curl -X POST \
'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
-H 'Content-Type: application/vnd.pingidentity.user.register+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
"username": "user1",
"email": "user1@pingidentity.com",
"password": "<password>"
}'
Check password
You can also use the POST /{environmentId}/flows/{flowId}
operation to initiate an action to allow users to login with their password. The request body requires the username
and password
attributes. This operation uses the application/vnd.pingidentity.usernamePassword.check+json
custom media type as the content type in the request header.
curl -X POST \
'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
-H 'Content-Type: application/vnd.pingidentity.password.reset+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
"username": "user1",
"password": "<password>"
}'
Reset password
You can also use the POST /{environmentId}/flows/{flowId}
operation to initiate an action to change (or reset) the user’s password. The request body requires the currentPassword
and newPassword
attributes. This operation uses the application/vnd.pingidentity.password.reset+json
custom media type as the content type in the request header.
curl -X POST \
'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
-H 'Content-Type: application/vnd.pingidentity.password.reset+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
"currentPassword": "<current password>",
"newPassword": "<new password>"
}'
Recover password
You can also use the POST /{environmentId}/flows/{flowId}
operation to initiate an action to recover the account and set a new password. The request body requires the recoveryCode
and newPassword
attributes. This operation uses the application/vnd.pingidentity.password.recover+json
custom media type as the content type in the request header.
curl -X POST \
'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
-H 'Content-Type: application/vnd.pingidentity.password.recover+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
"recoveryCode": "<code>",
"newPassword": "<new password>"
}'
Send recovery code
You can also use the POST /{environmentId}/flows/{flowId}
operation to send the OTP to the user. The OTP is a randomly generated eight-character alphanumeric string sent to the user’s email address, and the code is valid for five minutes. This operation uses the application/vnd.pingidentity.password.sendRecoveryCode
custom media type as the content type in the request header.
curl -X POST \
'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
-H 'Content-Type: application/vnd.pingidentity.password.sendRecoveryCode' \
-H 'Cookie: ST=<sessionToken>' \
}'
Verify user
The POST /{environmentId}/flows/{flowId}
operation initiates an action to verify the user account to continue the authentication flow. The user must click the link in the verification email to verify the account. The request body requires the verificationCode
attribute identifying the verification code to check. This operation uses the application/vnd.pingidentity.user.verify+json
custom media type as the content type in the request header.
curl -X POST \
'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
-H 'Content-Type: application/vnd.pingidentity.user.verify+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
"verificationCode": "<new password>"
}'
Send verification email
If the user did not receive the verification email, the POST /{environmentId}/flows/{flowId}
operation initiates an action to send the user a new account verification email. This operation uses the application/vnd.pingidentity.user.sendVerificationCode+json
custom media type as the content type in the request header.
curl -X POST \
'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
-H 'Content-Type: application/vnd.pingidentity.user.sendVerificationCode+json' \
-H 'Cookie: ST=<sessionToken>' \
}'
Select an MFA device
PingOne supports email and SMS-capable device types for use in a multi-factor authentication flow. To enable multi-factor authentication, a user resource must have a device ID associated with its user ID.
The following sample shows the POST /{environmentId}/flows/{flowId}
operation to specify a device ID to use in the multi-factor authentication flow. This operation uses the application/vnd.pingidentity.device.select+json
custom media type as the content type in the request header.
curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}" \
-H 'Content-type: application/vnd.pingidentity.device.select+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
"device": {
"id": "<deviceId>"
}
}'