Authentication
Authentication
This page covers how you sign in, how your session stays alive, and the rules around passwords and email verification. It applies to every user; admins should read the Force password change and Password policy sections.
Logging in
Sign in with your email and password.
POST /api/auth/login
{ "email": "you@example.com", "password": "••••••••", "rememberMe": true }
| Field | Required | Notes |
|---|---|---|
email | Yes | Your work email. |
password | Yes | Your account password. |
rememberMe | No | Defaults to true. Controls how long the session lasts (see below). |
Account enumeration is prevented by design
A wrong password and a non-existent or deactivated account both return the same generic error: Invalid email or password. We intentionally return identical responses regardless of which case applies, so a sign-in attempt never reveals whether an email address is in use.
Organizations that require single sign-on
When an organization has turned password sign-in off or requires SSO in Settings → SSO, password sign-in is refused for its people with SSO_REQUIRED: "Your organization signs in with single sign-on. Use "Sign in with SSO" on the sign-in page." This is enforced by the server for the web sign-in page and the AI connector's sign-in page, not only hidden in the form. The mobile app is the exception: it signs in with email and password only, so people in an SSO organization set a password once and use it there. See Signing in on the mobile app.
The rule applies only while SSO is fully set up: enabled, with the Auth0 domain, client ID and client secret saved, and an email domain it accepts. A half-finished SSO setup never locks people out of their passwords. See Auth0 Integration.
What happens on a successful login
- A seat-limit check runs. If the organization is over its plan's user cap, login is blocked with 403 — except for Executive accounts, which are exempt so an owner can always get in to fix billing.
- You receive an access token and a refresh token (on web, the refresh token is also set as an HttpOnly cookie).
- The submitted password is checked against known breached-password lists in the background. If it appears in a known breach, you get a security alert (sent occasionally, not on every login).
Every login attempt, success or failure, is recorded (see Audit & Monitoring). Repeated failures feed a failed-login-burst tripwire.
JWT tokens & rotation
| Token | Lifetime | Stored where |
|---|---|---|
| Access token | Short-lived | Held by the client; sent as Authorization: Bearer. |
| Refresh token (remember me) | Longer-lived | Database + HttpOnly cookie (web). |
| Refresh token (session only) | Shorter-lived | Database + HttpOnly cookie (web). |
The access token's payload includes: userId, organizationId, role, email, emailVerified, onboardingCompleted, forcePasswordChange, and requiresTwoFactorSetup.
Refresh rotates everything
POST /api/auth/refresh
{ "refreshToken": "..." }
On every refresh, both tokens are rotated atomically — the old pair is deleted and a fresh pair issued in one transaction.
| Situation | Response | Meaning |
|---|---|---|
| Normal refresh | New access + refresh token | Old pair is now invalid. |
| Reusing an already-rotated refresh token | Token already rotated - use the new token | Treated as token theft: you are signed out everywhere (see below). |
| Two refreshes racing | 409 Token refresh in progress - please retry | Another refresh is mid-flight; retry shortly. |
Two tabs, or a network retry, often refresh the same token at nearly the same moment. A request
that loses that race within 60 seconds of the rotation is still refused with
Token already rotated, but it is treated as normal and is not recorded as a security violation.
Reusing an older rotated token is still flagged as possible theft, once per token.
Reuse signs you out everywhere
When a refresh token that was already rotated is presented again after that 60-second window, two parties hold the same session and there is no way to tell which one is genuine. BookYourPTO then revokes every refresh token you have, on every device. You sign in again with your password (and second factor), which someone holding only a stolen token does not have.
A token that was revoked rather than rotated, for example by signing out or changing your password, is simply refused. It does not end the session you opened since.
Force password change
Users created by an administrator are created with forcePasswordChange = true. Until they set their own password, they are blocked (403) on everything except auth, profile, settings, and security pages, and are redirected to set a password. Setting the new password clears the flag and issues fresh tokens.
Password policy
The policy is org-configurable. The defaults are:
| Rule | Default |
|---|---|
| Minimum length | 8 characters (clamped to the 8–32 range) |
| Uppercase letter | Required |
| Lowercase letter | Required |
| Number | Required |
| Special character | Not required |
| Breached-password check | New passwords found in known breached-password lists are rejected |
New passwords are checked against known breached-password lists; the password itself never leaves our systems.
Changing your password logs you out everywhere
When you change your password, all of your refresh tokens are deleted (signing you out on every device), then a fresh pair is issued for your current session. The new password must be different from your current one.
Forgot & reset password
POST /api/auth/forgot-password
{ "email": "you@example.com" }
This always returns the same generic message — it never reveals whether the email exists. It works in organizations that require single sign-on too, because that is how their people set the password the mobile app uses. Behind the scenes it issues two credentials, both hashed in the database and valid for a limited time:
- a 6-digit code (handy for mobile entry), and
- a long URL token (embedded in the email link).
POST /api/auth/reset-password
{ "token": "<long token>", "password": "NewPass1", "email": "you@example.com" }
You may supply either the 6-digit code (in which case email is required) or the long token. On success:
- the password is updated,
- your email is marked verified (the reset link doubles as proof you control the inbox — useful for first-time setup),
- all refresh tokens are deleted, and
- a confirmation email is sent.
Email verification
POST /api/auth/verify-email
{ "token": "..." }
A verification link works once. The first click verifies your email and spends the link; clicking it again (or an old link from a forwarded email) verifies nothing and does not sign anyone in. If your email is already verified, the link simply says so. Until you verify, you're blocked (403) on most endpoints and sent to the verification screen. A new verification email can be requested again after a short wait.
Verification can't be skipped. When you sign up, the verification email must be sent. If it can't be (for example, the address is on a domain that does not receive mail), your account stays unverified on the verification screen, where you can Resend it or try a different email. Resend tells you when the email could not be sent rather than claiming it went out. The only exception is a self-hosted install with no email settings at all, where there is nothing to send with; see Running without email.
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
401 Invalid email or password | Wrong credentials or a deactivated account (deliberately indistinguishable). | Re-check your password; if it's correct, contact your administrator — the account may be deactivated. |
403 Email verification required | Your email isn't verified yet. | Click the link in your verification email; resend after a short wait if needed. |
| "We could not send an email to this address" on Resend | The verification email could not be delivered to that address. | Check the address is correct, or choose try a different email and sign up with another one. |
403 Password change required | You were created with a forced password change. | Set a new password when prompted. |
403 over the seat limit (non-executive) | The org has more users than its plan allows. | An admin/executive must reduce users or upgrade the plan. See Plans. |
Token already rotated | An old refresh token was reused. | Use the most recent token your client received; sign in again if unsure. |
| Signed out on every device at once | A rotated refresh token was reused, which is treated as theft. | Sign in again. If it keeps happening, change your password. |
SSO_REQUIRED | Your organization signs in with single sign-on. | Use Sign in with SSO on the sign-in page. On the mobile app, sign in with your email and the password you set for it. |
409 Token refresh in progress | Two refreshes ran at once. | Retry the request. |
429 with retryAfter | Rate limit hit (e.g. too many logins). | Wait the indicated time, then retry. |
The forgot/reset credentials are valid for a limited time — request a fresh one if it has expired.
Security Overview
How BookYourPTO protects your account and your organization's data — authentication, encryption, rate limiting, security headers, audit logging, and account guards.
Two-Factor & Devices
Set up TOTP two-factor authentication, save backup codes, verify at login, and manage trusted devices in BookYourPTO.