Settings → Security Settings

Password-adjacent security: MFA/TOTP, secret question, smart card, and passkeys.

Endpoint summary

Method	Path	Notes
GET	/user/v1/settings/security	View current security settings
PUT	/user/v1/settings/security	Update them
GET	/user/v1/settings/generateQR	QR code for the current MFA secret
GET	/user/v1/settings/is-mfa, /is-smartcard	Quick booleans for feature-gating the UI
POST	/auth/v1/otp/setup/begin	Begin TOTP enrollment
POST	/auth/v1/otp/setup/confirm	Confirm enrollment with a code
GET	/auth/v1/otp/status	Whether TOTP is currently enabled
DELETE	/auth/v1/otp	Disable TOTP
POST	/webauthn/register/options, /webauthn/register/verify	Register a passkey
PUT	/user/v1/settings/disable/passkey	Disable passkey login

---

Viewing and updating security settings

GET /user/v1/settings/security

{
  "secretQuestion": "What is your favorite color?",
  "secretEnabled": true,
  "mfaEnabled": true,
  "scaEnabled": false,
  "passKeyEnabled": true,
  "passKeyEnrollPending": false,
  "mfaEnabledInAdmin": true,
  "enableSmartCardAuthInAdmin": false,
  "desktopDownloadUrl": "https://cdn.example.com/vscrawl-desktop.exe"
}

mfaEnabledInAdmin/enableSmartCardAuthInAdmin reflect org/plan-level policy — you can't enable something your organization's plan doesn't allow.

PUT /user/v1/settings/security
Content-Type: application/json

{
  "mfaEnabled": true,
  "secretEnabled": true,
  "secretQuestion": "What is your favorite color?",
  "secret": "Blue",
  "tOtp": 483920
}

Field	Validation
secretQuestion	optional, 5–100 chars, letters (+ optional trailing ?)
secret	optional, 5–100 chars, letters only
mfaEnabled, scaEnabled, secretEnabled, passKeyEnabled, enableSmartCardAuth	boolean flags
tOtp	integer, required the first time you enable MFA

---

Enabling TOTP (authenticator app)

POST /auth/v1/otp/setup/begin
Authorization: Bearer <token>

{ "otpAuthUri": "otpauth://totp/vScrawl:jane@example.com?secret=...", "secret": "JBSWY3DPEHPK3PXP" }

Render otpAuthUri as a QR code, or show secret for manual entry into an authenticator app.

POST /auth/v1/otp/setup/confirm
Authorization: Bearer <token>
Content-Type: application/json

{ "code": "123456" }

{ "message": "OTP enabled", "kcOtpEnabled": true }

DELETE /auth/v1/otp disables it again.

---

Passkeys

Registering a new passkey:

POST /webauthn/register/options?username=jane@example.com
  → browser's navigator.credentials.create()
POST /webauthn/register/verify?username=jane@example.com  (body: the resulting credential JSON)
  → { "status": "success", "message": "Passkey registered successfully" }

PUT /user/v1/settings/disable/passkey turns passkey login back off for the account.