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) - 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 reset email is dispatched with a tokenized link. Response is always
202 Acceptedregardless of whether the email exists (prevents enumeration). - Reset redirect — the link validates the token and redirects to the frontend reset form with the token in the URL.
- Reset password — the frontend submits the token + new password. A confirmation email is sent on success.
Rate Limiting
Authentication endpoints are rate-limited to prevent brute force attacks:
| Endpoint | IP Limit | Email Limit |
|---|---|---|
| Register | 5 / 15 min | 3 / 15 min |
| Login | 5 / 15 min | 5 / 15 min |
| Social Login | 5 / 15 min | — |
| Logout | 10 / 1 min | — |
Security
- Password hashing — bcrypt with cost factor 12
- Email enumeration prevention — forgot password always returns 202, login returns generic errors
- Token expiry — access tokens (1h), refresh tokens (30d), validation/reset tokens are single-use
- Single-use refresh tokens — prevents token replay attacks