Two-Factor Authentication (TOTP)

Vetrix supports time-based one-time passwords (TOTP) per RFC 6238, compatible with Google Authenticator, Authy, 1Password, and other TOTP apps.

Enrolment

1. Begin enrolment

POST /api/v1/user/2fa/totp/enroll
Authorization: Bearer <jwt>

Response:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "uri": "otpauth://totp/Vetrix:alice?secret=JBSWY3DPEHPK3PXP&issuer=Vetrix&...",
  "backup_codes": ["ABCD1234", "EFGH5678", ...]
}

• Scan the uri with your authenticator app, or enter the secret manually.
• Save the backup codes now. They are shown once and cannot be retrieved. Each code can be used once to log in if you lose access to your authenticator.

2. Confirm enrolment

Generate the current 6-digit code from your authenticator app and confirm:

POST /api/v1/user/2fa/totp/confirm
Authorization: Bearer <jwt>

{ "code": "123456" }

TOTP is now active on your account.

Disabling 2FA

POST /api/v1/user/2fa/totp/disable
Authorization: Bearer <jwt>

{ "password": "<current-password>" }

Your account password is required to disable 2FA.

Backup codes

• 10 backup codes are generated at enrolment. Each can be used once.
• Codes are case-insensitive.
• After using a backup code, generate new ones by disabling and re-enrolling 2FA.
• Backup codes are stored as SHA-256 hashes; Vetrix never stores the plaintext.

TOTP parameters

Parameter	Value
Algorithm	HMAC-SHA1 (RFC 4226)
Period	30 seconds
Digits	6
Clock skew window	±1 step (30 seconds each side)