Complete the MFA step of a pending login session

Finishes the multi-factor authentication step of the login flow. Call this after the login endpoint returns a session with mfa_required: true (and a session_token in pending-mfa status), once the identity has satisfied one of their active login MFA methods.

There are two mutually exclusive ways to complete verification, both submitted to this same endpoint:

One-time code flow — pass identity_mfa_id (the email-mobile or authenticator method being used) together with code (the OTP emailed to the identity, or the current code from their authenticator app).

Passkey flow — pass assertion_response, the JSON object returned by the browser's startAuthentication() (from @simplewebauthn/browser) after calling POST /session-otps with { "type": "passkey" } to obtain the WebAuthn challenge. The server resolves which registered passkey was used directly from the assertion, so identity_mfa_id is never required for this flow.

On success the pending session is transitioned to active, a fresh 30-day session token is issued, and the identity's basic profile is returned. This endpoint is intentionally unauthenticated (no Authorization header is checked) — the session_token supplied in the request body is what proves the caller already completed the first login factor (password or otherwise).

Failed one-time-code attempts are tracked per MFA method, and failed passkey attempts are tracked per identity; both are rate-limited to 5 failures within a rolling 15-minute window, after which further attempts are rejected until the window elapses regardless of whether the new submission is correct.

application/json

The code or passkey assertion was valid and the session is now active. A fresh session token and the identity's abbreviated profile are returned.

Bodyapplication/json

curl --location --request PATCH '/identity-sessions' \ --header 'Content-Type: application/json' \ --data '{ "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7InNlc3Npb25faWQiOiIwMUpTRVNTMTIzNDU2Nzg5MEFCQ0RFRiJ9fQ.s1gnatur3", "identity_mfa_id": "01JMFA1234567890ABCDEFGHIJ", "code": "482913" }'

{ "message": "Request successful", "status": "success", "data": { "mfa_required": false, "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7InNlc3Npb25faWQiOiIwMUpTRVNTMTIzNDU2Nzg5MEFCQ0RFRiJ9fQ.n3wt0k3n", "session_id": "01JSESS1234567890ABCDEFGHI", "identity_id": "01JIDENT234567890ABCDEFGHI", "expires_at": 1793270400000, "identity": { "name": "Jane Doe", "primary_email": "jane.doe@example.com", "status": "active" } } }

Complete the MFA step of a pending login session

Request

Responses