Stepup required

The following actions require users to go through the stepup flow:

Operation Notes

Update MFA email

In order to update an email that is used as a second factor for MFA, users must go through a stepup flow.

Delete MFA email

In order to delete an email that is used as a second factor for MFA, users must go through a stepup flow.

Update MFA phone number

In order to update a phone number that is used as a second factor for MFA, users must go through a stepup flow.

Delete MFA phone number

In order to delete a phone number that is used as a second factor for MFA, users must go through a stepup flow.

Add email as second factor for MFA or Add phone number as second factor for MFA

If there is already an existing MFA credential, users must go through the stepup flow to add a new MFA credential.

Login with password

If a user has an existing registered MFA credential and the MFA required setting is set to Always, a stepup is required to login.

This is not applicable to users without MFA credentials or if the MFA required setting is set to Never.

Using the stepup endpoint

When you use the stepup endpoint to initiate the stepup flow, you can start the flow in one of three ways.

See the table below for accompanying details to the flowchart.

stepUpFlowEndpointScenarios

Stepup options
Approach Description

SSO session cookie

Recommended

Using a current, active SSO cookie initiates the stepup flow.

With the SSO session cookie, the cookie is deposited by the SDK into the browser. This way, it can’t be leaked or used on another domain.

It only works in conjunction with the Core SDK.

Example

POST https://YOUR_DOMAIN/identity/v1/mfa/stepup

SESSION_COOKIE

{
  "client_id": "nvR2y0ks...EgCW2dqy",
  "response_type": "code",
  "scope": "openid phone address profile mfa",
  "redirect_uri": "https://redirect_uri.com/"
}

tkn in request body

Recommended

Passing a valid tkn in the request body initiates the stepup flow. The tkn comes from the user login. Essentially, users must log in to have a fresh authorization.

Example

POST https://YOUR_DOMAIN/identity/v1/mfa/stepup

{
  "client_id": "nvR2y0ks...EgCW2dqy",
  "response_type": "code",
  "scope": "openid phone address profile mfa",
  "redirect_uri": "https://redirect_uri.com/",
  "tkn": "xhNGxw...70zx32" (1)
}
1 The one-time use authentication token.

access_token in AUTH header

Passing the access_token in your Authorization header initiates the stepup flow.

We recommend that you only use this approach if you are unable to use the SSO session cookie or tkn approach.
We can’t ensure how fresh the token will be in this case or if it has been leaked. Therefore, we strongly recommend against using this approach. It should be implemented as a last resort only.

Example

POST https://YOUR_DOMAIN/identity/v1/mfa/stepup

AUTHORIZATION: Bearer {access_token}

{
  "client_id": "nvR2y0ks...EgCW2dqy",
  "response_type": "code",
  "scope": "openid phone address profile mfa",
  "redirect_uri": "https://redirect_uri.com/"
}