Authentication module

FastStaq ships a complete authentication system so you never have to build sign-in from scratch. This article explains how it works and where to configure it.

What is included

• Email and password registration and login with strong password rules.
• Email verification before sensitive actions.
• Password reset via emailed link.
• Magic links for passwordless sign-in.
• Google OAuth (Sign in with Google). See Configure Google OAuth.
• Two-factor authentication (TOTP) for users and an enforceable policy for admins.

How sessions work

• Authentication uses signed JWTs delivered as HTTP-only cookies, so tokens are not exposed to JavaScript.
• Access tokens are short-lived (default 15 minutes, JWT_ACCESS_EXPIRY); refresh tokens last longer (JWT_REFRESH_EXPIRY, default 7 days).
• A per-user tokenVersion lets you revoke every session at once (used by password reset, suspend, and "log out everywhere").
• JWT_SECRET signs tokens; optional rotation is supported with JWT_SECRET_CURRENT / JWT_SECRET_PREVIOUS.

Cookie configuration

• On a single host (local dev or one domain), leave COOKIE_DOMAIN unset.
• On split hosts (front-end on example.com, API on api.example.com), set COOKIE_DOMAIN=.example.com or the front-end middleware cannot see the cookie and you get a /dashboard -> /login redirect loop.
• Harden with COOKIE_SECURE=true and an appropriate COOKIE_SAMESITE in production.

Two-factor and admin enforcement

• Users enable TOTP from account settings. See Managing your account and 2FA.
• TOTP secrets are encrypted at rest with ENCRYPTION_KEY.
• Require MFA for admins with COMPLIANCE_REQUIRE_MFA_FOR_ADMINS (production) or ADMIN_2FA_ENFORCED.

Optional hardening

• ENABLE_PASSWORD_BREACH_CHECK=true rejects known-breached passwords via the Have I Been Pwned k-anonymity API.
• MAGIC_LINK_AUTO_PROVISION controls whether magic links can create accounts.

Related articles

• Roles and permissions (RBAC)
• User management and profiles

Still need help?

Open a support ticket with the auth flow and any error message.