Flows


Common sign-on actions

The flow endpoint is used to interact with the 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).

Identifier first actions

The flow can initiate a discovery action used to identify the user by username and determine the applicable authentication methods for this user.

Progressive profiling

Progressive profiling actions prompt users to provide additional data at sign on. This action type does not authenticate users. It is used only to obtain additional profile data.

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 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:

Status value Description
USERNAME_PASSWORD_REQUIRED This value specifies that a username and password is required. This status can initiate a usernamePassword.check action, a user.register action, a password.forgot action, or an authenticate action to sign on using an external identity provider.
PASSWORD_REQUIRED This value specifies that a password is required. This status initiates a usernamePassword.check action.
SIGN_ON_REQUIRED This value specifies that a sign-on action is required. This status transitions to a user.lookup action in a passwordless authentication flow.
RECOVERY_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_CODE_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 must complete a multi-factor authentication action. This status calls the otp.check action.
DEVICE_SELECTION_REQUIRED This value specifies that the user must 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.
ACCOUNT_LINKING_REQUIRED This value specifies that the external identity returned by the identity provider requires an account linking action to link the external account to an existing user. This status can initiate a usernamePassword.check to link to an existing user, a user.register action to create a link to a new user, or a password.forgot to link to an existing user who has forgotten the password.
EXTERNAL_AUTHENTICATION_REQUIRED This value specifies that account authentication is required through an external identity provider’s authentication flow. The authenticate HAL embedded resource link provides the location to redirect the browser to sign on with the specified identity provider.
PROFILE_DATA_REQUIRED This value specifies that user must submit the requested profile data in order to continue the authentication flow.
COMPLETED This value specifies that the entire flow is completed and initiates a browser redirect to the resumeUrl property to continue.
FAILED This value specifies that the entire flow has failed.
PENDING_PUSH_CONFIRMATION This value specifies that a push was sent to a mobile device to confirm the authentication. The client will have to poll this status using GET /{environmentId}/flows/{flowID} to check whether the mobile device answered the push.
PENDING_PUSH_TIMEOUT This value specifies that a push was sent to a mobile device, but the mobile device didn’t answer the push during the allowed timeframe.

Flow API operations

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

The flow endpoint operation, POST /{environmentId}/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
application/json Get 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.session.reset+json Update or reset a flow

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 common response data model

These common properties are returned with the flow response.

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 the flow is COMPLETED or FAILED.
status A string that specifies the status of the flow. For more information about flow status values and their resulting actions, see Flow status values.
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.

These common links are returned with the flow response.

Links Description
self The HAL link to the current flow resource.
session.reset The HAL 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
user The HAL link to the resource containing profile attributes of the actively signing-on or previously signed-on user.

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 status data model and embedded resources

The following sections show the parameters required by the flow status. In addition, the following links and embedded resources are returned in the flow response for the given flow status.

USERNAME_PASSWORD_REQUIRED

Parameters Description
username A string that specifies the username or ID of the user to authenticate.
password A string that specifies the password or ID of the user to authenticate.
Links Description
usernamePassword.check The HAL link to initiate a sign-on action that allows users to login with a username and password. The request body requires the username and password attributes.
user.register The HAL link to initiate a sign-on action to register a user. The request body requires the username, email, and password attributes needed to define a new user.
password.forgot The HAL link to initiate an action to recover a user’s forgotten password. The request body requires the username attribute to identify the user.
Embedded resources Description
socialProviders.authenticate The HAL link to the external authentication resource to initiate authentication using an external identity provider’s authentication flow. The response also returns the following information about the identity provider: id, name, and type. For more information, see Base identity providers data model.
passwordPolicy The embedded password policy resource expanded to show password policy attributes. For more information about password policy attributes, see Password policies data model.

SIGN_ON_REQUIRED

Parameters Description
username A string that specifies the username or ID of the user to sign on.
Links Description
user.lookup The HAL link for existing users to sign on using their username.

PASSWORD_REQUIRED

Parameters Description
username A string that specifies the username or ID of the user to authenticate. If provided, must match the user currently associated with the session.
password A string that specifies the password or ID of the user to authenticate.
Links Description
usernamePassword.check The HAL link to initiate a sign-on action that allows users to log in with a username and password. The request body requires the username and password attributes.
password.forgot The HAL link to initiate an action to recover a user’s forgotten password. The request body requires the username attribute to identify the user.
Embedded resources Description
socialProviders.authenticate The HAL link to the external authentication resource to initiate authentication using an external identity provider’s authentication flow. The response also returns the following information about the identity provider: id, name, and type. For more information, see Base identity providers data model.

PASSWORD_EXPIRED

Parameters Description
currentPassword A string that specifies the current password, which must be verified before the new password is set.
newPassword A string that specifies the new password to set.
Links Description
password.reset The HAL link to initiate a sign-on action that allows users to reset their password. The request body requires the currentPassword and newPassword attributes.
Embedded resources Description
passwordPolicy The embedded password policy resource expanded to show password policy attributes. For more information about password policy attributes, see Password policies data model.

MUST_CHANGE_PASSWORD

Parameters Description
currentPassword A string that specifies the current password, which must be verified before the new password is set.
newPassword A string that specifies the new password to set.
Links Description
password.reset The HAL link to initiate a sign-on action that allows users to reset their password. The request body requires the currentPassword and newPassword attributes.
Embedded resources Description
passwordPolicy The embedded password policy resource expanded to show password policy attributes. For more information about password policy attributes, see Password policies data model.

RECOVERY_CODE_REQUIRED

Parameters Description
recoveryCode A string that specifies the recovery code sent to the user to recover the user’s password.
newPassword A string that specifies the new password to set.
Links Description
password.recover The HAL link to initiate an action to recover the account and set a new password. The request body requires the recoveryCode and newPassword attributes.
password.sendRecoveryCode The HAL link to send the one-time password (OTP) to the user.
Embedded resources Description
passwordPolicy The embedded password policy resource expanded to show password policy attributes. For more information about password policy attributes, see Password policies data model.

VERIFICATION_CODE_REQUIRED

Parameters Description
verificationCode A string that specifies the verification code to check.
Links Description
user.verify The HAL link to initiate an action to verify the user account to continue the authentication flow.
user.sendVerificationCode The HAL link to initiate an action to send the user a new account verification email.

DEVICE_SELECTION_REQUIRED

Parameters Description
device.id A string that specifies the ID of the selected device.
Links Description
device.select The HAL link to initiate an action to specify a device ID to use in the multi-factor authentication flow.
Embedded resources Description
devices The embedded devices resource expanded to show a list of authenticating devices for this operation. For more information about device attributes, see Devices model properties.

OTP_REQUIRED

Parameters Description
selectedDevice.id A string that specifies the ID of the currently selected device.
Links Description
device.select The HAL link to initiate an action to specify a device ID to use in the multi-factor authentication flow.
otp.check The HAL link to initiate an action to validate the OTP used in the multi-factor authentication flow.
Embedded resources Description
devices The embedded devices resource expanded to show a list of authenticating devices for this operation. For more information about device attributes, see Devices model properties.

PUSH_CONFIRMATION_REQUIRED

Parameters Description
selectedDevice.id A string that specifies the ID of the currently selected device.
Links Description
device.select The HAL link to initiate an action to specify a device ID to use in the multi-factor authentication flow.
Embedded resources Description
devices The embedded devices resource expanded to show a list of authenticating devices for this operation. For more information about device attributes, see Devices model properties.

ACCOUNT_LINKING_REQUIRED

Links Description
user.register The HAL link to initiate a sign-on action that initiates an action to register a user. The request body requires the username, email, and password attributes to define a new user.
Embedded resources Description
matchedUsers An array of 0 or more users that match the external identity. The request returns the username, email, and lastSignedOnAt attributes needed to identify the user.
identityProviders The external identity provider used to authenticate. The request returns the name and type attributes needed to identify the identity provider used for authentication.

EXTERNAL_AUTHENTICATION_REQUIRED

Parameters Description
name A string that specifies the name of the identity provider.
type A string that specifies the identity provider type.
Embedded resources Description
identityProvider.authenticate A string that specifies the URL for the external identity provider’s sign-on screen to initiate authentication with the external identity provider.
identityProvider.loginButtonIcon A string that specifies the URL for the external identity provider’s login button icon file.

PROFILE_DATA_REQUIRED

Parameters Description
displayName A string that specifies the display name as defined in the user schema.
name A string that specifies the attribute name/path as defined in the user schema (for example, email, address.postalCode).
required A boolean that specifies whether the user is required to provide a value for the attribute.
Links Description
user.update The HAL link to update the specified user’s profile with the user attribute values provided in the request.
Embedded resources Description
attributes An array of user attributes provided to update the user’s profile.
attributes.name A string that specifies the attribute path, as defined in the user schema (for example, email, name.family, address.postalCode).
attributes.displayName A string that specifies the attribute’s display name, as defined in the user schema. This property is optional.
attributes.required A boolean that specifies whether the user is required to provide a value for the attribute.
promptText A string that specifies text to display to the user when prompting for attribute values.

Endpoint examples

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/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    },
    "usernamePassword.check" : {
      "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    },
    "user.register" : {
      "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    },
    "password.forgot" : {
      "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    }
  },
  "id" : "ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6",
  "resumeUrl" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/as/resume?flowId=ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6",
  "status" : "USERNAME_PASSWORD_REQUIRED",
  "createdAt" : "2019-06-04T21:52:34.866Z",
  "expiresAt" : "2019-06-04T22:07:35.724Z",
  "_embedded" : {
    "passwordPolicy" : {
      "excludesProfileData" : true,
      "notSimilarToCurrent" : true,
      "excludesCommonlyUsed" : true,
      "maxRepeatedCharacters" : 2,
      "minUniqueCharacters" : 5,
      "length" : {
        "min" : 8,
        "max" : 255
      },
      "minCharacters" : {
        "abcdefghijklmnopqrstuvwxyz" : 1,
        "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : 1,
        "1234567890" : 1,
        "~!@#$%^&*()-_=+[]{}|;:,.<>/?" : 1
      },
      "history" : {
        "count" : 6,
        "retentionDays" : 365
      }
    },
    "socialProviders" : [ {
      "id" : "179a9005-6f26-4294-9388-fcb0e9323353",
      "name" : "Facebook",
      "type" : "FACEBOOK",
      "_links" : {
        "authenticate" : {
          "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/rp/authenticate?providerId=179a9005-6f26-4294-9388-fcb0e9323353&flowId=ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
        }
      }
    } ]
  }
}

For a status value of USERNAME_PASSWORD_REQUIRED, the response includes the following HAL links to initiate the possible next operation in the flow, depending on the sign-on policy configuration:

  • usernamePassword.check

An action to authenticate with a username and password.

  • user.register

    An action to register a new user.

  • password.forgot

    An action to recover a user’s forgotten password.

  • authenticate

    An action to sign on using an external authentication provider.

Log in with external authentication

PingOne supports login integration between external identity providers (such as Facebook) and PingOne authentication flows. For example, if Facebook is specified as an external identity provider, users have the ability to sign on to their PingOne account using their Facebook credentials and Facebook’s account sign-on flow.

When external authentication is enabled, the flow initialization response includes the socialProviders embedded resource, which provides the following information about each external identity provider that can be used by the user to sign on:

"socialProviders" : [ {
  "id" : "179a9005-6f26-4294-9388-fcb0e9323353",
  "name" : "Facebook",
  "type" : "FACEBOOK",
  "_links" : {
    "authenticate" : {
      "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/rp/authenticate?providerId=179a9005-6f26-4294-9388-fcb0e9323353&flowId=ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    }
  }
} ]

The authenticate HAL link can be used to redirect the browser to initiate authentication with the associated external identity provider.

Log in with username and password

When the flow status is USERNAME_PASSWORD_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides an action to allow users to login with a 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.

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 status property value in the response determines the next action in the flow. The following sample response shows a status value of OTP_REQUIRED, which indicates that the one-time password validation step used in a multi-factor authentication flow is a required action. The otp.check 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}"
    },
    "otp.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": "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"
      }
    }
  }
}

Log in with a username

When the flow status is SIGN_ON_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides 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.

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>"
}'

Forgot password

When the flow status is RECOVERY_CODE_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides 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": "<value>"
}'

Register a user

When the flow status is USERNAME_PASSWORD_REQUIRED or ACCOUNT_LINKING_REQUIRED, the POST /{environmentId}/flows/{flowId} operation initiates an action to register a user. For USERNAME_PASSWORD_REQUIRED, the request body requires the username, email, and password attributes 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

When the flow status is USERNAME_PASSWORD_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides an action to prompt the user who has previously signed on with a username and password to verify the password again. The request body requires the password attribute. However, the sign-on flow could prompt for the username value if the username does not match the user currently associated with the session. 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.usernamePassword.check+json' \
  -H 'Cookie: ST=<sessionToken>' \
  -d '{
    "username": "user1",
    "password": "<password>"
}'

Reset password

When the flow status is PASSWORD_EXPIRED or MUST_CHANGE_PASSWORD, the POST /{environmentId}/flows/{flowId} operation provides 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

When the flow status is RECOVERY_CODE_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides 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

When the flow status is VERIFICATION_CODE_REQUIRED, the POST /{environmentId}/flows/{flowId} operation sends a new verification email if the user lost or did not receive their previous email. The OTP in the verification email is a randomly generated eight-character alphanumeric string, 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

When the flow status is VERIFICATION_CODE_REQUIRED, 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

When the flow status is VERIFICATION_CODE_REQUIRED, if the user did not receive the verification email, the POST /{environmentId}/flows/{flowId} operation provides 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.

When the flow status is DEVICE_SELECTION_REQUIRED or PUSH_CONFIRMATION_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides an action 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>"
  }
}'

Validate the OTP

When the flow status is OTP_REQUIRED, the multi-factor authentication flow uses a one-time password (OTP) 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>"
}'

Submit profile data

In an authentication flow, users can be prompted to add data to their profile. When the flow status is PROFILE_DATA_REQUIRED, the POST /{environmentId}/flows/{flowId} operation uses the application/vnd.pingidentity.user.update+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.update+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
  "email": "lindajones@ping.com",
  "address": {
    "postalCode": "78613"
  }
}
'

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