POST/api/auth/mfa/verifyPublic

Complete a login MFA challenge

Second step of a login that answered mfa_required: presents a TOTP code, a passkey assertion or a recovery code for the pending challenge. Each wrong proof costs one of the challenge's attempts; when they run out (or the challenge expired) the answer is 410 and the user must log in again. On success the challenge is deleted and the same authorization code + session cookie a password-only login would have produced are issued. Rate limited per IP.

operationId post_api_auth_mfa_verifyAuthentication

Authentication & permissionsPublic

Anyone — no credentials required

Accepted credentials
None required
Notes
The challenge id issued by POST /api/auth/login is the credential.

Request body

Required — The body is parsed by the handler itself so its error format stays stable.

application/json
MfaLoginVerifyRequestThe challenge_id from the mfa_required login response, the same client_app_id the login was for, and one proof: a 6-digit TOTP code for a factor, a passkey assertion (obtained with the options from POST /api/auth/mfa/webauthn/options), or a single-use recovery code.
PropertyTypeDescription
challenge_id*string (uuid)
client_app_id*string

minLength: 2maxLength: 64pattern: ^[a-z0-9_-]*$

proof*object | object | object
JSONExample
"challenge_id""123e4567-e89b-12d3-a456-426614174000"
"client_app_id""string"
"proof"
"type""totp"
"factor_id""123e4567-e89b-12d3-a456-426614174000"
"code""string"

Responses

application/json
AuthenticatedResultThe user is authenticated: redeem authorization_code at POST /api/oidc/token (PKCE). The response also sets the auth server's HTTP-only session cookie.
PropertyTypeDescription
kind*"authenticated"
success*boolean
message*string
authorization_code*string

minLength: 43

JSONExample
"kind""authenticated"
"success"true
"message""string"
"authorization_code""string"

Example request

bashcurl
curl -X POST 'https://auth.schemavaults.com/api/auth/mfa/verify' \
  -H 'Content-Type: application/json' \
  -d '{
  "challenge_id": "123e4567-e89b-12d3-a456-426614174000",
  "client_app_id": "string",
  "proof": {
    "type": "totp",
    "factor_id": "123e4567-e89b-12d3-a456-426614174000",
    "code": "string"
  }
}'