/{app_slug}/v1/me/mfa/factorsAuthBegin enrollment of a new MFA factor
Creates a pending factor and returns the type-specific enrollment payload. TOTP: the otpauth URI, QR data URL, and shared secret; confirm with two consecutive codes. Email: a 6-digit code is sent to the bound verified email contact (primary by default, `contact_id` to override); confirm with that single code. The factor stays disabled until `/factors/:id/verify` succeeds.
Path parameters
app_slug*stringSlug of the app.
Headers
Idempotency-KeystringRetry safety for factor enrolment. The first request returns the enrolment secret; a repeat with the same key and body returns 409 `idempotency_secret_not_replayable` with `details.factor_id` (the secret is never replayed: delete that factor and start again). Same key with a different body: 409 `IDEMPOTENCY_KEY_REUSE`. 24 h window.
Request body
type*enum (3)Factor type to enrol: `totp`, `email` or `webauthn`.
Example: "totp"
labelstringOptional human-readable label shown in the authenticator app and on the factor list (e.g. "iPhone 15").
contact_idstring · uuidEmail factors only: id of the verified email contact the codes should be delivered to. Defaults to the primary verified email. 412 when the contact (or the primary email) is unverified.
Response · 201
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/me/mfa/factors
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"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": {}
}