Public

Begin email enrollment during a forced-2FA login.

Call this when POST /api/v1/tokens returned two_factor_enrollment_required and the user chooses email. Post the enrollment token from that response:

{ "enrollment_token": "eyJ..." }

A verification code is emailed to the user and a challenge is returned:

{
  "challenge_token": "eyJ...",
  "mechanism": "Email",
  "masked_destination": "b***@outseta.com",
  "expires_in": 600
}

Confirm the code via POST /api/v1/tokens/two-factor/enroll/email/confirm. Returns 401 if the enrollment token is invalid/expired and 403 if forced enrollment does not apply to this user. Rate limited to 5 requests per minute (429).

post/api/v1/tokens/two-factor/enroll/email/begin

Request

  • Base URL: https://go.outseta.com
  • URL: https://go.outseta.com/api/v1/tokens/two-factor/enroll/email/begin
  • Auth: none declared

Query parameters

dataunknown required

Response

A code was emailed; the enrollment-test challenge is returned.

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.