Begin TOTP enrollment

POST

/account/security/2fa

• Local development behind nginx (port 8088 by default)

Generates a fresh shared secret + returns the base32 form plus the otpauth:// URI for QR rendering. The row is persisted UNCONFIRMED — login flow is NOT yet gated. Caller must POST /account/security/2fa/confirm with a valid code to flip the enrollment to active + receive backup codes.

Re-calling overwrites any prior unconfirmed enrollment; a CONFIRMED enrollment is left in place (caller must DELETE first to re-enroll — that surfaces a “you’re about to disable 2FA” confirmation in the UI).

Authorizations

• cookieAuth

Responses

200

Enrollment in progress.

object

secret_base32

required

The shared secret as RFC 4648 base32 (no padding). Authenticator apps that can’t scan QR fall back to manual paste.

string

otpauth_url

required

Otpauth://totp/:?secret=…&issuer=… URI. Frontend renders as a QR code via client-side JS — no QR-generation Go dep needed.

string

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

409

2FA already confirmed; disable first to re-enroll.

object

error

required

Human-readable error summary

string

Example

the request could not be completed