Security & Privacy

Two-Factor & Devices

Set up TOTP two-factor authentication, save backup codes, verify at login, and manage trusted devices in BookYourPTO.

Two-Factor Authentication & Trusted Devices

Two-factor authentication (2FA) adds a second step to login: after your password, you enter a rotating 6-digit code from an authenticator app. BookYourPTO uses TOTP (the standard behind Google Authenticator, Authy, 1Password, etc.). Your organization may make 2FA mandatory — if so, you'll be forced to set it up before you can continue.

Setting up 2FA

POST /api/auth/totp/setup

The response gives you three things:

Item	Use
QR code	Scan it with your authenticator app.
Base32 secret	Type it in manually if you can't scan.
Backup codes	One-time codes shown once — save them now.

A limited setup window applies: confirm before it lapses or you'll need to start over.

Save your backup codes immediately. They are shown only once and stored only as hashes — BookYourPTO cannot show them to you again. They're your way back in if you lose your authenticator.

Confirming setup

POST /api/auth/totp/confirm
{ "code": "123456" }

Entering a valid code enables 2FA and issues fresh tokens. From now on, login requires your second factor.

Logging in with 2FA

If 2FA is enabled and your device isn't trusted, login returns a challenge instead of tokens:

{ "requiresTwoFactor": true, "twoFactorToken": "<short-lived token>" }

Complete it before the short challenge window lapses:

POST /api/auth/totp/verify
{ "code": "123456", "twoFactorToken": "...", "rememberDevice": true }

Field	Notes
`code`	A current TOTP code or one of your backup codes (single-use).
`twoFactorToken`	The short-lived token from the login challenge.
`rememberDevice`	If true, trusts this device so it skips 2FA for a limited period.

On success you receive real access and refresh tokens.

Backup codes

Generated during setup and shown once.
Each code works only once.
Use one in place of a TOTP code if you've lost your authenticator.
Regenerating backup codes requires your current password.

Disabling 2FA

POST /api/auth/totp/disable
{ "password": "your-current-password" }

Disabling requires your current password and revokes all trusted devices. If your organization mandates 2FA, you can't leave it disabled — you'll be prompted to set it up again.

Trusted devices

Choosing "trust this device" at verification creates a device record so you skip the 2FA prompt on that device for a limited period.

Stored	Detail
Token	A random token kept only as a hash; the plaintext lives in an HttpOnly cookie on your device.
Device name	Derived from the browser/OS user agent.
IP & expiry	The IP at trust time, and an expiry date.

Managing your devices

Action	Request
List devices (your current one is flagged)	`GET /api/auth/devices`
Revoke one device	`DELETE /api/auth/devices/:id`
Revoke all devices	`POST /api/auth/devices/revoke-all`

Disabling 2FA also revokes all trusted devices automatically.

Lost a device? Revoke it from any signed-in session. The next time that device tries to log in, it will be asked for 2FA again.

Troubleshooting

Error	Cause	Fix
`Invalid verification code`	Wrong/expired TOTP, or a backup code already used.	Wait for the next code, or use an unused backup code.
`Two-factor token expired`	The challenge window lapsed.	Log in again to get a new challenge.
`429 Too many verification attempts`	Too many tries in a short span.	Wait, then retry.
Lost authenticator	No access to your TOTP app.	Use a backup code, or ask an admin to disable 2FA on your account.
`403 Two-factor authentication setup required`	Your org mandates 2FA and you don't have it.	Set up 2FA to continue.
Disable rejected	Wrong current password.	Re-enter your current password.

Authentication

How sign-in works in BookYourPTO — login, JWT access and refresh tokens with rotation, force-password-change, the password policy, forgot/reset, and email verification.

Audit & Monitoring

Audit logs, sign-in logs, unknown-login alerts, and log retention in BookYourPTO — what's recorded, who can see it, and how long it's kept.