User Management
Authentication, user profiles, password flows, and rate limiting
User Management
What's Included
- Email/password registration with email validation
- Social login via Firebase (Google, Apple)
- JWT access tokens with refresh token rotation
- Forgot password / reset password flow
- Change password for authenticated users
- Rate limiting on all auth endpoints
Password Authentication
Users register with a name, email, and password. On registration:
- The account is created with
emailValidated: false - A
UserCreatedevent dispatches a welcome email containing a validation link - The user receives a JWT access token and refresh token immediately
Clicking the validation link in the email sets emailValidated: true and redirects to your configured EMAIL_VALIDATION_REDIRECT_URL.
Login accepts email + password and returns a JWT access token + refresh token.
Social Login (Firebase)
Social authentication is handled via Firebase Authentication. The frontend obtains a Firebase ID token (Google, Apple, etc.) and sends it to the backend, which verifies it via the Firebase Admin SDK.
- New users are auto-created with
emailValidated: true(social providers pre-verify emails) and provider set togoogle,apple, etc. - Existing users (matched by email) get new tokens issued
- Social signup does not send a validation email
Session Management
| Token | Type | Lifetime | Notes |
|---|---|---|---|
| Access token | JWT | 1 hour | Sent in Authorization: Bearer header |
| Refresh token | Opaque | 30 days | Single-use — each refresh issues a new pair |
- Refresh exchanges a valid refresh token for a new access + refresh token pair. The old refresh token is invalidated.
- Logout invalidates all refresh tokens for the user.
Password Reset Flow
- Forgot password — user submits their email. A
PasswordResetRequestedevent dispatches a reset email with a tokenized link. The response is always202 Acceptedregardless of whether the email exists (prevents enumeration). - Reset redirect — the link in the email hits the backend, which validates the token and redirects to
{FRONTEND_RESET_PASSWORD_URL}?token={token}. Expired tokens return 404 and are auto-deleted. - Reset password — the frontend submits the token + new password. On success, a
PasswordChangedevent sends a confirmation email.
Change Password
Authenticated users can change their password by providing their current password and a new one. A PasswordChanged event sends a confirmation email.
User Profile
Returns the current user's profile (id, name, email, emailValidated, provider, createdAt) via a DBAL read model for optimized reads.
Rate Limiting
Authentication endpoints are rate-limited to prevent brute force attacks. See Configuration > Rate Limiting for the full limiter definitions and thresholds.
Security
- Password hashing — bcrypt with cost factor 12
- Email enumeration prevention — forgot password always returns 202, login returns a generic "Invalid credentials" error
- Token expiry — access tokens (1h), refresh tokens (30d), email validation and password reset tokens are single-use and auto-deleted after use or expiry
- Single-use refresh tokens — prevents token replay attacks