/{app_slug}/v1/auth/mfa/enrollBegin MFA enrolment against an enrolment token
For apps running `auth_config.mfa: "required"`. When a user proves their password but holds no enabled factor, `/auth/signin` returns `{ mfa_enrollment_required: true, mfa_token, expires_at }` and mints NO session; this endpoint starts the enrolment that `mfa_token` authorises. Same body and same response as `POST /{app_slug}/v1/me/mfa/factors`, but authenticated by the token rather than by a session — there is no session yet. TOTP returns the otpauth URI, QR data URL and shared secret; email sends a 6-digit code to the bound verified contact. The factor stays disabled until `/auth/mfa/enroll/verify` succeeds. The token is single-purpose: `/auth/mfa/verify`, `/auth/mfa/send-code` and `/auth/mfa/recover` all refuse it with 401, it is not an access token so `/me/*` refuses it, and `/auth/refresh` does not accept it.
Path parameters
app_slug*stringSlug of the app.
Request body
mfa_token*stringThe `mfa_token` from an `mfa_enrollment_required: true` signin response. UUID.
Example: "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"
type*enum (2)Factor type to enrol — `totp` (authenticator app) or `email` (single-use code to a verified email contact).
Example: "totp"
labelstringOptional human-readable label for the factor (e.g. "iPhone 15").
contact_idstring · uuidEmail factors only: id of the verified email contact codes should be delivered to. Defaults to the primary verified email.
Response · 201 Pending factor created; enrolment payload returned.
factor*objectid*stringUnique identifier of the factor.
type*stringFactor type — `totp` (authenticator app), `email` (single-use code delivered to a verified email contact), or `webauthn` (a passkey). Further factor types will extend this list without a breaking change to the response shape.
Example: "totp"
label*stringLabel the user gave the factor, or `null`.
enabled*booleanWhether the factor is enabled.
created_at*string · date-timeWhen the factor was created (ISO 8601).
enabled_at*string · date-timeWhen the factor was enabled (ISO 8601), or `null`.
enrollment*objectType-specific enrollment payload. Shape depends on `factor.type` — TotpEnrollmentData for `totp`, EmailEnrollmentData for `email` (a code is emailed to the bound contact; submit it via `/factors/:id/verify` as `code`), WebauthnEnrollmentData for `webauthn` (pass `publicKey` to `navigator.credentials.create()` and submit the result as `credential`).
Example
Request
POST https://api.auth.productcraft.co/{app_slug}/v1/auth/mfa/enroll
Content-Type: application/json
{
"mfa_token": "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f",
"type": "totp",
"label": "string",
"contact_id": "00000000-0000-0000-0000-000000000000"
}Response
{
"factor": {
"id": "string",
"type": "totp",
"label": "string",
"enabled": false,
"created_at": "2026-01-01T00:00:00.000Z",
"enabled_at": "2026-01-01T00:00:00.000Z"
},
"enrollment": {}
}