What is User Management?

User management in CampusMindAI allows administrators to view, search, and remove users from the platform. These operations help maintain an organized user base and ensure proper access control.

Why User Management is Important

• Access Control: Monitor who has access to your CampusMindAI tenant

• User Auditing: Review user roles, groups, and activity

• Compliance: Maintain accurate records of platform users

• Lifecycle Management: Remove users who no longer need access

List Users

Retrieve a paginated list of all users in your CampusMindAI tenant.

Endpoint Details

• Method: POST

• URL: {{baseURL}}/api/v1/list_users/

• Authentication: Required (JWT Bearer token)

Request Headers

Authorization: Bearer <jwt-token>
Content-Type: application/json

Request Body

Example Request

curl -X POST "https://<baseURL>/api/v1/list_users/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 10
  }'

Response Structure

Status Code: 200 OK

{
  "current_page": 1,
  "next_page": 2,
  "total_pages": 5,
  "total_records": 47,
  "limit": 10,
  "users": [
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_name": "John Doe",
      "user_email": "john.doe@example.com",
      "user_create_at": "2024-01-15T10:30:00Z",
      "user_groups": ["Engineering", "Admins"],
      "user_role": 3,
      "user_invited_by": "admin@example.com"
    }
  ]
}

Response Fields

User Object Fields

Pagination Examples

First page:

{
  "page": 1,
  "limit": 10
}

Navigate to page 3:

{
  "page": 3,
  "limit": 10
}

Show 50 users per page:

{
  "page": 1,
  "limit": 50
}

Delete User

Remove a user from the CampusMindAI platform. This operation is irreversible.

Endpoint Details

• Method: POST

• URL: {{baseURL}}/api/v1/delete_user

• Authentication: Required (JWT Bearer token)

Request Headers

Authorization: Bearer <jwt-token>
Content-Type: application/json

Request Body

Example Request

curl -X POST "https://<baseURL>/api/v1/delete_user" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "user@example.com"
  }'

Successful Response

Status Code: 200 OK

{
  "success": true
}

Error Responses

Important Notes

• Irreversible Operation: Deleted users cannot be recovered

• Data Retention: User's historical data may be retained for audit purposes

• Re-invitation Required: If the user needs access again, they must be re-invited

• Group Memberships: User is automatically removed from all groups

Usage Examples

List All Users with Pagination

# Page 1
curl -X POST "https://<baseURL>/api/v1/list_users/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 20}'

# Page 2
curl -X POST "https://<baseURL>/api/v1/list_users/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"page": 2, "limit": 20}'

Search for Specific User

After listing users, filter by email or name in your application:

response = list_users(page=1, limit=100)
target_user = next(
    (user for user in response["users"] 
     if user["user_email"] == "target@example.com"),
    None
)

Delete User by Email

curl -X POST "https://<baseURL>/api/v1/delete_user" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "departing.user@example.com"
  }'

Best Practices

Listing Users

• Use appropriate page sizes: 10-50 users per page for optimal performance

• Cache results: Store user lists temporarily to reduce API calls

• Filter locally: Retrieve larger pages and filter in your application

• Monitor total records: Track user growth over time

Deleting Users

• Confirm before deletion: Implement confirmation prompts in your UI

• Log deletions: Record who deleted which user and when

• Document reasons: Maintain audit logs for user removals

• Review dependencies: Check if user owns critical resources (VTAs, agents)

Security

• Restrict access: Only administrators should delete users

• Validate permissions: Check user's role before allowing deletions

• Audit regularly: Review user list for inactive or unauthorized accounts

• Immediate action: Remove access for departing employees immediately

Common Use Cases

Onboarding Audit

List all recently added users:

curl -X POST "https://<baseURL>/api/v1/list_users/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 100}'

Filter by user_create_at in your application for users created in the last 7 days.

Role Distribution

Analyze user roles across your tenant by listing all users and counting by user_role.

Offboarding Process

Remove departing users:

1. List users to find the correct email

2. Verify the user should be removed

3. Delete the user

4. Confirm deletion with success response

Group Membership Review

List users and examine user_groups field to audit group assignments.

Troubleshooting

Empty User List

Issue: users array is empty

Causes:

• Requesting a page beyond available pages

• No users exist in the tenant

• User lacks permission to view users

Solutions:

• Check total_pages and request valid page

• Verify users exist in the tenant

• Confirm your account has appropriate permissions

Cannot Delete User

Issue: Delete operation fails

Causes:

• User email doesn't exist

• User is a system account

• User has active sessions or resources

Solutions:

• Verify exact email address (case-sensitive)

• Check if user is protected system account

• Review user's resources and dependencies

Pagination Errors

Issue: Incorrect pagination behavior

Causes:

• Invalid page number (0 or negative)

• Limit too high or too low

• Changes to user list during pagination

Solutions:

• Use page numbers starting from 1

• Keep limit between 1-100

• Re-fetch if data changes during pagination

Performance Considerations

Optimal Page Sizes

Rate Limiting

• Avoid rapid successive requests

• Implement exponential backoff on errors

• Cache results when appropriate

• Use webhooks for real-time updates if available