Public

Switch an in-progress login challenge to a different enrolled mechanism.

When a user has more than one method enrolled (see available_mechanisms on the login response) they can switch the active challenge — for example from Totp to Email when they have lost access to their authenticator. Post the current challenge token and the desired mechanism:

{ "challenge_token": "eyJ...", "mechanism": "Email" }

A fresh challenge for that mechanism is returned (and, for Email, a code is sent), in the same shape as the 202 from POST /api/v1/tokens minus two_factor_required. An unrecognized mechanism returns 400 (invalid_mechanism); a mechanism the user has not enrolled returns 400 (not_enrolled). Rate limited to 5 requests per minute (429).

post/api/v1/tokens/two-factor/switch-mechanism

Request

  • Base URL: https://go.outseta.com
  • URL: https://go.outseta.com/api/v1/tokens/two-factor/switch-mechanism
  • Auth: none declared

Query parameters

dataunknown required

Response

The challenge was reissued for the requested mechanism.

two_factor_requiredboolean nullable

Present and true on the 202 response from POST /api/v1/tokens when the user has at least one verified 2FA method. Absent on the resend / switch-mechanism responses, which only ever follow an already-issued login challenge.

two_factor_enrollment_requiredboolean nullable

Present and true instead of two_factor_required when the tenant forces 2FA but the user has not yet enrolled any method. In that case only challenge_token and expires_in are populated and the client must route the user through the mid-login enrollment endpoints (/api/v1/tokens/two-factor/enroll/...) before a token can be issued.

challenge_tokenstring nullable

Short-lived signed JWT (audience outseta:2fa-challenge) that identifies this challenge. Echo it back verbatim to complete the login.

mechanismstring nullable

The mechanism this challenge was issued against: Email or Totp (authenticator app). For Email a code has already been sent to the user; for Totp the user reads the current code from their authenticator app and nothing is sent.

masked_destinationstring nullable

A masked view of where an emailed code was sent (e.g. b***@outseta.com), suitable for display. Empty when mechanism is Totp.

expires_ininteger

Seconds until the challenge expires (600). After this the challenge_token can no longer be verified and the login must restart.

available_mechanismsstring[] nullable

Every verified mechanism enrolled for this user (excluding recovery codes), e.g. ["Totp", "Email"]. A client can offer a "use a different method" option for any value other than the current mechanism via POST /api/v1/tokens/two-factor/switch-mechanism.

recovery_codes_availableboolean nullable

true when the user has a batch of recovery codes on file, in which case POST /api/v1/tokens/two-factor/recovery can be used as a fallback if they cannot produce a primary code.

Example response

{
  "two_factor_required": false,
  "two_factor_enrollment_required": false,
  "challenge_token": "string",
  "mechanism": "string",
  "masked_destination": "string",
  "expires_in": 0,
  "available_mechanisms": [
    "string"
  ],
  "recovery_codes_available": false
}

Changes

No recorded changes to this operation across all 1 revision of this API.