​

User Management API

​

Base URL

​

Authentication

Authorization: Bearer YOUR_TOKEN

• USER_LOOKUP - For internal user lookups and email existence checks
• FETCH_CONFIG - For configuration updates

​

Architecture Overview

• Authentication Service - Validates user credentials and authentication methods
• Mail Service - Sends invitations and notifications via SMTP
• Configuration Manager - Manages application settings and SMTP configuration
• Event Service - Publishes entity lifecycle events via Kafka
• AI Connector Backend - Handles teams and graph-based user operations
• Prometheus Service - Records metrics and activities

​

Data Models

​

Organizations

• Organization metadata and settings
• Account types (individual/business)
• Onboarding status tracking
• Logo management with automatic compression

​

Users

• Profile information and contact details
• Authentication status and login history
• Organization membership and roles
• Display picture management with automatic compression

​

User Groups

• Predefined types: admin, standard, everyone, custom
• User membership management
• Permission inheritance
• System-managed groups cannot be deleted

​

Teams

• Team metadata and descriptions
• User membership with permissions
• External system integration via AI connector service

​

API Endpoints

{
  "accountType": "business",
  "contactEmail": "admin@example.com",
  "registeredName": "Example Corporation",
  "shortName": "ExampleCorp",
  "adminFullName": "John Administrator",
  "password": "SecurePass123!",
  "sendEmail": true,
  "phoneNumber": "+1-555-123-4567",
  "permanentAddress": {
    "addressLine1": "123 Business Ave",
    "city": "Tech City",
    "state": "Innovation State",
    "country": "United States",
    "postCode": "12345"
  }
}

{
  "contactEmail": "new-admin@example.com",
  "shortName": "NewExampleCorp",
  "permanentAddress": {
    "addressLine1": "456 New Street",
    "city": "Updated City",
    "state": "New State",
    "country": "United States",
    "postCode": "67890"
  }
}

{
  "status": "configured"
}

{
  "userIds": [
    "60d21b4667d0d8992e610c86",
    "60d21b4667d0d8992e610c87"
  ]
}

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

{
  "fullName": "Alice Johnson",
  "email": "alice.johnson@example.com",
  "mobile": "+12345678902",
  "designation": "Product Manager"
}

{
  "fullName": "Alice Marie Johnson"
}

{
  "firstName": "Alexandra"
}

{
  "lastName": "Smith-Johnson"
}

{
  "designation": "VP of Product"
}

{
  "email": "alice.smith-johnson@example.com"
}

{
  "fullName": "Alice Johnson",
  "email": "alice.johnson@example.com",
  "designation": "Senior Product Manager",
  "firstName": "Alice",
  "lastName": "Johnson",
  "address": {
    "addressLine1": "456 Oak Street",
    "city": "New York",
    "state": "NY",
    "postCode": "10001",
    "country": "US"
  }
}

{
  "emails": [
    "new.user1@example.com",
    "new.user2@example.com",
    "existing.deleted.user@example.com"
  ],
  "groupIds": [
    "60d21b4667d0d8992e610c89",
    "60d21b4667d0d8992e610c90"
  ]
}

{
  "name": "Developers",
  "type": "custom"
}

{
  "name": "Senior Developers"
}

{
  "userIds": [
    "60d21b4667d0d8992e610c86",
    "60d21b4667d0d8992e610c87"
  ],
  "groupIds": [
    "60d21b4667d0d8992e610c91",
    "60d21b4667d0d8992e610c92"
  ]
}

{
  "userIds": [
    "60d21b4667d0d8992e610c86"
  ],
  "groupIds": [
    "60d21b4667d0d8992e610c91"
  ]
}

{
  "name": "Product Development Team",
  "description": "Responsible for product development and roadmap",
  "userIds": [
    "60d21b4667d0d8992e610c86",
    "60d21b4667d0d8992e610c87"
  ],
  "role": "member"
}

{
  "name": "Advanced Product Development Team",
  "description": "Leading product innovation and development"
}

{
  "userIds": [
    "60d21b4667d0d8992e610c88",
    "60d21b4667d0d8992e610c89"
  ]
}

{
  "userIds": [
    "60d21b4667d0d8992e610c88"
  ]
}

{
  "userIds": [
    "60d21b4667d0d8992e610c87"
  ],
  "role": "lead"
}

​

Schema Definitions

interface IOrg extends Document {
  slug: string;                    // Auto-generated: "org-{counter}"
  registeredName: string;          // Required for business accounts with validation
  shortName?: string;              // Optional display name
  domain: string;                  // Extracted from contactEmail, required
  contactEmail: string;            // Required, lowercase, becomes admin email
  accountType: 'individual' | 'business';  // Required enum
  phoneNumber?: string;
  permanentAddress?: Address;      // Optional address object
  isDeleted: boolean;              // Default: false, soft delete flag
  deletedByUser?: string;
  onBoardingStatus: 'configured' | 'notConfigured' | 'skipped';  // Required enum
  // Timestamps added automatically
  createdAt?: Date;
  updatedAt?: Date;
}

interface Address {
  addressLine1?: string;
  city?: string;
  state?: string;
  postCode?: string;
  country?: string;               // Validated against jurisdictions enum
}

// Validation function for business accounts
const orgSchemaValidation = (data) => {
  if (data.accountType === 'business') {
    return !!data.registeredName;
  }
  return true;
};

​

Validation Schemas

// Create User Validation
const createUserBody = z.object({
  fullName: z.string().min(1, 'Full name is required'),
  email: z.string().email('Invalid email'),
  mobile: z.string().optional().refine((val) => 
    !val || /^\+?[0-9]{10,15}$/.test(val), {
    message: 'Invalid mobile number'
  }),
  designation: z.string().optional(),
});

// Update User Validation (comprehensive)
const updateUserBody = z.object({
  fullName: z.string().optional(),
  email: z.string().email('Invalid email'),  // Required field
  mobile: z.string().optional().refine((val) => 
    !val || /^\+?[0-9]{10,15}$/.test(val), {
    message: 'Invalid mobile number'
  }),
  designation: z.string().optional(),
  firstName: z.string().optional(),
  lastName: z.string().optional(),
  address: z.object({
    addressLine1: z.string().optional(),
    city: z.string().optional(),
    state: z.string().optional(),
    postCode: z.string().optional(),
    country: z.string().optional(),
  }).optional(),
  hasLoggedIn: z.boolean().optional(),
});

// Specific field updates
const updateFullNameBody = z.object({
  fullName: z.string().min(1, 'fullName must have at least one character'),
});

const updateFirstNameBody = z.object({
  firstName: z.string().min(1, 'firstName is required'),
});

// MongoDB ObjectId validation
const UserIdUrlParams = z.object({
  id: z.string().regex(/^[a-fA-F0-9]{24}$/, 'Invalid UserId'),
});

// Multiple users validation
const MultipleUserBody = z.object({
  userIds: z.array(
    z.string().regex(/^[a-fA-F0-9]{24}$/, 'Invalid MongoDB ObjectId')
  ).min(1, 'At least one userId is required'),
});

​

Error Handling

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": "Email is required and must be a valid email address"
  },
  "timestamp": "2025-04-27T13:20:00.000Z",
  "path": "/users",
  "method": "POST"
}

• VALIDATION_ERROR - Invalid request parameters
• NOT_FOUND - Resource not found
• UNAUTHORIZED - Authentication required
• FORBIDDEN - Insufficient privileges
• BAD_REQUEST - Invalid operation
• INTERNAL_ERROR - Server error

• 200 - Success
• 201 - Created
• 400 - Bad Request (validation errors)
• 401 - Unauthorized
• 403 - Forbidden (insufficient privileges)
• 404 - Not Found
• 500 - Internal Server Error

​

Important Notes

1. Route Paths: All route paths shown are relative to how the routers are mounted in the main application
2. MongoDB ObjectIds: All ID fields use 24-character hexadecimal strings matching /^[a-fA-F0-9]{24}$/
3. Soft Deletes: Users, organizations, and groups use soft deletion (isDeleted: true) rather than physical removal
4. Admin Restrictions:
   • Admin users cannot be deleted (checked via group membership)
   • Only custom user groups can be deleted (admin, everyone, standard are protected)
5. SMTP Dependencies: Email features require valid SMTP configuration checked via Configuration Manager service
6. Account Type Restrictions:
   • Bulk user invitations limited to business accounts
   • Individual accounts have restricted functionality
7. Automatic Group Memberships:
   • All users automatically added to “everyone” group
   • Admin users added to “admin” group during organization creation
8. Image Processing:
   • Uploaded images automatically compressed using Sharp library
   • Converted to JPEG format with dynamic quality adjustment
   • Target size: under 100KB after compression
9. Event Publishing:
   • All entity changes publish events via Kafka for system integration
   • Events include organization and user lifecycle changes
10. Transaction Support:
    • Uses MongoDB transactions when replica sets available
    • Falls back to individual operations for single-node deployments
11. Teams Functionality:
    • All teams operations are proxied to AI connector backend
    • Routes forward requests to ${config.connectorBackend}/api/v1/entity/team/*
    • Error handling returns appropriate responses for failed backend calls
    • Response formats depend entirely on connector backend implementation
12. Unique Constraints:
    • Email addresses must be unique across the system
    • Group names must be unique within organization
    • Slugs auto-generated with counter-based uniqueness
13. Middleware Processing:
    • FileProcessorFactory methods return arrays that are spread into middleware chains
    • Validation schemas include complete request structure (body, query, params, headers)
14. Service Integration:
    • Configuration updates dynamically rebind services in dependency injection container
    • Health endpoints available on all router modules
    • Metrics recorded via Prometheus service for monitoring
15. Access Control:
    • Scoped tokens for service-to-service communication (USER_LOOKUP, FETCH_CONFIG)
    • Role-based access through user group membership
    • Admin-only operations clearly enforced through middleware
16. Duplicate User Teams Endpoints:
    • /teams/user/teams (managed by TeamsController) - Returns empty array on backend errors
    • /users/teams/list (managed by UserController) - Throws BadRequestError on backend errors
    • Both proxy to connector backend but have different error handling strategies
17. File Upload Middleware:
    • FileProcessorFactory.createBufferUploadProcessor() returns an object with getMiddleware array
    • Middleware is spread using the spread operator (...middleware.getMiddleware)
    • All uploaded images undergo automatic compression regardless of original format
18. Validation Preprocessing:
    • Query parameters for pagination are preprocessed from strings to numbers using z.preprocess()
    • Default values are applied during validation for optional pagination parameters
19. Container Integration:
    • Inversify container provides dependency injection throughout the application
    • Services are dynamically rebound when configuration updates occur
    • Container disposal handles cleanup of connections and resources
20. Email Behavior Variations:
    • Different email templates sent for new vs restored user invitations
    • Authentication method (password vs non-password) affects email content
    • SMTP configuration validation occurs before any email sending operations