Two-Factor Authentication

Begins the enrollment flow for the authenticated user. Authenticated with a JWT Bearer token (not a secret API key).

For method=totp, the response includes the base32 secret and a pre-rendered qr_code data URL — show the QR to the user, ask them to scan it in their authenticator app, then call /v1/auth/2fa/confirm with the first 6-digit code.

For method=email, a 6-digit code is emailed to the user (10-minute TTL) and the response carries only a masked sent_to address. The same /v1/auth/2fa/confirm endpoint finishes the flow.

two_factor_enabled stays false until confirm succeeds — calling initiate alone does not lock the user out.

Verifies the first 6-digit code against the pending secret saved by /v1/auth/2fa/initiate. Authenticated with a JWT Bearer token.

On success: flips two_factor_enabled to true, stamps two_factor_enrolled_at, and returns ten one-time backup codes. The codes are returned only here — the database holds bcrypt hashes. Lose them and the user has to call /v1/auth/2fa/backup-codes/regenerate.

Used during login. When /v1/auth/login returns requires_two_factor: true, it also returns a short-lived partial token. Send that partial token as the Authorization: Bearer … header to this endpoint together with one of:

- a 6-digit TOTP code (TOTP-method users) - a 6-digit email OTP (email-method users — a fresh OTP was emailed at login) - a single-use backup_code (works regardless of method)

On success the response sets the full session via httpOnly cookies and the partial token is replaced by full access/refresh tokens. Exactly one of code and backup_code must be supplied.

Re-issues a fresh 6-digit code to the user's email and starts a new 10-minute window. Authenticated with the partial 2FA token (same Bearer token used for /v1/auth/2fa/verify).

Rate-limited to one request per 60 seconds per user. Only meaningful for users enrolled with the email method — TOTP users get a 400 (their authenticator app already generates codes on demand).

Requires re-authentication: the current password plus either a current code (TOTP or email OTP) or an unused backup_code. Authenticated with a JWT Bearer token.

The handler clears the secret, method, enabled flag, enrolled timestamp, and every backup code in a single transaction — the user can never land in a half-disabled state. Exactly one of code and backup_code must be supplied.

Returns the 2FA state for the authenticated user — used by the dashboard's security page to render "Enabled / Disabled" and the unused-backup-code count. Authenticated with a JWT Bearer token.

Replaces the existing backup-code set with ten freshly-minted codes. The previous set is invalidated atomically in the same transaction. Authenticated with a JWT Bearer token.

Requires either a current code (TOTP or email OTP) or an unused backup_code — a stolen access token alone cannot rotate backup codes for persistent access. Exactly one must be supplied.

Toggles mandatory 2FA at the merchant level. Owner only — non-owner callers get 403. Authenticated with a JWT Bearer token and merchant_profile:write permission.

When enabled=true:

- The owner must already have 2FA enabled (else 400) — otherwise they'd lock themselves out the moment enforcement kicks in. - A 7-day grace period begins. During the grace window non-enrolled team members can still sign in (the dashboard renders a banner). After the deadline, sign-in is blocked until the user enrolls. - Every non-enrolled active team member is emailed a grace-period notification with an enrollment link.

When enabled=false: the policy is removed and grace_period_ends_at is cleared. Distinct from per-user 2FA — disabling the policy does not turn off 2FA for anyone who has it on.