O
Oliver

User Management API

The User Management API provides comprehensive functionality for managing user accounts, profiles, permissions, and organizational structure within the Oliver Chat system. This includes user creation, role assignment, supervisor relationships, and activity monitoring.

Enterprise Focus: User management in Oliver Chat is designed for financial services organizations with hierarchical structures, compliance requirements, and detailed audit needs.

User Management Features

👥 User Accounts

Complete user lifecycle management including creation, updates, deactivation, and detailed profile management.

🔐 Role-Based Access

Sophisticated role and permission system with individual permission overrides and group-based access control.

🏢 Organizational Structure

Supervisor-supervisee relationships, department assignments, and hierarchical reporting structures.

📊 Activity Monitoring

Detailed user activity tracking, usage analytics, and performance metrics for compliance and management.

🔍 Audit & Compliance

Complete audit trails, compliance monitoring, and regulatory reporting capabilities for user activities.

🔗 SSO Integration

Microsoft Azure AD integration, SAML support, and enterprise single sign-on capabilities.

List Users

Retrieve a paginated list of users with filtering and search capabilities.

GET /api/v1/users
Authentication: Required
Required Permissions: view_users

Query Parameters

Parameter Type Required Description
page integer No Page number (default: 1)
per_page integer No Items per page (default: 20, max: 100)
search string No Search term for name or email
role_id integer No Filter by role ID
supervisor_id integer No Filter by supervisor ID
status string No Filter by status (active, inactive, suspended)
department string No Filter by department
created_after string No Filter by creation date (ISO 8601 format)
last_login_after string No Filter by last login date (ISO 8601 format)
include string No Additional data to include (stats, permissions, supervisor)

Example Response

{
    "success": true,
    "data": {
        "users": [
            {
                "id": 123,
                "name": "John Smith",
                "email": "jsmith@advisorsassetmanagement.com",
                "status": "active",
                "role": {
                    "id": 3,
                    "name": "Financial Advisor",
                    "key": "financial_advisor"
                },
                "department": "Investment Management",
                "supervisor": {
                    "id": 45,
                    "name": "Mary Johnson",
                    "email": "mjohnson@advisorsassetmanagement.com"
                },
                "profile_image_url": "https://oliverchat.com/storage/profile-images/user_123.jpg",
                "last_login": "2025-03-11T08:30:00Z",
                "created_at": "2024-11-15T09:00:00Z",
                "login_type": "microsoft_sso",
                "stats": {
                    "total_chats": 156,
                    "total_messages": 1247,
                    "images_generated": 23,
                    "compliance_flags": 2
                }
            },
            {
                "id": 124,
                "name": "Sarah Wilson",
                "email": "swilson@advisorsassetmanagement.com",
                "status": "active",
                "role": {
                    "id": 2,
                    "name": "Compliance Officer",
                    "key": "compliance_officer"
                },
                "department": "Compliance",
                "supervisor": null,
                "profile_image_url": null,
                "last_login": "2025-03-11T07:45:00Z",
                "created_at": "2024-10-20T14:30:00Z",
                "login_type": "standard",
                "stats": {
                    "total_chats": 89,
                    "total_messages": 567,
                    "images_generated": 5,
                    "compliance_flags": 0
                }
            }
        ],
        "pagination": {
            "current_page": 1,
            "per_page": 20,
            "total": 2,
            "total_pages": 1
        },
        "summary": {
            "total_users": 2,
            "active_users": 2,
            "inactive_users": 0,
            "users_by_role": {
                "financial_advisor": 1,
                "compliance_officer": 1
            }
        }
    },
    "message": "Users retrieved successfully"
}

Create User

Create a new user account with role assignment and profile information.

POST /api/v1/users
Authentication: Required
Required Permissions: create_users

Request Parameters

Parameter Type Required Description
name string Yes User's full name (max 255 characters)
email string Yes User's email address (must be unique)
password string No Password (required if not using SSO, min 8 characters)
password_confirmation string No Password confirmation (required if password is provided)
role_id integer Yes ID of the role to assign to the user
supervisor_id integer No ID of the user's supervisor
department string No User's department
employee_id string No Employee ID or badge number
phone string No Phone number
office_location string No Office location or address
login_type string No Authentication method (standard, microsoft_sso)
send_welcome_email boolean No Send welcome email with login instructions (default: true)

Example Request

{
    "name": "Michael Davis",
    "email": "mdavis@advisorsassetmanagement.com",
    "role_id": 3,
    "supervisor_id": 45,
    "department": "Investment Management",
    "employee_id": "EMP001234",
    "phone": "+1-555-123-4567",
    "office_location": "New York Office",
    "login_type": "microsoft_sso",
    "send_welcome_email": true
}

Example Response

{
    "success": true,
    "data": {
        "user": {
            "id": 125,
            "name": "Michael Davis",
            "email": "mdavis@advisorsassetmanagement.com",
            "status": "active",
            "role": {
                "id": 3,
                "name": "Financial Advisor",
                "key": "financial_advisor"
            },
            "supervisor": {
                "id": 45,
                "name": "Mary Johnson",
                "email": "mjohnson@advisorsassetmanagement.com"
            },
            "profile": {
                "department": "Investment Management",
                "employee_id": "EMP001234",
                "phone": "+1-555-123-4567",
                "office_location": "New York Office"
            },
            "login_type": "microsoft_sso",
            "profile_image_url": null,
            "last_login": null,
            "created_at": "2025-03-11T15:30:00Z",
            "updated_at": "2025-03-11T15:30:00Z"
        }
    },
    "message": "User created successfully"
}

Get User

Get detailed information about a specific user including their profile, permissions, and activity statistics.

GET /api/v1/users/{user_id}
Authentication: Required
Required Permissions: view_users

Path Parameters

Parameter Type Required Description
user_id integer Yes ID of the user

Query Parameters

Parameter Type Required Description
include string No Additional data (stats, permissions, supervised_users, recent_activity)

Example Response

{
    "success": true,
    "data": {
        "user": {
            "id": 123,
            "name": "John Smith",
            "email": "jsmith@advisorsassetmanagement.com",
            "status": "active",
            "role": {
                "id": 3,
                "name": "Financial Advisor",
                "key": "financial_advisor"
            },
            "supervisor": {
                "id": 45,
                "name": "Mary Johnson",
                "email": "mjohnson@advisorsassetmanagement.com",
                "role": "Senior Advisor"
            },
            "profile": {
                "department": "Investment Management",
                "employee_id": "EMP001123",
                "phone": "+1-555-987-6543",
                "office_location": "Chicago Office",
                "hire_date": "2024-11-15",
                "bio": "Experienced financial advisor specializing in retirement planning"
            },
            "login_info": {
                "login_type": "microsoft_sso",
                "last_login": "2025-03-11T08:30:00Z",
                "login_count": 247,
                "failed_login_attempts": 0
            },
            "profile_image_url": "https://oliverchat.com/storage/profile-images/user_123.jpg",
            "created_at": "2024-11-15T09:00:00Z",
            "updated_at": "2025-03-10T16:45:00Z"
        },
        "stats": {
            "activity": {
                "total_chats": 156,
                "private_chats": 12,
                "total_messages": 1247,
                "images_generated": 23,
                "rag_queries": 89,
                "compliance_flags": 2,
                "resolved_flags": 2
            },
            "usage_patterns": {
                "avg_messages_per_chat": 8.2,
                "avg_session_duration_minutes": 18.5,
                "most_active_hour": 14,
                "preferred_features": ["chat", "image_generation", "rag_search"]
            },
            "recent_activity": {
                "last_chat_at": "2025-03-11T08:30:00Z",
                "last_message_at": "2025-03-11T08:35:00Z",
                "last_image_generated_at": "2025-03-10T15:20:00Z"
            }
        },
        "permissions": {
            "role_permissions": [
                "create_chats",
                "view_chats",
                "generate_images",
                "use_search",
                "use_browsing"
            ],
            "individual_permissions": [
                "access_premium_rag"
            ],
            "effective_permissions": [
                "create_chats",
                "view_chats",
                "generate_images",
                "use_search",
                "use_browsing",
                "access_premium_rag"
            ]
        },
        "supervised_users": [
            {
                "id": 126,
                "name": "Jennifer Brown",
                "email": "jbrown@advisorsassetmanagement.com",
                "role": "Junior Advisor",
                "last_login": "2025-03-11T07:15:00Z"
            }
        ]
    },
    "message": "User retrieved successfully"
}

Update User

Update a user's information, role, or profile details.

PUT /api/v1/users/{user_id}
Authentication: Required
Required Permissions: update_users

Path Parameters

Parameter Type Required Description
user_id integer Yes ID of the user to update

Request Parameters

Parameter Type Required Description
name string No User's full name
email string No User's email address
role_id integer No ID of the role to assign to the user
supervisor_id integer No ID of the user's supervisor
status string No User status (active, inactive, suspended)
department string No User's department
phone string No Phone number
office_location string No Office location
bio string No User biography or description
password string No New password (min 8 characters)
password_confirmation string No Password confirmation (required if password provided)

Example Request

{
    "name": "John P. Smith",
    "department": "Senior Investment Management",
    "phone": "+1-555-987-6544",
    "office_location": "Chicago Office - Floor 15",
    "bio": "Senior financial advisor with 15+ years experience specializing in retirement planning and wealth management"
}

Example Response

{
    "success": true,
    "data": {
        "user": {
            "id": 123,
            "name": "John P. Smith",
            "email": "jsmith@advisorsassetmanagement.com",
            "status": "active",
            "role": {
                "id": 3,
                "name": "Financial Advisor",
                "key": "financial_advisor"
            },
            "profile": {
                "department": "Senior Investment Management",
                "phone": "+1-555-987-6544",
                "office_location": "Chicago Office - Floor 15",
                "bio": "Senior financial advisor with 15+ years experience specializing in retirement planning and wealth management"
            },
            "updated_at": "2025-03-11T15:45:00Z"
        }
    },
    "message": "User updated successfully"
}

Deactivate User

Deactivate a user account (users are not permanently deleted for audit compliance).

DELETE /api/v1/users/{user_id}
Authentication: Required
Required Permissions: delete_users

Path Parameters

Parameter Type Required Description
user_id integer Yes ID of the user to deactivate

Request Parameters

Parameter Type Required Description
reason string No Reason for deactivation (for audit purposes)
transfer_supervisor_to integer No ID of user to transfer supervised users to

Example Request

{
    "reason": "Employee termination - end of employment",
    "transfer_supervisor_to": 45
}

Example Response

{
    "success": true,
    "data": {
        "user": {
            "id": 123,
            "status": "inactive",
            "deactivated_at": "2025-03-11T16:00:00Z",
            "deactivation_reason": "Employee termination - end of employment"
        },
        "actions_taken": {
            "supervised_users_transferred": 1,
            "new_supervisor_id": 45,
            "active_sessions_terminated": 2,
            "api_keys_revoked": 1
        }
    },
    "message": "User deactivated successfully"
}

Get User Activity

Get detailed activity history for a specific user.

GET /api/v1/users/{user_id}/activity
Authentication: Required
Required Permissions: view_user_activity

Path Parameters

Parameter Type Required Description
user_id integer Yes ID of the user

Query Parameters

Parameter Type Required Description
page integer No Page number (default: 1)
per_page integer No Items per page (default: 50, max: 200)
activity_type string No Filter by activity type (login, chat, message, image_generation)
date_from string No Start date filter (ISO 8601 format)
date_to string No End date filter (ISO 8601 format)

Example Response

{
    "success": true,
    "data": {
        "activities": [
            {
                "id": 789456,
                "activity_type": "message_sent",
                "description": "Sent message in chat about investment portfolio review",
                "details": {
                    "chat_id": "chat_123456789",
                    "message_id": "msg_987654321",
                    "message_length": 145,
                    "contains_attachments": false
                },
                "ip_address": "192.168.1.100",
                "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
                "timestamp": "2025-03-11T08:35:00Z"
            },
            {
                "id": 789455,
                "activity_type": "login",
                "description": "User logged in via Microsoft SSO",
                "details": {
                    "login_method": "microsoft_sso",
                    "session_id": "sess_abc123def456",
                    "location": "Chicago, IL"
                },
                "ip_address": "192.168.1.100",
                "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
                "timestamp": "2025-03-11T08:30:00Z"
            },
            {
                "id": 789454,
                "activity_type": "image_generated",
                "description": "Generated financial chart image",
                "details": {
                    "image_id": "img_123456789",
                    "prompt": "Portfolio allocation pie chart",
                    "image_type": "chart",
                    "generation_time_ms": 3200
                },
                "ip_address": "192.168.1.100",
                "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
                "timestamp": "2025-03-10T15:20:00Z"
            }
        ],
        "pagination": {
            "current_page": 1,
            "per_page": 50,
            "total": 3,
            "total_pages": 1
        },
        "summary": {
            "activity_count": 3,
            "unique_sessions": 2,
            "most_common_activity": "message_sent",
            "date_range": {
                "from": "2025-03-10T15:20:00Z",
                "to": "2025-03-11T08:35:00Z"
            }
        }
    },
    "message": "User activity retrieved successfully"
}

Bulk Operations

Perform operations on multiple users at once for administrative efficiency.

Bulk Update Users

Update multiple users with the same changes (role, department, supervisor, etc.).

PATCH /api/v1/users/bulk
Authentication: Required
Required Permissions: bulk_update_users

Request Parameters

Parameter Type Required Description
user_ids array Yes Array of user IDs to update
updates object Yes Fields to update for all specified users

Example Request

{
    "user_ids": [123, 124, 125],
    "updates": {
        "supervisor_id": 45,
        "department": "Investment Management - West Coast",
        "office_location": "San Francisco Office"
    }
}

Example Response

{
    "success": true,
    "data": {
        "updated_users": 3,
        "failed_updates": 0,
        "results": [
            {
                "user_id": 123,
                "status": "success",
                "updated_fields": ["supervisor_id", "department", "office_location"]
            },
            {
                "user_id": 124,
                "status": "success",
                "updated_fields": ["supervisor_id", "department", "office_location"]
            },
            {
                "user_id": 125,
                "status": "success",
                "updated_fields": ["supervisor_id", "department", "office_location"]
            }
        ]
    },
    "message": "Bulk user update completed successfully"
}

API Tester

Test the User Management API endpoints directly from this documentation.