Retrieve list of users with filtering, sorting, and pagination.

Authentication: JWT token required Access: Restricted to ADMIN and SUPERADMIN users only

Query Parameters:

• include: Comma-separated list of additional fields to include
• exclude: Comma-separated list of fields to exclude from response
• filter: Filter users by email, name, role, or other attributes
• sort: Sort field (prefix with '-' for descending, e.g., '-created_at')
• page: Page number for pagination (triggers pagination when provided)
• per_page: Items per page (1-100, default: 20)

Response Schema (without pagination):

{
  "data": [
    {
      "id": "123",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "USER",
      "country": "US",
      "institution": "Example Organization",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z",
      "last_login_at": "2025-01-15T09:30:00Z",
      "last_activity_at": "2025-01-15T11:30:00Z",
      "email_verified": true,
      "email_verified_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Response Schema (with pagination):

{
  "data": [...],
  "page": 1,
  "per_page": 20,
  "total": 150
}

Filtering Examples:

• ?filter=role=ADMIN - Find users with ADMIN role
• ?filter=country=US - Find users from United States
• ?filter=email_verified=true - Find users who verified their email
• ?filter=last_activity_at>2025-01-01 - Find users active after date

Sorting Examples:

• ?sort=name - Sort by name ascending
• ?sort=-created_at - Sort by creation date descending
• ?sort=last_activity_at desc - Sort by last activity descending
• ?sort=-email_verified - Sort unverified users first

Field Control Examples:

• ?include=password_last_changed - Include additional fields
• ?exclude=institution,country - Exclude specified fields

Error Responses:

• 401 Unauthorized: JWT token required
• 403 Forbidden: Insufficient privileges (ADMIN+ required)
• 500 Internal Server Error: Failed to retrieve users