> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# UJ-M-001: Register or Login

> Member authenticates via SSO or email/password to access the portal

## Journey Overview

| Attribute      | Value                                                    |
| -------------- | -------------------------------------------------------- |
| **Journey ID** | UJ-M-001                                                 |
| **Actor**      | Prospective or existing member                           |
| **Goal**       | Gain authenticated access to the Member Portal           |
| **Trigger**    | User navigates to member portal URL or clicks login link |
| **Outcome**    | User is authenticated and redirected to dashboard        |

## Preconditions

* User has a valid email address
* For SSO: Organization has configured SSO provider (WorkOS)
* For existing members: Account exists in the system

## Journey Flow

```mermaid theme={null}
flowchart TD
    A[User visits Member Portal] --> B{Has account?}
    B -->|No| C[Click Register]
    B -->|Yes| D[Click Login]
    C --> E[Enter registration details]
    E --> F[Verify email]
    F --> G[Complete profile]
    D --> H{SSO enabled?}
    H -->|Yes| I[Redirect to SSO provider]
    H -->|No| J[Enter email/password]
    I --> K[SSO authentication]
    J --> L[Validate credentials]
    K --> M[Issue JWT token]
    L --> M
    G --> M
    M --> N[Redirect to Dashboard]
```

## Detailed Steps

<Steps>
  <Step title="Access Portal">
    User navigates to the member portal URL (e.g., `members.organization.com`).

    **System Response:**

    * Displays login/register screen
    * Shows SSO button if configured for the organization
    * Shows email/password form as fallback
  </Step>

  <Step title="Choose Authentication Method">
    User selects their preferred authentication method:

    **Option A - SSO (if available):**

    * Click "Continue with \[Provider Name]"
    * Redirected to identity provider (Google, Microsoft, Okta, etc.)
    * Complete authentication with provider
    * Redirected back with auth token

    **Option B - Email/Password:**

    * Enter registered email address
    * Enter password
    * Click "Sign In"

    **Option C - New Registration:**

    * Click "Create Account" or "Register"
    * Proceed to registration flow
  </Step>

  <Step title="System Validates Credentials">
    **For SSO:**

    * System validates OAuth token from provider
    * Matches user to existing account or creates new account
    * Retrieves user profile from provider (name, email, avatar)

    **For Email/Password:**

    * System validates email exists
    * System validates password hash matches
    * Checks account status (active, suspended, locked)

    **Validation Failures:**

    * Invalid credentials → "Invalid email or password"
    * Account locked → "Account locked. Contact support."
    * Account suspended → "Account suspended. Contact support."
  </Step>

  <Step title="Issue Authentication Token">
    System issues JWT token containing:

    * User ID
    * Tenant ID (organization)
    * Role(s)
    * Token expiry

    Token is stored in:

    * HTTP-only secure cookie (primary)
    * Local storage (refresh token)
  </Step>

  <Step title="Redirect to Dashboard">
    User is redirected to:

    * Dashboard (default)
    * Original requested URL (if deep-linked)
    * Profile completion page (if profile incomplete)
  </Step>
</Steps>

## New Member Registration Flow

<Steps>
  <Step title="Enter Basic Information">
    * Email address (required, unique)
    * First name (required)
    * Last name (required)
    * Password (required, min 8 chars, complexity rules)
    * Confirm password
  </Step>

  <Step title="Email Verification">
    * System sends verification email with 6-digit code
    * User enters code within 15 minutes
    * System marks email as verified
  </Step>

  <Step title="Accept Terms">
    * User reviews Terms of Service
    * User reviews Privacy Policy
    * User checks acceptance checkbox
  </Step>

  <Step title="Account Created">
    * System creates user account
    * User redirected to profile completion
  </Step>
</Steps>

## Error Scenarios

| Scenario                           | System Response                                        | User Action                        |
| ---------------------------------- | ------------------------------------------------------ | ---------------------------------- |
| Invalid email format               | "Please enter a valid email address"                   | Correct email                      |
| Email already registered           | "An account with this email already exists"            | Use login or password reset        |
| Incorrect password                 | "Invalid email or password"                            | Try again or reset password        |
| Account locked (5 failed attempts) | "Account temporarily locked. Try again in 30 minutes." | Wait or contact support            |
| SSO provider error                 | "Authentication failed. Please try again."             | Retry or use email/password        |
| Email not verified                 | "Please verify your email first"                       | Check inbox for verification email |
| Session expired                    | Redirect to login page                                 | Re-authenticate                    |

## Password Reset Flow

<Steps>
  <Step title="Request Reset">
    User clicks "Forgot Password" and enters email
  </Step>

  <Step title="Receive Email">
    System sends password reset link (valid 1 hour)
  </Step>

  <Step title="Set New Password">
    User clicks link and enters new password
  </Step>

  <Step title="Confirmation">
    System updates password and redirects to login
  </Step>
</Steps>

## Security Considerations

* Passwords hashed using bcrypt (cost factor 12)
* Rate limiting: 5 failed attempts = 30-minute lockout
* JWT tokens expire after 24 hours
* Refresh tokens expire after 7 days
* All auth endpoints use HTTPS only
* CSRF protection on all forms

## Related Entities

* [`User/Member`](/entities/core/user-member)
* [`Audit Log`](/entities/system/audit-log)

## Related Journeys

* [UJ-M-002](/member/journeys/complete-profile)
* [UJ-M-003](/member/journeys/choose-membership-plan)

## Acceptance Criteria

### Frontend

* [ ] Login form with email/password fields
* [ ] SSO button displayed when configured
* [ ] Registration form with validation
* [ ] Email verification code input
* [ ] Password reset flow implemented
* [ ] Loading states during authentication
* [ ] Error messages displayed clearly
* [ ] Remember me checkbox (extends session)

### Backend

* [ ] `POST /api/auth/login` - Email/password login
* [ ] `POST /api/auth/register` - New user registration
* [ ] `POST /api/auth/verify-email` - Email verification
* [ ] `POST /api/auth/forgot-password` - Password reset request
* [ ] `POST /api/auth/reset-password` - Password reset completion
* [ ] `GET /api/auth/sso/{provider}` - SSO initiation
* [ ] `POST /api/auth/sso/callback` - SSO callback

### Permissions

* [ ] Public access to login/register endpoints
* [ ] Rate limiting applied to auth endpoints

### Business Rules

* [ ] Email must be unique per tenant
* [ ] Password complexity enforced
* [ ] Email verification required before full access
* [ ] SSO users cannot set password (SSO-only)

### Error Handling

* [ ] Generic error for invalid credentials (security)
* [ ] Clear messages for account status issues
* [ ] Graceful SSO provider failure handling