User Management

User Management Overview

User management endpoints allow you to manage user accounts within your Infomaxim application. Most endpoints require admin authentication with JWT tokens.

Authentication Requirements

• Admin Routes: Require both JWT authentication and admin role (adminGuard)
• User Routes: Require only JWT authentication
• Public Routes: No authentication required

Business Logic Flow

1. User Creation: Admins create users with email, password, name, and role
2. User Retrieval: Users can view their own profile; admins can view all users
3. User Updates: Users can update their own profile; admins can update any user
4. User Deletion: Only admins can delete users

GET/users/:userId/photo

Retrieves a user's profile photo. This is a public endpoint that does not require authentication.

URL Parameters

• userId number

  The unique identifier of the user

Query Parameters

• token string

  JWT token used to verify photo access (optional)

Business Logic

• Validates the JWT token if provided
• Retrieves the photo path from the database
• Returns the photo file from the assets directory

Success Response (200 OK)

Returns the image file (binary data)

Error Response (200 OK with error)

Note: The current implementation returns HTTP 200 OK for errors, which is not RESTful best practice. Future versions should use appropriate HTTP error codes (4xx/5xx).

Client Implementation Guidance: When consuming this endpoint, always check the response body for a "status" field. If status is "Failed", treat it as an error regardless of the HTTP status code.

{
  "status": "Failed",
  "error": "Error message"
}

Common Error Scenarios

• Invalid token: JWT token verification fails
• Photo not found: User has no associated photo in database
• File system error: Photo file missing from assets directory

GET/users/test

Test endpoint to verify the user controller is functioning. This is a public diagnostic endpoint.

Authentication

None required - public endpoint

Success Response (200 OK)

<h1>User Controller</h1>

Business Logic

• Simple health check endpoint
• Returns HTML to confirm controller is loaded
• Used for debugging and verification

GET/users

Retrieves a list of all users in the application. Requires admin authentication.

Request Headers

Authorization: Bearer <admin_access_token>

Authentication Requirements

• JWT authentication (auth middleware)
• Admin role required (adminGuard middleware)

Query Parameters

• page number

  Page number for pagination (default: 1)

• perPage number

  Results per page (default: 20, max: 100)

Business Logic

• Validates admin authentication and authorization
• Queries the aurora_users table with pagination
• Maps user roles from primary_role ID to role names
• Returns user list with total count

Success Response (200 OK)

{
  "status": "Success",
  "data": {
    "users": [
      {
        "id": 123,
        "email": "user@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "role": "Administrator",
        "primary_role": 9,
        "org_id": 456,
        "work_flow": "default",
        "createdAt": "2024-01-01T12:00:00Z",
        "accessed": "2024-01-15T09:30:00Z"
      }
    ],
    "pagination": {
      "total": 150,
      "page": 1,
      "perPage": 20,
      "totalPages": 8
    }
  }
}

Error Responses

// 401 Unauthorized
{
  "status": "Failed",
  "message": "Authentication required"
}

// 403 Forbidden
{
  "status": "Failed",
  "message": "Admin access required"
}

POST/users

Creates a new user account. Requires admin authentication.

Request Headers

Authorization: Bearer <admin_access_token>
Content-Type: application/json

Authentication Requirements

• JWT authentication (auth middleware)
• Admin role required (adminGuard middleware)

Request Body

{
  "email": "newuser@example.com",
  "password": "SecurePass123!",
  "firstName": "John",
  "lastName": "Doe",
  "role": "Author",
  "primary_role": 7,
  "org_id": 456
}

Request Body Parameters

• email string required

  User's email address (must be unique)

• password string required

  User's password (will be hashed)

• firstName string required

  User's first name

• lastName string required

  User's last name

• role string

  Role name (Library, Reviewer, Guest, Author, Account Manager, Administrator, System Administrator)

• primary_role number

  Role ID (1-10, maps to role name)

• org_id number

  Organization/account ID for the user

Business Logic

• Validates admin authentication and authorization
• Checks if user with email already exists
• Hashes password before storage
• Inserts new user into aurora_users table
• Maps primary_role ID to role name
• Returns created user with error handling

Success Response (200 OK)

{
  "status": "Success",
  "data": {
    "id": 789,
    "email": "newuser@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "Author",
    "primary_role": 7,
    "org_id": 456
  }
}

Error Responses

// 409 Conflict - User already exists
{
  "status": "Failed",
  "message": "User already exists",
  "errorId": "unique-error-id"
}

// 401 Unauthorized
{
  "status": "Failed",
  "message": "Authentication required"
}

// 403 Forbidden
{
  "status": "Failed",
  "message": "Admin access required"
}

// 500 Internal Server Error
{
  "status": "Failed",
  "message": "Internal server error"
}

GET/users/current

Retrieves the currently authenticated user's profile. Any authenticated user can access this endpoint.

Request Headers

Authorization: Bearer <access_token>

Authentication Requirements

• JWT authentication (auth middleware)
• No admin role required - any authenticated user can access

Business Logic

• Validates JWT authentication
• Extracts user ID from JWT token (req.user.id)
• Queries aurora_users table by user ID
• Maps primary_role ID to role name
• Retrieves default app ID for user from aurora_sites table based on org_id
• Returns complete user profile with error handling

Success Response (200 OK)

{
  "status": "Success",
  "data": {
    "id": 123,
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "Administrator",
    "primary_role": 9,
    "org_id": 456,
    "work_flow": "default",
    "gmt": "UTC",
    "accessed": "2024-01-15T09:30:00Z",
    "appID": 789
  }
}

Error Responses

// 401 Unauthorized
{
  "status": "Failed",
  "message": "Authentication required"
}

// 404 Not Found
{
  "status": "Failed",
  "message": "User not found",
  "errorId": "unique-error-id"
}

// 500 Internal Server Error
{
  "status": "Failed",
  "message": "Internal server error"
}

PUT/users/current

Updates the currently authenticated user's profile. Requires admin authentication.

Request Headers

Authorization: Bearer <admin_access_token>
Content-Type: application/json

Authentication Requirements

• JWT authentication (auth middleware)
• Admin role required (adminGuard middleware)

Request Body

{
  "firstName": "UpdatedFirst",
  "lastName": "UpdatedLast",
  "email": "updated@example.com",
  "age": 30,
  "address": {
    "street": "123 Main St",
    "city": "City",
    "country": "Country"
  }
}

Request Body Parameters

• firstName string

  User's first name

• lastName string

  User's last name

• email string

  User's email (must be unique across all users)

• age number

  User's age (optional)

• address object

  User's address information (optional)

Business Logic

• Validates admin authentication and authorization
• Extracts user ID from JWT token (req.user.id)
• Checks for duplicate email addresses (excluding current user)
• Updates user record in database
• Generates new JWT tokens (access and refresh tokens) with updated user info
• Returns updated user profile with new tokens

Success Response (200 OK)

{
  "status": "Success",
  "data": {
    "user": {
      "id": 123,
      "email": "updated@example.com",
      "firstName": "UpdatedFirst",
      "lastName": "UpdatedLast",
      "role": "Administrator"
    },
    "accessToken": "new.jwt.token",
    "refreshToken": "new.refresh.token"
  }
}

Error Responses

// 409 Conflict - Duplicate email
{
  "status": "Failed",
  "message": "Email already in use",
  "error": {
    "code": 409,
    "field": "email",
    "type": "exist"
  }
}

// 401 Unauthorized
{
  "status": "Failed",
  "message": "Authentication required"
}

// 403 Forbidden
{
  "status": "Failed",
  "message": "Admin access required"
}

GET/users/:id

Retrieves a specific user by ID. Requires admin authentication.

Request Headers

Authorization: Bearer <admin_access_token>

Authentication Requirements

• JWT authentication (auth middleware)
• Admin role required (adminGuard middleware)

URL Parameters

• id number required

  The unique identifier of the user to retrieve

Business Logic

• Validates admin authentication and authorization
• Queries aurora_users table by user ID
• Maps primary_role ID to role name
• Retrieves default app ID for user from aurora_sites table based on org_id
• Returns complete user profile

Success Response (200 OK)

{
  "status": "Success",
  "data": {
    "id": 123,
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "Author",
    "primary_role": 7,
    "org_id": 456,
    "work_flow": "default",
    "gmt": "UTC",
    "accessed": "2024-01-15T09:30:00Z",
    "appID": 789
  }
}

Error Responses

// 401 Unauthorized
{
  "status": "Failed",
  "message": "Authentication required"
}

// 403 Forbidden
{
  "status": "Failed",
  "message": "Admin access required"
}

// 404 Not Found
{
  "status": "Failed",
  "message": "User not found"
}

PUT/users/:id

Updates a specific user's information. Requires admin authentication.

Request Headers

Authorization: Bearer <admin_access_token>
Content-Type: application/json

Authentication Requirements

• JWT authentication (auth middleware)
• Admin role required (adminGuard middleware)

URL Parameters

• id number required

  The unique identifier of the user to update

Request Body

{
  "firstName": "Updated",
  "lastName": "Name",
  "email": "updated@example.com",
  "age": 35,
  "role": "Account Manager",
  "address": {
    "street": "456 Oak Ave",
    "city": "New City"
  }
}

Request Body Parameters

• firstName string

  User's first name

• lastName string

  User's last name

• email string

  User's email (must be unique across all users)

• age number

  User's age (optional)

• role string

  User's role name (optional)

• address object

  User's address information (optional)

Business Logic

• Validates admin authentication and authorization
• Checks if user exists by ID
• Validates email uniqueness (excluding the user being updated)
• If duplicate email found with different user ID, returns 409 error
• Updates user record in database
• Maps primary_role ID to role name
• Returns updated user profile

Success Response (200 OK)

{
  "status": "Success",
  "data": {
    "id": 123,
    "email": "updated@example.com",
    "firstName": "Updated",
    "lastName": "Name",
    "role": "Account Manager",
    "age": 35,
    "address": {
      "street": "456 Oak Ave",
      "city": "New City"
    }
  }
}

Error Responses

// 409 Conflict - Duplicate email
{
  "status": "Failed",
  "message": "Email already in use",
  "error": {
    "code": 409,
    "field": "email",
    "type": "exist"
  }
}

// 401 Unauthorized
{
  "status": "Failed",
  "message": "Authentication required"
}

// 403 Forbidden
{
  "status": "Failed",
  "message": "Admin access required"
}

// 404 Not Found
{
  "status": "Failed",
  "message": "User not found"
}

DELETE/users/:id

Deletes a user account. Requires admin authentication. This is a permanent operation.

Request Headers

Authorization: Bearer <admin_access_token>

Authentication Requirements

• JWT authentication (auth middleware)
• Admin role required (adminGuard middleware)

URL Parameters

• id number required

  The unique identifier of the user to delete

Business Logic

• Validates admin authentication and authorization
• Checks if user exists by ID
• Permanently removes user record from aurora_users table
• Returns confirmation with deleted user ID

Important: Cascade Deletion Considerations

Warning: This endpoint performs a simple DELETE operation and does NOT automatically cascade to related records. Before deleting a user, consider the following cleanup:

• User Sessions: Active JWT tokens remain valid until expiration
• Created Content: Records in data tables may reference the deleted user ID
• File Uploads: User-uploaded files in the assets directory are not removed
• Audit Logs: Analytics and activity logs retain user references
• Permissions: ACL entries and folder permissions may still reference user
• Shopping Cart: E-commerce cart data for the user is not cleared

Recommended Cleanup Procedure:

1. Archive or reassign user's created content to another user
2. Clear or archive user's cart and order history
3. Revoke active sessions (consider implementing a session invalidation endpoint)
4. Update audit logs to mark user as deleted (or maintain for compliance)
5. Remove or archive user's uploaded files

Success Response (200 OK)

{
  "status": "Success",
  "data": {
    "id": 123
  }
}

Error Responses

// 401 Unauthorized
{
  "status": "Failed",
  "message": "Authentication required"
}

// 403 Forbidden
{
  "status": "Failed",
  "message": "Admin access required"
}

// 404 Not Found
{
  "status": "Failed",
  "message": "User not found"
}

// 500 Internal Server Error
{
  "status": "Failed",
  "message": "Failed to delete user"
}

Role Reference

The following roles are available in the system, mapped by primary_role ID:

1  - Library
2  - Reviewer
3  - Guest
4  - Bulk Event Author
5  - Bulk Event Author (Note: Duplicate of role 4 - appears to be legacy data)
6  - Bulk Shop Author
7  - Author
8  - Account Manager
9  - Administrator
10 - System Administrator

Note: Role IDs 4 and 5 both map to "Bulk Event Author". This appears to be a legacy configuration in the codebase that has been maintained for backward compatibility.

Role Hierarchy

• System Administrator (10): Full system access
• Administrator (9): Organization-level admin access
• Account Manager (8): Account management capabilities
• Author (7): Content creation and editing
• Bulk Shop/Event Authors (4-6): Bulk operations for specific modules
• Guest (3): Limited read access
• Reviewer (2): Review and approval capabilities
• Library (1): Basic library access

User Data Model

Users are stored in the aurora_users table with the following key fields:

Database Schema

• id number

  Primary key, unique user identifier

• user_email string

  User's email address (unique)

• first_name string

  User's first name

• last_name string

  User's last name

• primary_role number

  Role ID (1-10) - maps to role name

• org_id number

  Organization/account identifier

• work_flow string

  Workflow configuration for user

• gmt string

  User's timezone setting

• accessed datetime

  Last access timestamp

Related Tables

• aurora_sites: Linked via org_id to get user's default app
• aurora_customers: Separate table for e-commerce customers