feat: adding bulk user validation endpoint for admin console

Author: jacobo-dominguez-wgu

CHANGELOG.rst

@@ -14,6 +14,14 @@ Change Log
 Unreleased
 **********
 
+1.6.0 - 2026-04-10
+******************
+
+Added
+=====
+
+* Add ``users/validate`` endpoint endpoint for bulk validation of user identifiers (usernames or emails).
+
 1.5.0 - 2026-04-09
 ******************
 
@@ -370,4 +378,4 @@ Added
 Added
 =====
 
-* Basic repo structure and initial setup.
+* Basic repo structure and initial setup.

openedx_authz/__init__.py

@@ -4,6 +4,6 @@
 
 import os
 
-__version__ = "1.5.0"
+__version__ = "1.6.0"
 
 ROOT_DIRECTORY = os.path.dirname(os.path.abspath(__file__))

openedx_authz/rest_api/v1/fields.py

@@ -37,3 +37,11 @@ def to_internal_value(self, data):
     def to_representation(self, value):
         """Convert string to lowercase"""
         return value.strip().lower()
+
+
+class UserValidationSummarySerializer(serializers.Serializer):  # pylint: disable=abstract-method
+    """Serializer for user validation summary statistics."""
+
+    total = serializers.IntegerField(help_text="Total number of users validated")
+    valid_count = serializers.IntegerField(help_text="Number of valid users found")
+    invalid_count = serializers.IntegerField(help_text="Number of invalid users")

openedx_authz/rest_api/v1/serializers.py

@@ -11,6 +11,7 @@
     CaseSensitiveCommaSeparatedListField,
     CommaSeparatedListField,
     LowercaseCharField,
+    UserValidationSummarySerializer,
 )
 
 User = get_user_model()
@@ -259,3 +260,26 @@ def get_email(self, obj: UserAssignments) -> str:
     def get_assignation_count(self, obj: UserAssignments) -> int:
         """Get the assignation count for the given role assignment."""
         return len(obj.assignments)
+class UserValidationAPIViewSerializer(serializers.Serializer):  # pylint: disable=abstract-method
+    """Serializer for validating user existence."""
+
+    users = serializers.ListField(
+        child=serializers.CharField(max_length=255), allow_empty=False, help_text="List of user identifiers to validate"
+    )
+
+    def validate_users(self, value) -> list[str]:
+        """Eliminate duplicates preserving order"""
+        return list(dict.fromkeys(value))
+
+
+class UserValidationAPIViewResponseSerializer(serializers.Serializer):  # pylint: disable=abstract-method
+    """Serializer for user validation response."""
+
+    valid_users = serializers.ListField(
+        child=serializers.CharField(max_length=255), help_text="List of user identifiers that were found to be valid"
+    )
+    invalid_users = serializers.ListField(
+        child=serializers.CharField(max_length=255),
+        help_text="List of user identifiers that were not found or are invalid",
+    )
+    summary = UserValidationSummarySerializer(help_text="Summary statistics for the validation operation")

openedx_authz/rest_api/v1/urls.py

@@ -14,4 +14,5 @@
     path("roles/users/", views.RoleUserAPIView.as_view(), name="role-user-list"),
     path("orgs/", views.AdminConsoleOrgsAPIView.as_view(), name="orgs-list"),
     path("users/", views.TeamMembersAPIView.as_view(), name="user-list"),
+    path("users/validate/", views.UserValidationAPIView.as_view(), name="user-validation"),
 ]

openedx_authz/rest_api/v1/views.py

@@ -42,6 +42,8 @@
     RemoveUsersFromRoleWithScopeSerializer,
     TeamMemberSerializer,
     UserRoleAssignmentSerializer,
+    UserValidationAPIViewResponseSerializer,
+    UserValidationAPIViewSerializer,
 )
 from openedx_authz.utils import get_user_by_username_or_email
 
@@ -586,3 +588,87 @@ def get(self, request: HttpRequest) -> Response:
         paginator = self.pagination_class()
         paginated_response_data = paginator.paginate_queryset(team_members, request)
         return paginator.get_paginated_response(paginated_response_data)
+    
+
+@view_auth_classes()
+class UserValidationAPIView(APIView):
+    """API view for validating that provided user identifiers correspond to existing users.
+
+    This view allows clients to verify that a list of user identifiers (usernames or emails)
+    correspond to valid users in the system. It is designed to support bulk validation of multiple
+    user identifiers in a single request, providing a convenient way to check the validity of users before
+    performing operations such as role assignments.
+
+    **Endpoints**
+    - POST: Validate that the provided list of usernames or emails correspond to existing users
+
+    **Request Format (POST)**
+    - users: List of user identifiers (username or email)
+
+    **Response Format (POST)**
+
+    Returns HTTP 200 OK with::
+
+        {
+            "valid_users": ["john_doe", "[email protected]"],
+            "invalid_users": ["nonexistent_user"],
+            "summary": {
+                "total": 3,
+                "valid_count": 2,
+                "invalid_count": 1
+            }
+        }
+
+    **Authentication and Permissions**
+
+    - Requires authenticated user.
+    - Requires ``manage_library_team`` or ``manage_course_team`` permission in any scope.
+
+    **Example Request**
+
+    POST /api/authz/v1/users/validate/ ::
+
+        {
+            "users": ["john_doe", "[email protected]", "nonexistent_user"]
+        }
+    """
+
+    permission_classes = [AnyScopePermission]
+
+    @apidocs.schema(
+        body=UserValidationAPIViewSerializer,
+        responses={
+            status.HTTP_200_OK: UserValidationAPIViewResponseSerializer,
+            status.HTTP_400_BAD_REQUEST: "The request data is invalid",
+            status.HTTP_401_UNAUTHORIZED: "The user is not authenticated",
+            status.HTTP_403_FORBIDDEN: "The user does not have the required permissions",
+        },
+    )
+    @authz_permissions([permissions.MANAGE_LIBRARY_TEAM.identifier, permissions.COURSES_MANAGE_COURSE_TEAM.identifier])
+    def post(self, request: HttpRequest) -> Response:
+        """Validates the provided usernames or emails correspond to existing users."""
+
+        request_serializer = UserValidationAPIViewSerializer(data=request.data)
+        request_serializer.is_valid(raise_exception=True)
+        serialized_request_data = request_serializer.validated_data
+        valid_users = []
+        invalid_users = []
+        for user_identifier in serialized_request_data["users"]:
+            try:
+                _user = get_user_by_username_or_email(user_identifier)
+                valid_users.append(user_identifier)
+            except User.DoesNotExist:
+                invalid_users.append(user_identifier)
+
+        response_data = {
+            "valid_users": valid_users,
+            "invalid_users": invalid_users,
+            "summary": {
+                "total": len(serialized_request_data["users"]),
+                "valid_count": len(valid_users),
+                "invalid_count": len(invalid_users),
+            },
+        }
+        response_serializer = UserValidationAPIViewResponseSerializer(response_data)
+        return Response(response_serializer.data, status=status.HTTP_200_OK)
+