/{app_slug}/v1/auth/mfa/enroll/verifyConfirm the enrolled factor and receive the withheld session
Completes the flow started by `/auth/mfa/enroll`. TOTP: submit two `codes` from consecutive 30-second windows. Email: submit the emailed 6-digit `code`. On success the factor is enabled, a fresh set of recovery codes is minted and returned ONCE (invalidating any prior set), and the session sign-in withheld is finally minted with `amr: ["pwd","mfa"]` and `mfa_at` set to now. A wrong code counts against the token exactly as it does on the sign-in challenge; 5 failures lock it and the user must sign in again.
Path parameters
app_slug*stringSlug of the app.
Request body
mfa_token*stringThe same `mfa_token` used to start the enrolment. UUID.
Example: "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"
factor_id*string · uuidId of the pending factor returned by `/auth/mfa/enroll`.
codesarrayTOTP factors: two codes from consecutive 30-second windows.
Example: ["123456","654321"]
codestringEmail factors: the single 6-digit code emailed when enrolment started.
Example: "123456"
Response · 200 Factor enabled, recovery codes issued, session minted.
result*objectAlways `session` here: a session was minted. Discriminates the sign-in results (`session`, `mfa_required`, `mfa_enrollment_required`).
access_token*stringShort-lived JWT signed with the app-scoped JWKS key. Carries sub, role, permissions[], type=end_user.
refresh_token*stringLong-lived opaque-ish JWT used to mint a new access token via /auth/refresh. Rotated on use.
token_type*stringAlways `Bearer`.
Example: "Bearer"
expires_in*numberAccess-token lifetime in seconds.
Example: 3600
password_warningsarrayNon-fatal notes about the password that was just set. Present only on `signup` and `accept-invite`, and only when the app runs `password_breach_check: "warn"` and the password was found in a public breach corpus — the value is then `["breached"]` and the session is minted anyway, so the client can prompt the user to change it. The key is ABSENT (not an empty array) when there is nothing to report; do not branch on its length without checking that it exists. Apps on the default `block` never see it — a breached password is refused with 400 `PASSWORD_BREACHED`.
Example: ["breached"]
mfa_enrollment_due_atstring · date-timePresent only when the app runs `mfa: "required"`, the user holds no enabled factor, and the account is still inside `mfa_grace_days` of its creation. The session IS minted; this is the deadline after which sign-in will start returning `mfa_enrollment_required` instead, so a client can prompt rather than block. Absent in every other case.
factor*objectThe factor that was just enabled.
Example: {"id":"8a7f…","type":"totp","label":"iPhone 15","enabled":true}
recovery_codes*arraySingle-use recovery codes for this account. Returned ONCE — any previously-issued set is invalidated. Store them now.
Example: ["a1b2-c3d4-e5f6-7890","1234-5678-9abc-def0"]
Example
Request
POST https://api.auth.productcraft.co/{app_slug}/v1/auth/mfa/enroll/verify
Content-Type: application/json
{
"mfa_token": "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f",
"factor_id": "00000000-0000-0000-0000-000000000000",
"codes": [
"123456",
"654321"
],
"code": "123456"
}Response
{
"result": {},
"access_token": "string",
"refresh_token": "string",
"token_type": "Bearer",
"expires_in": 3600,
"password_warnings": [
"breached"
],
"mfa_enrollment_due_at": "2026-01-01T00:00:00.000Z",
"factor": {
"id": "8a7f…",
"type": "totp",
"label": "iPhone 15",
"enabled": true
},
"recovery_codes": [
"a1b2-c3d4-e5f6-7890",
"1234-5678-9abc-def0"
]
}