Request a login MFA challenge or one-time-passcode

Advances a pending multi-factor authentication (MFA) login session by dispatching the next verification challenge for one of the identity's active MFA methods. Call this after a login attempt returns a session in the pending-mfa state, so the user can obtain what they need to complete verification. Two mutually exclusive dispatch modes are supported, selected by which optional field is supplied: passing type: "passkey" generates and returns WebAuthn authentication (assertion) options scoped to the identity's active passkeys, while passing identity_mfa_id (referencing an active email-mobile MFA method) emails a 6-digit one-time passcode to the address on file. Exactly one of identity_mfa_id or type must be supplied. This endpoint is unauthenticated by design: it is called before the user holds any bearer token, and access is instead gated by possession of the short-lived session_token issued at login. Email OTP dispatch is rate-limited per MFA method to prevent notification abuse: if a code was already sent within the cooldown window, the request is rejected until the window elapses.

Responses

🟢201

application/json

The next MFA challenge was generated successfully. For the email OTP flow, a one-time passcode was emailed to the address on file (the response confirms dispatch only; it never returns the code itself). For the passkey flow, WebAuthn authentication options were generated and the anti-replay challenge was persisted on the session so it can be verified on the next step.

Bodyapplication/json

🟠400

🟠401

🟠404

🟠429

curl --location '/session-otps' \ --header 'Content-Type: application/json' \ --data '{ "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiMDFIUVpSMkJLUEZROE1YSlZUM0c3TFdOQSJ9.4fA1s0cR9m2wYQeK3jT6bV8pXqU7dS5nZ1hL0oM2rWk", "identity_mfa_id": "01HQZR2BKPFQ8MXJVT3G7LWNA" }'