Enroll a new MFA method for the authenticated identity

Begin enrollment of a multi-factor authentication method (email-mobile, authenticator, secure-pin, or passkey) for the authenticated identity. The identity is always taken from the authenticated session's JWT — it can never be supplied in the request body. Uniqueness is enforced per identity_id + type + a type-specific medium reference: for email-mobile, authenticator, and secure-pin the medium reference is the type itself, so an identity may only ever have one record of each of those types (enrolling one twice returns 409); for passkey the medium reference is device_id, so an identity may register multiple passkeys, one per distinct device, and only re-registering the same device_id returns 409. Behavior, starting status, and contexts (where the method is enforced) differ by type: email-mobile, authenticator, and passkey start in pending status, are scoped to the login context, and must be verified/activated through the corresponding verification flow before they are enforced on login. secure-pin starts immediately in active status (no separate activation step) and is scoped to the payout context, used to authorize payouts rather than logins. For email-mobile, email is required and a one-time verification code is immediately emailed to that address (expires in 5 minutes); the response's provisioning field is null. For authenticator, the service generates a new TOTP secret, builds an otpauth:// provisioning URI, and renders it as a QR code — these are returned once in the provisioning field of this response only and are never retrievable again, so the client must capture and display them immediately (e.g. for the user to scan with an authenticator app or manually enter the secret). For passkey, device_id is required (device_name is an optional display label); the service returns a WebAuthn PublicKeyCredentialCreationOptions object once in the provisioning field, which the client must pass directly into navigator.credentials.create() to complete registration with the browser/authenticator — the accompanying challenge expires after 5 minutes. For secure-pin, pin (a 6-digit code) and exactly 2 distinct security_questions (with answers) are required; the PIN is rejected as weak if it is all one digit or a sequential run (e.g. 111111, 123456, 654321), and a fresh set of 10 one-time backup codes is generated and returned once in the backup_codes field — these plaintext codes are never retrievable again, so the client must capture and display them immediately.

Responses

🟢201

application/json

The MFA method was created. email-mobile, authenticator, and passkey methods are created in pending status; secure-pin methods are created directly in active status. For authenticator methods, the one-time provisioning secret and QR code are included; for passkey methods, a one-time WebAuthn provisioning registration payload is included for the client to complete with navigator.credentials.create(); for secure-pin methods, one-time plaintext backup_codes are included. All of these must be captured now — none is ever retrievable again.

Bodyapplication/json

🟠400

🟠401

🟠409

{ "message": "Identity MFA created successfully", "status": "success", "data": { "id": "01HXYZ1234567890ABCDEFGHIJ", "identity_id": "01HABC9876543210ZYXWVUTSRQ", "type": "authenticator", "status": "pending", "contexts": [ "login" ], "system_meta": { "email": null, "mobile": null, "security_questions": null, "has_backup_codes": false, "passkey": null }, "provisioning": { "secret": "JBSWY3DPEHPK3PXP", "otpauth_url": "otpauth://totp/FLW%20BNW:jane.doe@example.com?secret=JBSWY3DPEHPK3PXP&issuer=FLW%20BNW", "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }, "backup_codes": null, "created": 1722869520000, "updated": 1722869520000 } }

Enroll a new MFA method for the authenticated identity

Request

Responses