Start enrolling a new TOTP device

POST 
/api/v1/mfa/devices

Returns a TOTP secret and QR code URI; the device stays unverified until confirmed via /verify. Requires re-authentication (password for local/LDAP, TOTP code for OIDC step-up) unless this is the very first device on a restricted MFA/reset token. Capped at a configured max devices per user.

Request

Responses

201

Device created (unverified); secret and QR code returned

400

Max devices reached (MAX_MFA_DEVICES_REACHED), or the required step-up credential is missing (BAD_REQUEST)

401

Not authenticated, or the step-up credential was invalid (INVALID_PASSWORD, INVALID_MFA_CODE)

403

Restricted token not allowed for non-initial device setup (MFA_SETUP_RESTRICTED)

409

A verified device with this name already exists (MFA_DEVICE_NAME_EXISTS)

429

Too many failed TOTP step-up attempts (MFA_RATE_LIMITED)

500

TOTP secret generation/encryption failed (MFA_SETUP_FAILED)

503

Step-up re-authentication provider unavailable (AUTH_PROVIDER_UNAVAILABLE)