User Invitations & Management

The User Invitations & Management submodule handles user invitation workflows, account-user associations, invitation management, and user permission operations within account contexts.

API Endpoints Overview

Method	Endpoint	Description
POST	/v1/accounts/invite	Invite user to create sub-account
GET	/v1/accounts/accept-invite	Accept account invitation
POST	/v1/accounts/:id/invite	Send invitation by account ID
DELETE	/v1/accounts/:id/cancel-invite	Cancel invitation by account ID
PUT	/v1/accounts/:id/updateownerinfo	Update account owner information

MongoDB Collections Used

Primary Collections

• _accounts - Account records with invitation tokens and status
• _users - User records with account associations and permissions
• crm.contacts - Business contacts for invitation targeting
• queues - Background processing queues for bulk invitations

User Invitation Workflows

Sub-Account Invitation Flow

graph TD
    A[Select Business Contact] --> B[Generate Invitation Token]
    B --> C[Create Sub-Account Record]
    C --> D[Create User with Reset Token]
    D --> E[Send Invitation Email]
    E --> F[User Accepts Invitation]
    F --> G[Redirect to Password Setup]
    G --> H[Account Activation Complete]

Bulk Invitation Processing Flow

graph TD
    A[CSV Upload] --> B[Validate CSV Data]
    B --> C[Queue Processing]
    C --> D[Process Each Invitation]
    D --> E[Create Account Records]
    E --> F[Generate Invitation Tokens]
    F --> G[Send Batch Emails]
    G --> H[Update Processing Status]

Invitation Management Flow

graph TD
    A[Invitation Request] --> B[Validate Business Availability]
    B --> C{User Only Mode?}
    C -->|Yes| D[Add User to Existing Account]
    C -->|No| E[Create New Sub-Account]
    D --> F[Generate User Token]
    E --> F
    F --> G[Send Customized Email]
    G --> H[Track Invitation Status]

Service Methods & Functionality

Core Invitation Services

invite() - User invitation workflow

• Creates sub-accounts and sends invitation emails to users
• Handles both business invitation and user-only invitation flows
• Validates business availability and prevents duplicate invitations
• Manages CSV bulk invitation processing through queue system
• Creates user records with invitation tokens and reset capabilities
• Sends customized invitation emails with account-specific branding
• Returns invitation status and user information with detailed messaging

acceptInvite() - Invitation acceptance

• Processes invitation token acceptance and validation
• Redirects users to appropriate signup or login flows based on token status
• Handles invitation validation and account activation workflows
• Manages token expiration and error handling with proper redirects

Invitation Management Services

accountInviteById() / cancelInviteById() - Invitation management by ID

• accountInviteById(): Sends invitation emails for specific account IDs with validation
• cancelInviteById(): Cancels pending invitations and removes invitation tokens
• Handles invitation status management and user notification workflows
• Validates account ownership and permissions for invitation operations
• Returns invitation status and user information for tracking

Owner & User Management Services

updateOwnerInfo() - Owner information management

• Updates account owner contact information and profile data
• Handles owner email changes with validation and verification processes
• Manages owner profile updates with proper authorization and security
• Supports database transactions for critical owner information updates
• Returns updated owner information confirmation with status messages

Technical Implementation Details

Invitation Security

• JWT Token Security: Secure token generation with expiration handling for invitations
• Permission Validation: Owner-only permissions for sensitive invitation operations
• Business Validation: Prevents duplicate invitations and validates business availability
• Token Management: Proper token lifecycle management with cleanup procedures

Email Integration

• Branded Templates: Customizable invitation emails with account-specific branding
• SendGrid Integration: Reliable email delivery with template management
• Dynamic Content: Personalized invitation content with sender and recipient information
• Error Handling: Comprehensive error handling for email delivery failures

Bulk Processing

• Queue System: Background processing for large invitation batches
• CSV Processing: Structured CSV import with field mapping and validation
• Batch Operations: Efficient bulk invitation processing with status tracking
• Progress Monitoring: Real-time processing status and completion notifications

Business Logic Implementation

Invitation Validation Workflow

1. Business Availability Check: Validate business hasn't been previously invited
2. User Permission Validation: Ensure requesting user has invitation privileges
3. Account Relationship Validation: Verify parent-child account relationships
4. Duplicate Prevention: Check for existing invitations or accounts
5. User Creation: Create user records with proper tokens and permissions
6. Email Delivery: Send customized invitation emails with tracking
7. Status Management: Update invitation status and provide user feedback

Token Management Workflow

1. JWT Generation: Create secure invitation tokens with expiration
2. Token Storage: Store tokens in account records for validation
3. Acceptance Processing: Validate tokens and process acceptance
4. Cleanup Operations: Remove expired or cancelled tokens
5. Security Validation: Ensure token integrity and prevent tampering
6. Redirect Handling: Proper redirect flows based on token status

Key Features

Comprehensive Invitation System

• Multiple Invitation Types: Support for business and user-only invitations
• Bulk Processing: CSV-based bulk invitation processing with queue management
• Token Security: Secure JWT-based invitation token system
• Email Customization: Branded invitation emails with dynamic content

Advanced User Management

• Owner Management: Comprehensive owner information and contact management
• Permission System: Role-based permission management for invitation operations
• Account Association: Flexible user-account relationship management
• Status Tracking: Complete invitation lifecycle and status monitoring

Integration Capabilities

• Business Integration: Seamless integration with business contact management
• Queue Processing: Background job processing for scalable operations
• Email Service: Reliable email delivery with template customization
• Status Monitoring: Real-time invitation status and processing updates

Security & Validation

• Access Control: Owner-only permissions for sensitive operations
• Duplicate Prevention: Comprehensive validation to prevent duplicate invitations
• Token Security: Secure token generation and validation with expiration
• Error Handling: Robust error handling with user-friendly messaging