feat: Implement scopes endpoint for admin console

Author: rodmgwgu

CHANGELOG.rst

@@ -14,6 +14,14 @@ Change Log
 Unreleased
 **********
 
+1.9.0 - 2026-04-15
+******************
+
+Added
+=====
+
+* Add ``scopes/`` endpoint to list all scopes (courses and libraries), sorted by org, with search and pagination support.
+
 1.8.0 - 2026-04-14
 ******************
 

openedx_authz/__init__.py

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

openedx_authz/api/data.py

@@ -14,7 +14,12 @@
 from opaque_keys.edx.locator import LibraryLocatorV2
 from organizations.models import Organization
 
-from openedx_authz.constants.permissions import COURSES_VIEW_COURSE_TEAM, VIEW_LIBRARY_TEAM
+from openedx_authz.constants.permissions import (
+    COURSES_MANAGE_COURSE_TEAM,
+    COURSES_VIEW_COURSE_TEAM,
+    MANAGE_LIBRARY_TEAM,
+    VIEW_LIBRARY_TEAM,
+)
 from openedx_authz.data import AUTHZ_POLICY_ATTRIBUTES_SEPARATOR, ActionData, AuthzBaseClass, AuthZData, PermissionData
 from openedx_authz.models.scopes import get_content_library_model, get_course_overview_model
 
@@ -356,6 +361,20 @@ def get_admin_view_permission(cls) -> PermissionData:
         """
         raise NotImplementedError("Subclasses must implement get_admin_view_permission method.")
 
+    @classmethod
+    @abstractmethod
+    def get_admin_manage_permission(cls) -> PermissionData:
+        """Get the permission required to manage this scope
+
+        This method should be implemented on every ScopeData subclass to define
+        which permission to check against when a user tries to manage assignations
+        related to this scope in the Admin Console.
+
+        Returns:
+            PermissionData: The permission required to manage this scope in the admin console.
+        """
+        raise NotImplementedError("Subclasses must implement get_admin_manage_permission method.")
+
     @abstractmethod
     def get_object(self) -> Any | None:
         """Retrieve the underlying domain object that this scope represents.
@@ -462,6 +481,15 @@ def get_admin_view_permission(cls) -> PermissionData:
         """
         return VIEW_LIBRARY_TEAM
 
+    @classmethod
+    def get_admin_manage_permission(cls) -> PermissionData:
+        """Get the permission required to manage this scope
+
+        Returns:
+            PermissionData: The permission required to manage this scope in the admin console.
+        """
+        return MANAGE_LIBRARY_TEAM
+
     def get_object(self) -> ContentLibrary | None:
         """Retrieve the ContentLibrary instance associated with this scope.
 
@@ -584,6 +612,15 @@ def get_admin_view_permission(cls) -> PermissionData:
         """
         return COURSES_VIEW_COURSE_TEAM
 
+    @classmethod
+    def get_admin_manage_permission(cls) -> PermissionData:
+        """Get the permission required to manage this scope
+
+        Returns:
+            PermissionData: The permission required to manage this scope in the admin console.
+        """
+        return COURSES_MANAGE_COURSE_TEAM
+
     def get_object(self) -> CourseOverview | None:
         """Retrieve the CourseOverview instance associated with this scope.
 
@@ -714,6 +751,15 @@ def build_external_key(cls, org: str) -> str:
         """
         return f"{cls.NAMESPACE}{EXTERNAL_KEY_SEPARATOR}{org}{cls.ID_SEPARATOR}{GLOBAL_SCOPE_WILDCARD}"
 
+    @classmethod
+    def get_admin_manage_permission(cls) -> PermissionData:
+        """Get the permission required to manage this scope
+
+        Returns:
+            PermissionData: The permission required to manage this scope in the admin console.
+        """
+        raise NotImplementedError("Subclasses must implement get_admin_manage_permission method.")
+
     @classmethod
     def get_org(cls, external_key: str) -> str | None:
         """Extract the organization identifier from the glob pattern.
@@ -812,6 +858,15 @@ def get_admin_view_permission(cls) -> PermissionData:
         """
         return VIEW_LIBRARY_TEAM
 
+    @classmethod
+    def get_admin_manage_permission(cls) -> PermissionData:
+        """Get the permission required to manage this scope
+
+        Returns:
+            PermissionData: The permission required to manage this scope in the admin console.
+        """
+        return MANAGE_LIBRARY_TEAM
+
 
 @define
 class OrgCourseOverviewGlobData(OrgGlobData):
@@ -861,6 +916,15 @@ def get_admin_view_permission(cls) -> PermissionData:
         """
         return COURSES_VIEW_COURSE_TEAM
 
+    @classmethod
+    def get_admin_manage_permission(cls) -> PermissionData:
+        """Get the permission required to manage this scope
+
+        Returns:
+            PermissionData: The permission required to manage this scope in the admin console.
+        """
+        return COURSES_MANAGE_COURSE_TEAM
+
 
 class CCXCourseOverviewData(CourseOverviewData):
     """CCX course scope for authorization in the Open edX platform.

openedx_authz/rest_api/v1/serializers.py

@@ -1,6 +1,8 @@
 """Serializers for the Open edX AuthZ REST API."""
 
 from django.contrib.auth import get_user_model
+from opaque_keys.edx.locator import LibraryLocatorV2
+from organizations.serializers import OrganizationSerializer
 from rest_framework import serializers
 
 from openedx_authz import api
@@ -49,6 +51,12 @@ class OrderMixin(serializers.Serializer):  # pylint: disable=abstract-method
     )
 
 
+class OrgMixin(serializers.Serializer):  # pylint: disable=abstract-method
+    """Mixin providing org field functionality."""
+
+    org = serializers.CharField(required=False, max_length=255)
+
+
 class PermissionValidationSerializer(ActionMixin, ScopeMixin):  # pylint: disable=abstract-method
     """Serializer for permission validation request."""
 
@@ -215,6 +223,14 @@ def get_roles(self, obj: api.RoleAssignmentData) -> list[str]:
         return [role.external_key for role in obj.roles]
 
 
+class ListScopesQuerySerializer(OrgMixin):  # pylint: disable=abstract-method
+    """Serializer for validating query parameters in ScopesAPIView."""
+
+    management_permission_only = serializers.BooleanField(required=False, default=False)
+    scope_type = serializers.ChoiceField(choices=["course", "library"], required=False, default=None, allow_null=True)
+    search = serializers.CharField(required=False, default="", allow_blank=True)
+
+
 class ListTeamMembersSerializer(OrderMixin):  # pylint: disable=abstract-method
     """
     Serializer for listing team members.
@@ -346,3 +362,28 @@ def get_permission_count(self, obj: api.RoleAssignmentData | api.SuperAdminAssig
                 return None
             case api.RoleAssignmentData():
                 return len(obj.roles[0].permissions) if obj.roles else 0
+
+
+class ScopeSerializer(serializers.Serializer):  # pylint: disable=abstract-method
+    """
+    Serializer for scope.
+    """
+
+    external_key = serializers.SerializerMethodField()
+    display_name = serializers.SerializerMethodField()
+    org = serializers.SerializerMethodField()
+
+    def get_external_key(self, obj: dict) -> str:
+        """Get the external key for the given scope."""
+        if obj["scope_type"] == "library":
+            return str(LibraryLocatorV2(org=obj["org_name"], slug=obj["scope_id"]))
+        return obj["scope_id"]
+
+    def get_display_name(self, obj: dict) -> str:
+        """Get the display name for the given scope."""
+        return str(obj.get("display_name_col") or "")
+
+    def get_org(self, obj: dict) -> dict | None:
+        """Get the org for the given scope."""
+        org = self.context.get("org_map", {}).get(obj["org_name"])
+        return OrganizationSerializer(org).data if org else None

openedx_authz/rest_api/v1/urls.py

@@ -18,4 +18,5 @@
     path(
         "users/<str:username>/assignments/", views.TeamMemberAssignmentsAPIView.as_view(), name="user-assignment-list"
     ),
+    path("scopes/", views.ScopesAPIView.as_view(), name="scope-list"),
 ]