Use Case 012: Email Verification Process

Overview

Description

This use case describes the email verification process that can be enabled for trial user registration. When enabled, trial users must verify their email address before receiving access credentials and being able to login to Riptide applications. The system generates verification tokens, sends verification emails, validates token expiration and status, manages resend requests with rate limiting, and provides administrator override capabilities for manual verification.

Actors

Preconditions

1. Application Manager is running and accessible
2. Email service (SMTP or AWS SES) is configured and operational
3. Email verification is enabled in configuration (RequireEmailVerification: true)
4. Trial user has completed initial registration (UC-001)
5. Verification token expiration period is configured (default: 24 hours)
6. Rate limiting settings are configured for resend operations

Postconditions

Success Postconditions

1. User's EmailVerified flag set to true in database
2. Welcome email with credentials sent to verified user
3. User can now create sessions and login to applications
4. Verification token marked as used/consumed
5. Verification timestamp recorded (VerifiedAt)
6. Activity logged in audit trail

Failure Postconditions

1. EmailVerified remains false if verification fails
2. User cannot login until verified
3. Error messages logged for troubleshooting
4. Admin notification triggered for persistent failures

Triggers

• User completes trial registration (UC-001) with verification enabled
• User clicks verification link in email
• User requests verification email resend
• Verification token expires
• Administrator manually verifies user

Basic Flow (Happy Path)

Detailed Steps

1. System Generates Verification Token

   • Generate cryptographically secure GUID token
   • Calculate expiration: CreatedAt + 24 hours
   • Store token in EmailVerificationTokens table or user record
   • Link token to trial user ID

2. System Sends Verification Email

   • Compose email with:
     • Clear subject line: "Verify Your Riptide Trial Account"
     • Prominent verification button/link
     • Token expiration notice (24 hours)
     • Resend instructions if email not received
     • Support contact information
   • Generate verification URL: https://app-manager.riptide.com/verify-email?token={token}
   • Send via configured email provider
   • Log email delivery attempt with timestamp

3. User Receives Verification Email

   • User checks email inbox (may check spam/junk folder)
   • User sees verification email
   • User reviews email content
   • User clicks "Verify Email" button/link

4. System Receives Verification Request

   • Web UI intercepts verification URL
   • Extract token from query parameter
   • Call API endpoint: POST /api/v1/trial-users/verify-email
   • Pass token in request body

5. System Validates Verification Token

   • Query database for user with matching token
   • If token not found: Return 404 Not Found
   • If token found: Proceed with validation
   • Check token expiration date against current time
   • If expired: Return 400 Bad Request (token expired)
   • If not expired: Proceed with verification

6. System Checks User Status

   • Retrieve user's current EmailVerified status
   • If already verified: Return 200 OK with message "Email already verified"
   • If trial expired while awaiting verification: Handle gracefully (optional: extend trial)
   • If user is inactive: Return 400 Bad Request

7. System Marks Email as Verified

   • Begin database transaction
   • Update trial user record:
     • EmailVerified = true
     • VerifiedAt = Current UTC timestamp
   • Update verification token:
     • UsedAt = Current UTC timestamp
     • IsUsed = true
   • Commit transaction
   • Log verification event in audit trail

8. System Sends Welcome Email

   • Compose welcome email with:
     • Congratulations message
     • Login token (32 characters)
     • API token (64 characters)
     • Direct links to authorized applications
     • Trial expiration date
     • Getting started guide
     • Support contact information
   • Send email to verified address
   • Log email delivery

9. System Returns Success Response

   • Return 200 OK to web UI
   • Include success message in response body
   • Web UI displays confirmation message
   • Redirect to login page after 5 seconds (optional)

10. User Receives Credentials

    • User checks email for welcome message
    • User saves/bookmarks credentials securely
    • User proceeds to login using provided token
    • User accesses trial applications

Alternative Flows

Alt Flow 1: Verification Token Expired

Steps:

1. User clicks expired verification link (token > 24 hours old)
2. System detects token expiration during validation (step 5)
3. System returns 400 Bad Request with error code VerificationTokenExpired
4. Web UI displays user-friendly message: "Your verification link has expired. Verification links are valid for 24 hours."
5. Web UI offers "Resend Verification Email" button
6. User clicks resend button
7. System checks rate limit (max 3 resends per day per user)
8. System generates new verification token
9. System invalidates old token in database
10. System sends new verification email
11. User receives new email and completes verification

Alt Flow 2: Email Already Verified

Steps:

1. User clicks verification link for already-verified account
2. System finds user by token during step 4
3. System checks EmailVerified status during step 6
4. System detects EmailVerified = true
5. System returns 200 OK with message: "Email already verified"
6. Web UI displays: "Your email has already been verified. You can login to your account."
7. Web UI provides "Go to Login" button
8. User clicks button and is redirected to login page
9. No email is sent (credentials already delivered previously)

Alt Flow 3: Verification Email Not Received

Steps:

1. User completes registration but doesn't receive verification email within 5 minutes
2. User navigates to registration confirmation page or clicks "Resend" link
3. User clicks "Resend Verification Email" button
4. System checks resend rate limit:
   • Maximum 3 resends per user per 24 hours
   • Minimum 2 minutes between resend requests
5. If rate limit exceeded:
   • Return 429 Too Many Requests
   • Display: "Too many resend attempts. Please wait 24 hours or contact support."
6. If rate limit OK:
   • Generate new verification token (invalidate previous)
   • Send new verification email
   • Return 200 OK
   • Display: "Verification email resent successfully. Check your inbox and spam folder."
7. User checks spam/junk folder if still not received
8. User contacts support if email persistently not received
9. Administrator can investigate email logs and manually verify user

Alt Flow 4: Invalid or Malformed Token

Steps:

1. User receives or clicks on malformed verification link (corrupted, incomplete, etc.)
2. Web UI extracts token parameter
3. API receives invalid token format
4. System validates token format (GUID expected):
   • If format invalid: Return 400 Bad Request
   • If format valid: Query database
5. If token not found in database:
   • Return 404 Not Found
   • Message: "Verification link is invalid or has expired"
6. Web UI displays error message and "Resend Verification Email" option
7. User requests resend and receives new valid link

Alt Flow 5: Admin Manual Verification

Steps:

1. Administrator identifies user needing manual verification (support ticket, email delivery issue, etc.)
2. Administrator logs into admin panel
3. Administrator searches for trial user by email
4. System displays user details showing EmailVerified: false
5. Administrator clicks "Verify Email Manually" button
6. System prompts for confirmation: "Manually verify this user's email? They will receive credentials immediately."
7. Administrator confirms action
8. System validates admin has appropriate permissions
9. System updates user record:
   • EmailVerified = true
   • VerifiedAt = Current timestamp
   • VerificationMethod = "Manual"
   • VerifiedByAdminId = Admin ID
10. System sends welcome email with credentials
11. System logs admin action in audit trail
12. System displays success message to administrator
13. User receives credentials and can login

Alt Flow 6: Rate Limit Exceeded on Resend

Steps:

1. User attempts to resend verification email for 4th time within 24 hours
2. System queries verification email send history from database
3. System counts resend attempts in past 24 hours
4. System detects rate limit violation (3 attempts already made)
5. System returns 429 Too Many Requests
6. Response includes:
   • Error code: RateLimitExceeded
   • Message: "You have reached the maximum number of verification email resend attempts (3) for today."
   • RetryAfter header with seconds until rate limit resets
7. Web UI displays error message
8. Web UI provides support contact information
9. User options:
   • Wait for 24-hour rate limit reset
   • Contact support for manual verification
   • Check spam folder again

Alt Flow 7: Trial Expired During Verification Delay

Steps:

1. User registered but didn't verify email for extended period
2. Trial expiration date passes (e.g., 30 days from registration)
3. User finally clicks verification link
4. System validates token (still within 24-hour token expiration from last resend)
5. System checks trial expiration status
6. System detects trial has expired
7. Business rule applied based on configuration:
   • Option A (Lenient): Auto-extend trial by 30 days, send welcome email
   • Option B (Strict): Reject verification, display "Trial expired" message
8. If Option A:
   • Mark email as verified
   • Update TrialExpirationDate = Current date + 30 days
   • Send welcome email noting trial extension
   • Log extension in audit trail
9. If Option B:
   • Return error message
   • Provide contact information for sales/support
   • User must request trial extension or upgrade

Business Rules

Data Requirements

Note: For complete TrialUser data model including inheritance structure, see UC-001 Data Requirements section.

Email Verification Token Record

{
  "Id": "uuid-v4",
  "TrialUserId": "uuid-v4 (foreign key)",
  "Token": "uuid-v4 (unique, indexed)",
  "CreatedAt": "datetime (UTC)",
  "ExpiresAt": "datetime (UTC, CreatedAt + 24h)",
  "IsUsed": "boolean (default: false)",
  "UsedAt": "datetime (UTC, nullable)",
  "IpAddress": "string (optional, for security audit)",
  "UserAgent": "string (optional, for security audit)"
}

Trial User Record Updates

{
  "EmailVerified": "boolean (default: false)",
  "VerifiedAt": "datetime (UTC, nullable)",
  "VerificationMethod": "string ('Email' | 'Manual', nullable)",
  "VerifiedByAdminId": "uuid-v4 (nullable, foreign key to admin user)"
}

Verification Email Send History

{
  "Id": "uuid-v4",
  "TrialUserId": "uuid-v4 (foreign key)",
  "SentAt": "datetime (UTC)",
  "EmailAddress": "string",
  "TokenId": "uuid-v4 (foreign key)",
  "DeliveryStatus": "string ('Sent' | 'Delivered' | 'Failed')",
  "FailureReason": "string (nullable)"
}

Email Templates

• Verification Email:

  • Subject: "Verify Your Riptide Trial Account"
  • Body includes:
    • Verification link/button
    • Token expiration notice (24 hours)
    • What happens after verification
    • Resend instructions
    • Support contact

• Welcome Email (Post-Verification):

  • Subject: "Your Riptide Trial is Ready"
  • Body includes:
    • Congratulations message
    • Login token
    • API token
    • Application links
    • Trial expiration date
    • Getting started guide
    • Support contact

• Verification Link Expired Email:

  • Subject: "Your Verification Link Has Expired"
  • Body includes:
    • Explanation of expiration
    • New verification link/button
    • Reminder of 24-hour validity
    • Support contact

User Interface

Verification Pending Screen

┌─────────────────────────────────────────────────────┐
│  📧 Verify Your Email Address                       │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Thank you for registering for a Riptide trial!    │
│                                                     │
│  We've sent a verification email to:                │
│                                                     │
│     john.doe@example.com                           │
│                                                     │
│  Please check your inbox and click the             │
│  verification link to activate your account.       │
│                                                     │
│  ⏰ The verification link expires in 24 hours.      │
│                                                     │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Didn't receive the email?                          │
│                                                     │
│  • Check your spam or junk folder                   │
│  • Wait a few minutes for delivery                  │
│  • Ensure john.doe@example.com is correct          │
│                                                     │
│  ┌─────────────────────────────┐                   │
│  │  Resend Verification Email   │                  │
│  └─────────────────────────────┘                   │
│                                                     │
│  Need help? Contact support@riptide.com            │
└─────────────────────────────────────────────────────┘

Verification Success Screen

┌─────────────────────────────────────────────────────┐
│  ✅ Email Verified Successfully!                    │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Your email address has been verified.              │
│                                                     │
│  📧 An email with your login credentials has been   │
│     sent to:                                        │
│                                                     │
│     john.doe@example.com                           │
│                                                     │
│  The email contains:                                │
│     • Your login token                              │
│     • Your API token                                │
│     • Links to access applications                  │
│     • Getting started guide                         │
│                                                     │
│  ⏰ Trial Duration: 30 days                         │
│  📅 Expires: February 29, 2026                      │
│                                                     │
│  ┌─────────────────────┐                           │
│  │   Go to Login        │                          │
│  └─────────────────────┘                           │
│                                                     │
└─────────────────────────────────────────────────────┘

Token Expired Screen

┌─────────────────────────────────────────────────────┐
│  ⚠️  Verification Link Expired                      │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  This verification link has expired.                │
│  Verification links are valid for 24 hours.         │
│                                                     │
│  Don't worry! You can request a new verification    │
│  link below.                                        │
│                                                     │
│  Email address: john.doe@example.com               │
│                                                     │
│  ┌──────────────────────────────┐                  │
│  │  Send New Verification Email │                  │
│  └──────────────────────────────┘                  │
│                                                     │
│  Need help? Contact support@riptide.com            │
└─────────────────────────────────────────────────────┘

Rate Limit Exceeded Screen

┌─────────────────────────────────────────────────────┐
│  ⛔ Too Many Requests                               │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  You have reached the maximum number of             │
│  verification email resend attempts.                │
│                                                     │
│  Limit: 3 resends per 24 hours                      │
│  Retry after: 18 hours 32 minutes                   │
│                                                     │
│  If you're having trouble receiving emails:         │
│                                                     │
│  1. Check your spam/junk folder                     │
│  2. Add noreply@riptide.com to contacts            │
│  3. Contact support for assistance                  │
│                                                     │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  📧 Email: support@riptide.com                      │
│  💬 Chat: Available 9 AM - 5 PM EST                │
│                                                     │
└─────────────────────────────────────────────────────┘

Admin Manual Verification Interface

┌─────────────────────────────────────────────────────┐
│  Admin Panel - Trial User Details                  │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  User ID: 550e8400-e29b-41d4-a716-446655440000     │
│  Name: John Doe                                     │
│  Email: john.doe@example.com                       │
│  Company: Acme Corporation                          │
│                                                     │
│  Status                                             │
│  • Registration: January 28, 2026 10:30 AM         │
│  • Email Verified: ❌ No                            │
│  • Trial Expires: February 27, 2026                │
│  • Last Login: Never                                │
│                                                     │
│  Verification History                               │
│  • Emails sent: 3                                   │
│  • Last sent: January 29, 2026 2:15 PM            │
│  • Delivery status: Delivered                       │
│  • Link clicked: No                                 │
│                                                     │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Admin Actions                                      │
│                                                     │
│  ┌──────────────────────────┐                      │
│  │  Verify Email Manually    │  ⚠️ This will send │
│  └──────────────────────────┘     credentials     │
│                                                     │
│  ┌──────────────────────────┐                      │
│  │  Resend Verification      │                     │
│  └──────────────────────────┘                      │
│                                                     │
│  ┌──────────────────────────┐                      │
│  │  View Email Logs          │                     │
│  └──────────────────────────┘                      │
│                                                     │
└─────────────────────────────────────────────────────┘

API Endpoints

Verify Email

Endpoint: POST /api/v1/trial-users/verify-email

Authentication: None (public endpoint, token-based verification)

Request Body:

{
  "token": "550e8400-e29b-41d4-a716-446655440000"
}

Success Response: 200 OK

{
  "success": true,
  "message": "Email verified successfully. Check your email for login credentials.",
  "user": {
    "id": "750e8400-e29b-41d4-a716-446655440001",
    "email": "john.doe@example.com",
    "emailVerified": true,
    "verifiedAt": "2026-01-30T14:25:00Z"
  }
}

Error Responses:

400 Bad Request - Token expired

{
  "error": "VerificationTokenExpired",
  "message": "This verification link has expired. Verification links are valid for 24 hours.",
  "canResend": true,
  "email": "john.doe@example.com"
}

400 Bad Request - Already verified

{
  "error": "AlreadyVerified",
  "message": "This email address has already been verified. You can login now.",
  "verifiedAt": "2026-01-29T10:30:00Z"
}

404 Not Found - Token not found

{
  "error": "TokenNotFound",
  "message": "Invalid verification link. Please request a new verification email.",
  "canResend": true
}

Resend Verification Email

Endpoint: POST /api/v1/trial-users/resend-verification

Authentication: None (public endpoint, email-based)

Request Body:

{
  "email": "john.doe@example.com"
}

Success Response: 200 OK

{
  "success": true,
  "message": "Verification email sent successfully. Please check your inbox.",
  "email": "john.doe@example.com",
  "expiresAt": "2026-01-31T14:30:00Z",
  "resendCount": 2,
  "maxResends": 3,
  "retryAfter": null
}

Error Responses:

429 Too Many Requests - Rate limit exceeded

{
  "error": "RateLimitExceeded",
  "message": "Maximum resend attempts (3) reached for today. Please try again in 18 hours.",
  "retryAfter": 64800,
  "supportEmail": "support@riptide.com"
}

400 Bad Request - Email already verified

{
  "error": "AlreadyVerified",
  "message": "This email address is already verified. You can login now."
}

404 Not Found - Email not found

{
  "error": "EmailNotFound",
  "message": "No trial user found with this email address."
}

Admin Manual Verification

Endpoint: POST /api/v1/admin/trial-users/{userId}/verify-email

Authentication: Required (Admin role)

Request Body:

{
  "reason": "User reported email delivery issues. Verified via phone.",
  "sendWelcomeEmail": true
}

Success Response: 200 OK

{
  "success": true,
  "message": "User email verified manually by administrator.",
  "user": {
    "id": "750e8400-e29b-41d4-a716-446655440001",
    "email": "john.doe@example.com",
    "emailVerified": true,
    "verifiedAt": "2026-01-30T15:00:00Z",
    "verificationMethod": "Manual",
    "verifiedByAdminId": "admin-550e8400-e29b-41d4-a716-446655440002"
  },
  "welcomeEmailSent": true
}

Error Responses:

403 Forbidden - Insufficient permissions

{
  "error": "Forbidden",
  "message": "You do not have permission to manually verify users."
}

400 Bad Request - Already verified

{
  "error": "AlreadyVerified",
  "message": "This user's email is already verified.",
  "verifiedAt": "2026-01-29T10:30:00Z"
}

Get Verification Status

Endpoint: GET /api/v1/trial-users/verification-status

Authentication: None (email-based query)

Query Parameters:

• email (required): Email address to check

Success Response: 200 OK

{
  "email": "john.doe@example.com",
  "emailVerified": false,
  "verificationEmailsSent": 2,
  "lastVerificationEmailSentAt": "2026-01-30T10:00:00Z",
  "canResend": true,
  "retryAfter": null,
  "trialStatus": "Active",
  "trialExpiresAt": "2026-02-29T10:30:00Z"
}

Performance Requirements

Security Considerations

Token Security

• Verification tokens must be cryptographically secure UUIDs (v4)
• Tokens generated using System.Security.Cryptography.RandomNumberGenerator
• Tokens must be unique across all users
• Tokens stored with secure hash in database (optional)
• Tokens transmitted only via HTTPS
• Tokens included in email links (not in subject/preview)
• Tokens automatically invalidated after use
• Expired tokens cannot be reused

Email Security

• Verification emails sent via TLS/SSL
• Email content does not include sensitive credentials (only after verification)
• Verification links use HTTPS protocol
• Domain validation for email callback URLs
• DKIM/SPF/DMARC configured for email domain
• Unsubscribe link not included (transactional email)

Rate Limiting

• Maximum 3 resend requests per email per 24 hours
• Minimum 2 minutes between resend requests
• Rate limiting by email address (not IP, to handle shared IPs)
• Rate limit counters reset after 24 hours
• Admin actions exempt from rate limiting

Brute Force Protection

• No public endpoint to enumerate valid tokens
• Token lookup failures logged but not counted for rate limiting
• Failed verification attempts monitored for abuse patterns
• Suspicious activity alerts administrators

Privacy Considerations

• Email addresses not exposed in error messages
• Verification status not publicly queryable without email
• Admin actions logged in audit trail
• User consent implied by registration action
• GDPR compliance: user can request account deletion

Testing Scenarios

Test Case 1: Successful Email Verification

Given: User registered with verification enabled, email sent
When: User clicks valid verification link within 24 hours
Then: Email marked as verified, welcome email sent, 200 OK returned
Verify: EmailVerified = true, VerifiedAt set, token marked as used, credentials delivered

Test Case 2: Expired Token Handling

Given: User registered 25 hours ago, hasn't verified
When: User clicks original verification link
Then: 400 Bad Request returned with "Token expired" message
Verify: EmailVerified still false, resend option displayed, no credentials sent

Test Case 3: Duplicate Verification Attempt

Given: User already verified email successfully
When: User clicks verification link again
Then: 200 OK returned with "Already verified" message
Verify: No duplicate welcome email sent, login button displayed

Test Case 4: Resend Verification Within Rate Limit

Given: User has sent 2 verification emails today
When: User requests third resend
Then: New verification email sent, 200 OK returned
Verify: New token generated, old token invalidated, email delivered

Test Case 5: Resend Verification Exceeds Rate Limit

Given: User has already sent 3 verification emails today
When: User attempts fourth resend
Then: 429 Too Many Requests returned
Verify: No email sent, rate limit message displayed, retry time shown

Test Case 6: Invalid Token Format

Given: User clicks malformed verification link
When: System receives non-GUID token
Then: 400 Bad Request returned
Verify: No database lookup attempted, error logged

Test Case 7: Token Not Found in Database

Given: User clicks link with valid GUID not in database
When: System queries for token
Then: 404 Not Found returned
Verify: Generic error message, resend option offered

Test Case 8: Admin Manual Verification

Given: Administrator identified user needing manual verification
When: Admin clicks "Verify Manually" in admin panel
Then: Email marked as verified, welcome email sent, audit logged
Verify: VerificationMethod = "Manual", VerifiedByAdminId set, credentials delivered

Test Case 9: Verification Email Delivery Failure

Given: Email service unavailable during resend
When: System attempts to send verification email
Then: Email failure logged, user notified
Verify: Token still generated, delivery retried later or admin notified

Test Case 10: Concurrent Verification Attempts

Given: User clicks verification link from two different browsers simultaneously
When: Both requests process at same time
Then: Only one succeeds, other gets "Already verified"
Verify: No duplicate welcome emails, database transaction prevents race condition

Test Case 11: Trial Expired Before Verification

Given: User registered 31 days ago, never verified (trial duration 30 days)
When: User finally clicks verification link
Then: Based on policy: either extend trial or reject with "Trial expired"
Verify: Configured business rule applied consistently

Test Case 12: Unverified User Login Attempt

Given: User registered but hasn't verified email
When: User attempts to login with credentials
Then: Login rejected with "Email verification required"
Verify: Session not created, verification reminder displayed

Monitoring and Analytics

Key Metrics to Track

• Verification Rate: Users verified / Total registrations (%)
• Verification Time: Average time from registration to verification
• Token Expiration Rate: Expired tokens / Total tokens issued (%)
• Resend Request Rate: Resend requests / Total verifications sent
• Email Delivery Rate: Emails delivered / Emails sent (%)
• Verification Link Click Rate: Links clicked / Emails delivered (%)
• Manual Verification Rate: Manual verifications / Total verifications (%)
• Rate Limit Hit Rate: Rate limit errors / Total resend requests (%)

Performance Dashboards

• Real-time verification processing times
• Email delivery latency tracking
• Token validation response times
• Database query performance for verification lookups
• API endpoint health (verify, resend, status check)

Alerts

• Verification success rate < 70% in 24 hours
• Email delivery failure rate > 10% in 1 hour
• Token validation errors spike (> 50/hour)
• Rate limit hits spike (> 100/hour)
• Average verification time > 48 hours
• Manual verification rate > 20% (indicates systemic email issue)
• Database connection failures during verification
• Abnormal resend request patterns (potential abuse)

Email Service Monitoring

• SMTP connection health
• Email bounce rate tracking
• Spam complaint monitoring
• Email open rates (verification and welcome emails)
• Link click-through rates
• Email service provider status

Configuration Options

Application Settings

{
  "EmailVerification": {
    "Enabled": true,
    "TokenExpirationHours": 24,
    "MaxResendsPerDay": 3,
    "MinResendIntervalMinutes": 2,
    "AllowLoginWithoutVerification": false,
    "ExtendTrialOnLateVerification": true,
    "ExtensionDays": 30,
    "AutoCleanupExpiredTokensDays": 7
  },
  "Email": {
    "FromAddress": "noreply@riptide.com",
    "FromName": "Riptide Platform",
    "VerificationEmailTemplate": "trial-verification",
    "WelcomeEmailTemplate": "trial-welcome",
    "Provider": "AWSSES"
  },
  "RateLimiting": {
    "VerificationResend": {
      "Limit": 3,
      "PeriodHours": 24,
      "MinIntervalMinutes": 2
    }
  }
}

Feature Flags

• RequireEmailVerification: Enable/disable verification requirement
• AllowAdminManualVerification: Allow administrators to bypass verification
• SendVerificationReminders: Send reminder emails after 24/48 hours
• ExtendExpiredTrialsOnVerification: Auto-extend trials for late verifications

Integration Points

Email Service Integration

• AWS SES for production email delivery
• SMTP fallback for development/testing
• Email template management system
• Email delivery status webhooks (bounces, opens, clicks)
• Email queue for reliability

Database Integration

• Trial user table updates (EmailVerified flag)
• Verification token table management
• Email send history logging
• Audit trail integration

Admin Panel Integration

• User search and detail view
• Manual verification controls
• Email history display
• Rate limit override capability

Session Management Integration

• Login endpoint checks EmailVerified flag
• Unverified users blocked from session creation
• Error messages prompt verification

Related Use Cases

• UC-001: Trial User Self-Registration (triggers verification)
• UC-002: Trial User Login and Session Management (checks verification status)
• UC-005: Administrator Trial User Management (manual verification)
• UC-013: Email Notification Service (sends verification and welcome emails)
• UC-014: Rate Limiting and Abuse Prevention
• UC-015: Audit Trail and Logging

Notes and Assumptions

1. Optional Feature: Email verification can be disabled via configuration; if disabled, welcome email sent immediately
2. Token Format: GUIDs (v4) used for verification tokens to ensure uniqueness and security
3. Single Token Policy: Only one active verification token per user at a time; resend invalidates previous token
4. Email Provider: Assumes reliable email service (AWS SES or SMTP) with delivery tracking
5. No SMS Verification: Email-only verification; SMS/2FA out of scope for trial users
6. Trial Extension Logic: Configurable whether late verifications extend trial period
7. No Password Reset During Verification: Password reset requires separate flow (post-verification)
8. Link Format: Verification links are GET requests redirecting to POST API calls
9. Internationalization: Currently English-only; multi-language support is future enhancement
10. Mobile Optimization: Verification emails and pages are mobile-responsive

Revision History

Document Owner: Platform Architecture Team
Stakeholders: Product Management, Engineering, Customer Success, Security Team
Review Cycle: Quarterly or as needed for major changes