User Management & Authentication

Secure user authentication and comprehensive profile management powered by NileDB.

MVP Status & Roadmap

Current Status: MVP In Progress

What’s Available Today:

✅ Email/password signup and login
✅ Email verification flow
✅ Password reset flow
✅ Change password (authenticated)
✅ JWT-based session management
✅ Token refresh mechanism
✅ Profile management (view/edit)
✅ Team member invitations
✅ Role-based access control (Owner/Admin/Member)
✅ Account deletion with grace period

Missing MVP Features (Q1 2026):

⏳ Account lockout / brute force protection
⏳ Session management UI (view/revoke active sessions)
⏳ Email change verification flow UI
⏳ Password strength enforcement (server-side)
⏳ Login activity log
⏳ Unverified email restrictions
⏳ Remember me functionality
⏳ CAPTCHA for sensitive operations

Post-MVP Enhancements (2026+):

🛡️ Two-factor authentication (2FA) - Q1 2026
🌐 Social login (OAuth) - Q2 2026
🔑 Single sign-on (SSO) for enterprise - Q3 2026
🧬 Biometric authentication - Q4 2026
🕒 Advanced session management - Q4 2026

Detailed Roadmap: Authentication Roadmap

Overview

PenguinMails provides enterprise-grade user authentication with email/password login, profile management, password security features, and session management - all built on NileDB’s secure authentication framework.

Authentication Features

🔐 Secure Login - Email/password authentication via NileDB SDK
👤 Profile Management - Self-service profile editing
🔑 Password Security - Forgot/reset/change password workflows
🛟 Session Management - Secure token-based sessions
👥 Team Management - Multi-user tenant support
✉️ Email Verification - Confirmed email addresses only

Level 1: User Authentication

Create a new account and tenant:

Sign Up Form:

- Email Address *

- Full Name *

- Password * (min 8 characters)

- Company Name *

- [ ] I agree to Terms of Service

[Create Account]

Sign Up Flow:

User submits registration form
Backend creates tenant + owner user
Email verification sent
User clicks verification link
Account activated
Redirected to onboarding

API Endpoint:

POST /api/v1/auth/signup

{
  "email": "user@example.com",
  "name": "John Doe",
  "password": "SecurePass123!",
  "company_name": "Acme Corp"
}

Response:
{
  "user_id": "user_abc123",
  "tenant_id": "tenant_xyz789",
  "email": "user@example.com",
  "email_verified": false,
  "verification_sent": true
}

Secure email/password authentication:

Login Form:

- Email Address

- Password

- [x] Remember me (optional)

[Login] | [Forgot Password?]

Login Flow:

User enters email/password
NileDB validates credentials
JWT token generated (includes tenant_id)
Session established
Redirect to dashboard

API Endpoint:

POST /api/v1/auth/login

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "tenant_id": "tenant_xyz789",
    "role": "owner"
  },
  "expires_in": 3600 // 1 hour
}

Logout

End user session:

POST /api/v1/auth/logout
Authorization: Bearer {access_token}

Response:
{
  "success": true,
  "message": "Successfully logged out"
}

// Backend:
// 1. Invalidate access token
// 2. Revoke refresh token
// 3. Clear server-side session

Client-side:

Remove tokens from storage
Clear user state
Redirect to login page

Email Verification

Verify email address after signup:

Verification Email:

Subject: Verify your PenguinMails account

Hi John,

Welcome to PenguinMails! Please verify your email address:

[Verify Email Address]

Or copy this link:
https://app.penguinmails.com/verify-email?token=abc123

This link expires in 24 hours.

Verification Flow:

GET /api/v1/auth/verify-email?token={verification_token}

Response:
{
  "success": true,
  "email_verified": true,
  "redirect_url": "/onboarding"
}

Re-send Verification:

POST /api/v1/auth/resend-verification
{
  "email": "user@example.com"
}

Level 2: Password Management

Forgot Password

Reset password via email link:

Forgot Password Form:

Forgot Password

Enter your email address and we'll send you a link to reset your password.

Email Address: _______________

[Send Reset Link]

Reset Flow:

User enters email
System sends reset link (if email exists)
Link expires in 1 hour
User clicks link
Enter new password
Password updated
Auto-login with new password

API Endpoints:

// Step 1: Request reset
POST /api/v1/auth/forgot-password
{
  "email": "user@example.com"
}

Response:
{
  "success": true,
  "message": "If that email exists, we sent a reset link"
  // Note: Don't reveal if email exists (security)
}

// Step 2: Reset password
POST /api/v1/auth/reset-password
{
  "token": "reset_token_abc123",
  "new_password": "NewSecurePass456!"
}

Response:
{
  "success": true,
  "message": "Password reset successful",
  "access_token": "eyJhbGc..." // Auto-login
}

Change Password

Change password while logged in:

Change Password

Current Password: _______________
New Password: _______________
Confirm New Password: _______________

[Update Password]

Password Requirements:

✅ Minimum 8 characters
✅ At least one uppercase letter
✅ At least one lowercase letter
✅ At least one number
✅ At least one special character (optional but recommended)

API Endpoint:

POST /api/v1/auth/change-password
Authorization: Bearer {access_token}

{
  "current_password": "OldPass123!",
  "new_password": "NewPass456!"
}

Response:
{
  "success": true,
  "message": "Password updated successfully"
}

Level 3: Profile Management

View Profile

User profile information:

GET /api/v1/users/me
Authorization: Bearer {access_token}

Response:
{
  "user_id": "user_abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "tenant_id": "tenant_xyz789",
  "role": "owner",
  "email_verified": true,
  "created_at": "2025-11-01T10:00:00Z",
  "preferences": {
    "timezone": "America/Los_Angeles",
    "date_format": "MM/DD/YYYY",
    "email_notifications": true
  }
}

Update Profile

Edit profile information:

Edit Profile

Full Name: John Doe
Email: user@example.com (verified ✓)
Timezone: America/Los_Angeles
Date Format: MM/DD/YYYY

[Save Changes]

API Endpoint:

PUT /api/v1/users/me
Authorization: Bearer {access_token}

{
  "name": "John Smith",
  "preferences": {
    "timezone": "America/New_York",
    "date_format": "YYYY-MM-DD"
  }
}

Response:
{
  "success": true,
  "user": {
    "name": "John Smith",
    "preferences": {
      "timezone": "America/New_York",
      "date_format": "YYYY-MM-DD"
    }
  }
}

Changing Email:

// Requires email verification
POST /api/v1/users/me/change-email
{
  "new_email": "newemail@example.com",
  "password": "CurrentPass123!" // Confirm with password
}

Response:
{
  "success": true,
  "email_verification_sent": true,
  "message": "Verify your new email address"
}

User Preferences

Customizable user settings:

{
  "preferences": {
    // Regional Settings
    "timezone": "America/Los_Angeles",
    "date_format": "MM/DD/YYYY",
    "time_format": "12h", // 12h or 24h
    "language": "en",

    // Notification Settings
    "email_notifications": true,
    "campaign_alerts": true,
    "weekly_reports": true,
    "billing_alerts": true,

    // Dashboard Settings
    "default_workspace": "ws_abc123",
    "dashboard_layout": "compact",
    "show_onboarding": false
  }
}

Team & Workspace Management

MVP Status & Roadmap

Current Status: Partially Complete

What’s Available Today:

✅ Team member invitation system
✅ Role-based access control (Owner, Admin, Member)
✅ View all team members with status
✅ Update user roles
✅ Remove team members from tenant
✅ Workspace assignment during invitation
✅ Multi-tenant architecture with complete data isolation

Missing MVP Features (Q1 2026):

⏳ Workspace management feature documentation (2-3 days)
⏳ Workspace health scoring system (3-5 days)
⏳ Organization settings & branding documentation (2-3 days)
⏳ RBAC permission matrix documentation (2-3 days)
⏳ Team member removal workflow documentation (1-2 days)
⏳ Workspace member management documentation (3-5 days)
⏳ Workspace deletion & data handling documentation (3-5 days)

Post-MVP Enhancements (2026+):

🛡️ Advanced permissions system (custom roles) - Q2 2026
📜 Audit logs for team actions - Q3 2026
📊 Team analytics & activity monitoring - Q4 2026
📦 Bulk user management - Q3 2026
👥 User groups & teams within tenant - Q1 2027
🧩 Workspace templates - Q2 2027
🌀 Workspace duplication - Q3 2027
🕒 Advanced session management - Q4 2026
🚀 Team member onboarding workflows - Q1 2027
🤝 External user collaboration (client portal) - Q2 2027

Detailed Roadmap: Team Management Roadmap

Team Management

Inviting Users

Add team members to tenant:

Invite Team Member

Email Address: _______________
Role: [Admin ▼]
Workspaces: [x] Client A  [ ] Client B

[Send Invitation]

Invitation Flow:

Admin sends invitation
Email sent to invitee
Invitee clicks link
Creates account or logs in
Automatically added to tenant
Assigned to selected workspaces

API Endpoint:

POST /api/v1/tenants/{tenant_id}/invitations
Authorization: Bearer {access_token}

{
  "email": "newuser@example.com",
  "role": "admin", // owner, admin, member
  "workspaces": ["ws_abc123", "ws_def456"]
}

Response:
{
  "invitation_id": "inv_abc123",
  "email": "newuser@example.com",
  "status": "pending",
  "expires_at": "2025-12-01T10:00:00Z"
}

Managing Team Members

View all team members:

GET /api/v1/tenants/{tenant_id}/users
Authorization: Bearer {access_token}

Response:
{
  "users": [
    {
      "user_id": "user_abc123",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "owner",
      "status": "active",
      "last_login": "2025-11-24T10:00:00Z"
    },
    {
      "user_id": "user_def456",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "admin",
      "status": "active",
      "last_login": "2025-11-23T15:30:00Z"
    }
  ],
  "total": 2
}

Update User Role:

PUT /api/v1/tenants/{tenant_id}/users/{user_id}
{
  "role": "member" // Downgrade from admin
}

Remove User:

DELETE /api/v1/tenants/{tenant_id}/users/{user_id}

// User removed from tenant
// Loses access to all workspaces
// Data ownership transferred to tenant owner

Workspace Management

Multi-workspace support for agencies:

Create multiple client workspaces within tenant
Workspace-level access control (Admin, Member, Viewer)
Assign team members to specific workspaces
Workspace health monitoring (0-100 score)
Isolated campaigns, leads, and settings per workspace

Workspace Routes:

/dashboard/workspaces - List all workspaces with health scores
/dashboard/workspaces/new - Create new workspace
/dashboard/workspaces/[slug]/settings - Workspace settings

See Also: Multi-Tenant Architecture for technical details

Session Management

JWT Tokens

Authentication uses JWT (JSON Web Tokens):

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "user_id": "user_abc123",
    "tenant_id": "tenant_xyz789",
    "email": "user@example.com",
    "role": "admin",
    "iat": 1700830200, // Issued at
    "exp": 1700833800  // Expires (1 hour)
  },
  "signature": "..."
}

Token Types:

Access Token - Short-lived (1 hour), used for API requests
Refresh Token - Long-lived (30 days), used to get new access tokens

Token Refresh:

POST /api/v1/auth/refresh
{
  "refresh_token": "eyJhbGciOiJI..."
}

Response:
{
  "access_token": "eyJhbGciOiJI...", // New access token
  "expires_in": 3600
}

Session Security

Security Features:

Automatic Logout - 30 minutes of inactivity
Token Expiration - Access tokens expire in 1 hour
Refresh Rotation - New refresh token on each refresh
Revocation - Tokens can be revoked server-side
IP Tracking - Log IP addresses for security monitoring

Session Endpoints:

// Get active sessions
GET /api/v1/auth/sessions

Response:
{
  "sessions": [
    {
      "session_id": "sess_abc123",
      "device": "Chrome on macOS",
      "ip_address": "192.168.1.1",
      "last_active": "2025-11-24T10:30:00Z",
      "current": true
    }
  ]
}

// Revoke session
DELETE /api/v1/auth/sessions/{session_id}

Account Deletion

Delete user account:

⚠️ Delete Account

This will permanently delete your account and all associated data.

Type "DELETE" to confirm: _______________

[Delete My Account]

Deletion Process:

DELETE /api/v1/users/me
Authorization: Bearer {access_token}

{
  "confirmation": "DELETE",
  "password": "UserPass123!" // Confirm with password
}

Response:
{
  "success": true,
  "scheduled_deletion": "2025-12-24T10:00:00Z", // 30 days
  "message": "Account scheduled for deletion"
}

What Happens:

Immediate: Account marked for deletion, access revoked
30 days: Grace period for account recovery
After 30 days: Permanent deletion of all data

Authentication & Security

Authentication Roadmap - Detailed authentication timeline and quarterly breakdown
Team Management Roadmap - Detailed team & workspace management timeline
Multi-Tenant Architecture - Tenant isolation and workspace architecture
Security Framework - Security overview
Vault Integration - Secure secrets management for API keys and credentials

Implementation

NileDB Authentication - Auth implementation
API Authentication - API auth details
Public & Authentication Routes - Login, signup, password reset UI
Settings Routes - Profile, team management, security settings UI

Tasks

Epic 2: User Authentication - Internal task reference for implementation work

Roadmap

Product Roadmap - Authentication features timeline
Executive Roadmap - Strategic authentication priorities

Last Updated: November 26, 2025 Authentication Provider: NileDB SDK Current Method: Email + Password MVP Status: In Progress (8 of 11 MVP features remaining) Next Milestone: Q1 2026 - Complete MVP authentication features

Secure user authentication is the foundation of platform security. NileDB provides enterprise-grade authentication with tenant isolation built-in. For MVP and near-term releases, we continue using NileDB’s email/password authentication. OAuth 2.0 and SSO (SAML, OpenID Connect) are planned for Q2-Q3 2026 to meet enterprise customer requirements.

User Management & Authentication

MVP Status & Roadmap

Current Status: MVP In Progress

Overview

Authentication Features

Level 1: User Authentication

Sign Up (Registration)

Login

Logout

Email Verification

Level 2: Password Management

Forgot Password

Change Password

Level 3: Profile Management

View Profile

Update Profile

User Preferences

Team & Workspace Management

MVP Status & Roadmap

Current Status: Partially Complete

Team Management

Inviting Users

Managing Team Members

Workspace Management

Session Management

JWT Tokens

Session Security

Account Deletion

Related Documentation

Authentication & Security

Implementation

Tasks

Roadmap