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 }

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.

What happens on a successful login

1. 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.
2. You receive an access token and a refresh token (on web, the refresh token is also set as an HttpOnly cookie).
3. 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

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.

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:

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. 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": "..." }

Verification is idempotent — clicking the link twice is harmless. 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.

Troubleshooting

The forgot/reset credentials are valid for a limited time — request a fresh one if it has expired.