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.

Sign-on actions

The flow endpoint can initiate sign-on actions that specify the operations to authenticate without a password. This flow performs a username lookup and requires an MFA action to login.

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 status

In a sign-on workflow, the flow’s status property value returned by the last action identifies the appropriate next action in the authentication process. For example, if an application uses the LOGIN sign-on policy, when a user initiates sign-on and starts the authentication flow, the response returned by the flow shows a status value that specifies the next required step to complete this flow successfully. For the LOGIN sign-on policy, the next action prompts the user to enter a username and password, as indicated by the USERNAME_PASSWORD_REQUIRED value in the status property.

"status" : "USERNAME_PASSWORD_REQUIRED"

The response data also includes a HAL link to the required action, which in this case is the usernamePassword.check:

{
  "_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}"
    }
  },

After the user submits a username and password, the flow calls the usernamePassword.check action to verify the username and password.

Flow status values

An authentication flow can return one of the following status values in response to a sign-on action:

• USERNAME_PASSWORD_REQUIRED

  This value specifies that a username and password is required. This status calls a usernamePassword.check action.

• PASSWORD_REQUIRED

  This value specifies that a password is required. This status calls a usernamePassword.check action.

• SIGN_ON_REQUIRED

  This value specifies that the user is signing on without providing a password. This status is initiated through a user.register action to register a new user. It is also initiated through a user.lookup action in a passwordless authentication flow. It can also be initiated through a password.forgot flow.

• RECOVER_CODE_REQUIRED

  This value specifies that the user initiated a password.forgot action and a recovery code must be sent. This status calls the password.recover action.

• VERIFICATION_REQUIRED

  This value specifies that the user’s account must be verified. This status calls the user.verify action.

• OTP_REQUIRED

  This value specifies that the user complete a multi-factor authentication action. This status calls the otp.check action.

• DEVICE_SELECTION_REQUIRED

  This value specifies that the user complete a device selection multi-factor authentication action. This status calls the device.select action.

• PASSWORD_EXPIRED

  This value specifies that a user’s password has expired and must be updated. This status calls the password.reset action.

• MUST_CHANGE_PASSWORD

  This value specifies that a temporary password must be changed or updated. This status calls the password.reset action.

• COMPLETED

  This value specifies that the current action has completed. This status calls the next action in the sign-on policy, or if no other actions are required, the flow is completed.

• FAILED

  This value specifies that the current action has failed. This status calls the next available sign-on policy, or if no other sign-on policy is assigned to the application, the flow fails.

Flow API operations

The flow endpoints support the following operations:

• POST /{environmentId}/flows/{flowID} Reset a flow

• GET /{environmentId}/flows/{flowID} Read a flow

• POST /{environmentId}/flows/{flowID} Login with username and password

• POST /{environmentId}/flows/{flowID} Sign on with a username

• POST /{environmentId}/flows/{flowId} Validate the one-time password

• POST /{environmentId}/flows/{flowId} Forgot password

• POST /{environmentId}/flows/{flowId} Register a user

• POST /{environmentId}/flows/{flowId} Check password

• POST /{environmentId}/flows/{flowId} Reset a user password

• POST /{environmentId}/flows/{flowId} Recover a user password

• POST /{environmentId}/flows/{flowId} Send recovery code

• POST /{environmentId}/flows/{flowId} Verify user

• POST /{environmentId}/flows/{flowId} Send verification email

• POST /{environmentId}/flows/{flowId} Select an MFA device

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

Login actions data model

Sign-on actions data model

Multi-factor authentication actions data model

Response codes

Endpoint examples

Reset a flow

The following sample shows the POST /{environmentId}/flows/{flowID} operation that updates (or resets) a flow 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

The GET /{environmentId}/flows/{flowID} operation retrieves 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: For a status value of USERNAME_PASSWORD_REQUIRED, the response includes the HAL link to the usernamePassword.check action to initiate the next required operation.

Login with username and password

The POST /{environmentId}/flows/{flowId} operation initiates 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"
      }
    }
  }
}

Sign on with a username

The POST /{environmentId}/flows/{flowId} operation initiates an action to allow users to sign on with a username. The request body requires only the username attribute. The username value is verified in this action. This operation uses the application/vnd.pingidentity.user.lookup+json custom media type as the content type in the request header.

Note: You must create a new sign-on policy with the appropriate sign-on policy actions to use this sign-on flow.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.user.lookup+json' \
  -H 'Cookie: ST=<sessionToken>' \
  -d '{
    "username": "<username>"
}'

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 response includes the validateOTP HAL link to initiate this required step.

{
  "_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

The POST /{environmentId}/flows/{flowId} operation initiates 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

The POST /{environmentId}/flows/{flowId} operation initiates 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

The POST /{environmentId}/flows/{flowId} operation initiates 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

The POST /{environmentId}/flows/{flowId} operation initiates 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

The POST /{environmentId}/flows/{flowId} operation initiates 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

The POST /{environmentId}/flows/{flowId} operation sends 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>"
  }
}'