openedx_authz.rest_api.v1 package

openedx_authz.rest_api.v1 package#

Submodules#

openedx_authz.rest_api.v1.fields module#

Fields serializer for the Open edX AuthZ REST API.

class openedx_authz.rest_api.v1.fields.CaseSensitiveCommaSeparatedListField(*args, **kwargs)

Bases: CharField

Serializer for a comma-separated list of strings, case-sensitive.

to_internal_value(data)

Convert string separated by commas to list of unique items preserving order

to_representation(value)

Convert list to string separated by commas

class openedx_authz.rest_api.v1.fields.CommaSeparatedListField(*args, **kwargs)

Bases: CharField

Serializer for a comma-separated list of strings.

to_internal_value(data)

Convert string separated by commas to list of unique items preserving order

to_representation(value)

Convert list to string separated by commas

class openedx_authz.rest_api.v1.fields.LowercaseCharField(*args, **kwargs)

Bases: CharField

Serializer for a lowercase string.

to_internal_value(data)

Convert string to lowercase

to_representation(value)

Convert string to lowercase

openedx_authz.rest_api.v1.filters module#

Custom DRF filter backends for the Open edX AuthZ REST API.

class openedx_authz.rest_api.v1.filters.TeamMemberAssignmentsOrderingFilter

Bases: BaseFilterBackend

Sort team member assignments by a given field and order.

filter_queryset(request, queryset, view)

Return a filtered queryset.

class openedx_authz.rest_api.v1.filters.TeamMemberOrderingFilter

Bases: BaseFilterBackend

Sort team members by a given field and order.

filter_queryset(request, queryset, view)

Return a filtered queryset.

class openedx_authz.rest_api.v1.filters.TeamMemberSearchFilter

Bases: BaseFilterBackend

Filter team members by a search term.

filter_queryset(request, queryset, view)

Return a filtered queryset.

class openedx_authz.rest_api.v1.filters.UserAssignmentsOrderingFilter

Bases: BaseFilterBackend

Sort user assignments by a given field and order.

filter_queryset(request, queryset, view)

Return a filtered queryset.

class openedx_authz.rest_api.v1.filters.UserAssignmentsSearchFilter

Bases: BaseFilterBackend

Filter user assignments by a search term over full_name, username, and email.

filter_queryset(request, queryset, view)

Return a filtered queryset.

openedx_authz.rest_api.v1.paginators module#

Pagination classes for the REST API.

class openedx_authz.rest_api.v1.paginators.AuthZAPIViewPagination

Bases: PageNumberPagination

Pagination class for the AuthZ API views.

max_page_size = 100
page_size = 10
page_size_query_param = 'page_size'

openedx_authz.rest_api.v1.permissions module#

Permissions for the Open edX AuthZ REST API.

class openedx_authz.rest_api.v1.permissions.AnyScopePermission

Bases: MethodPermissionMixin, BasePermission

Permission handler for endpoints that are not tied to a specific scope.

Grants access if the user has at least one of the required permissions in any scope.

has_permission(request, view) → bool

Check if the user has any of the required permissions across all scopes.

Superusers and staff are automatically granted access. For other users, grants access if the user has at least one required permission in any scope.

Returns:

True if the user has at least one required permission in any scope.

Return type:

bool

class openedx_authz.rest_api.v1.permissions.BaseScopePermission

Bases: BasePermission

Base permission class for all scope-based permissions.

This class provides the foundation for implementing scope-based authorization checks in the REST API. It extracts scope information from requests and provides hooks for permission validation. Subclasses should override the permission methods to implement specific authorization logic for their scope types.

NAMESPACE: ClassVar[str] = 'global'

The namespace identifier for this permission class. Default global for generic scopes.

get_scope_namespace(request) → str

Derive the namespace from the request scope value.

Attempts to parse the scope value and extract its namespace. If the scope value is invalid or missing, falls back to this class’s NAMESPACE.

Parameters:

request – The Django REST framework request object.

Returns:

The scope namespace (e.g., ‘lib’, ‘global’).

Return type:

str

Examples

>>> request.data = {"scope": "lib:DemoX:CSPROB"}
>>> permission.get_scope_namespace(request)
'lib'
>>> request.data = {}
>>> permission.get_scope_namespace(request)
'global'
get_scope_value(request) → str | None

Extract the scope value from the request.

When a scopes list is provided, returns only the first element. This is intentional: bulk requests are expected to be homogeneous (all scopes must share the same namespace). Actual per-scope permission validation for bulk requests is handled in DynamicScopePermission.

Parameters:

request – The Django REST framework request object.

Returns:

The scope value if found (e.g., ‘lib:DemoX:CSPROB’), or None if not present.

Return type:

str | None

has_object_permission(request, view, obj) → bool

Fallback object-level permission check (deny by default).

Subclasses should override this method to implement their specific object-level permission logic.

Returns:

False (deny access by default).

Return type:

bool

has_permission(request, view) → bool

Fallback permission check (deny by default).

Subclasses should override this method to implement their specific permission logic.

Returns:

False (deny access by default).

Return type:

bool

class openedx_authz.rest_api.v1.permissions.ContentLibraryPermission

Bases: MethodPermissionMixin, BaseScopePermission

Permission handler for content library scopes.

This class implements permission checks specific to content library operations. It uses the authz API to verify whether a user has the necessary permissions to perform actions on library team members.

NAMESPACE: ClassVar[str] = 'lib'

lib for content library scopes.

has_permission(request, view) → bool

Check if the user has permission to perform the requested action.

First checks if the view method has @authz_permissions decorator. If present, validates all required permissions. If not present, allows access by default.

Returns:

True if the user has the required permission, False otherwise.

Also returns False if no scope value is provided in the request.

Return type:

bool

class openedx_authz.rest_api.v1.permissions.CoursePermission

Bases: MethodPermissionMixin, BaseScopePermission

Permission handler for course scopes.

This class implements permission checks specific to course operations. It uses the authz API to verify whether a user has the necessary permissions to perform actions on course team members or course resources.

NAMESPACE: ClassVar[str] = 'course-v1'

course-v1 for course scopes.

has_permission(request, view) → bool

Check if the user has permission to perform the requested action.

First checks if the view method has @authz_permissions decorator. If present, validates all required permissions. If not present, allows access by default.

Returns:

True if the user has the required permission, False otherwise.

Also returns False if no scope value is provided in the request.

Return type:

bool

class openedx_authz.rest_api.v1.permissions.DynamicScopePermission

Bases: BaseScopePermission

Dispatcher permission class that delegates permission checks to scope-specific handlers.

This class acts as a dispatcher that automatically selects and delegates to the appropriate permission class based on the request’s scope namespace. It also provides special handling for superusers and staff members.

Permission Flow:

  1. Check if user is superuser or staff (automatic approval).

  2. Extract the scope namespace from the request.

  3. Look up the appropriate permission class for that namespace.

  4. Delegate the permission check to that class.

Examples

>>> permission = ScopePermission()
>>> # For a library scope request, this will delegate to ContentLibraryPermission
>>> request.data = {"scope": "lib:DemoX:CSPROB"}
>>> ContentLibraryPermission.has_permission(request, view)
>>> # For a generic scope request, this will delegate to BaseScopePermission
>>> request.data = {"scope": "global:generic"}
>>> BaseScopePermission.has_permission(request, view)

Note

Superusers and staff members always have permission regardless of scope. Bulk requests (scopes list) must be homogeneous — all scopes must share the same namespace (e.g., all course-v1: or all lib:). Mixed namespaces will raise a ValueError during namespace resolution.

NAMESPACE: ClassVar[None] = None

This is a dispatcher, not tied to a specific namespace.

has_object_permission(request, view, obj) → bool

Delegate object-level permission check to the appropriate scope-specific permission class.

Superusers and staff members are automatically granted permission. For other users, the object-level permission check is delegated to the permission class registered for the request’s scope namespace.

Examples

>>> # Regular user gets scope-specific check
>>> request.data = {"scope": "lib:DemoX:CSPROB"}
>>> permission.has_object_permission(request, view, obj)  # Delegates to ContentLibraryPermission
has_permission(request, view) → bool

Delegate permission check to the appropriate scope-specific permission class.

Superusers and staff members are automatically granted permission. For other users, the permission check is delegated to the permission class registered for the request’s scope namespace.

For bulk requests that carry a scopes list, delegates to _has_bulk_permission: every scope must pass at least one of the required permissions (OR logic per permission, AND logic across scopes).

Examples

>>> # Regular user gets scope-specific check
>>> request.data = {"scope": "lib:DemoX:CSPROB"}
>>> permission.has_permission(request, view)  # Delegates to ContentLibraryPermission
class openedx_authz.rest_api.v1.permissions.MethodPermissionMixin

Bases: object

Mixin that validates permissions defined via @authz_permissions decorator.

This mixin reads the required_permissions attribute set by the @authz_permissions decorator and validates each permission using is_user_allowed. All permissions must be satisfied for the check to pass.

Usage:

Combine this mixin with BaseScopePermission to create permission classes that use method-level permission declarations:

>>> class MyPermission(MethodPermissionMixin, BaseScopePermission):
...     NAMESPACE = "lib"
...
>>> class MyView(APIView):
...     permission_classes = [MyPermission]
...
...     @authz_permissions(["content_libraries.view_library_team"])
...     def get(self, request):
...         pass
get_required_permissions(request, view) → list[str]

Extract required permissions from the view method.

Parameters:

  • request – The Django REST framework request object.

  • view – The view being accessed.

Returns:

List of permission identifiers, or empty list if not defined.

Return type:

list[str]

validate_permissions(request, permissions: list[str], scope_value: str) → bool

Validate that the user has at least one of the required permissions for the scope.

Parameters:

  • request – The Django REST framework request object.

  • permissions – List of permission identifiers to check (OR logic — any one suffices).

  • scope_value – The scope to check permissions against.

Returns:

True if user has at least one required permission, False otherwise.

Return type:

bool

class openedx_authz.rest_api.v1.permissions.PermissionMeta(name, bases, attrs)

Bases: BasePermissionMetaclass

Metaclass that automatically registers permission classes by namespace.

This metaclass maintains a registry of permission classes indexed by their NAMESPACE attribute. When a permission class is defined with a NAMESPACE, it is automatically registered in the permission_registry for later retrieval.

classmethod get_permission_class(namespace: str) → type[BaseScopePermission]

Retrieve the permission class for the given namespace.

Parameters:

namespace – The namespace identifier (e.g., ‘lib’, ‘global’).

Returns:

The permission class for the namespace,

or BaseScopePermission if the namespace is not registered.

Return type:

type[“BaseScopePermission”]

Examples

>>> PermissionMeta.get_permission_class("lib")
<class 'ContentLibraryPermission'>
>>> PermissionMeta.get_permission_class("unknown")
<class 'BaseScopePermission'>
permission_registry: dict[str, type[BaseScopePermission]] = {'course-v1': <class 'openedx_authz.rest_api.v1.permissions.CoursePermission'>, 'global': <class 'openedx_authz.rest_api.v1.permissions.BaseScopePermission'>, 'lib': <class 'openedx_authz.rest_api.v1.permissions.ContentLibraryPermission'>}

openedx_authz.rest_api.v1.serializers module#

Serializers for the Open edX AuthZ REST API.

class openedx_authz.rest_api.v1.serializers.ActionMixin(*args, **kwargs)

Bases: Serializer

Mixin providing action field functionality.

class openedx_authz.rest_api.v1.serializers.AddUsersToRoleWithScopeSerializer(*args, **kwargs)

Bases: RoleScopeValidationMixin, RoleMixin, ScopeMixin

Serializer for adding users to a role with one or more scopes.

Accepts either a single scope string (backward-compatible) or a scopes list for bulk assignment. Exactly one of the two must be provided per request.

validate(attrs) → dict

Validate that exactly one of ‘scope’/’scopes’ is provided and that every scope exists in the registry, exists in the system, and supports the role. Returns validated data with a unified scopes list of strings.

validate_users(value) → list[str]

Eliminate duplicates preserving order.

class openedx_authz.rest_api.v1.serializers.ListAssignmentsQuerySerializer(*args, **kwargs)

Bases: ListTeamMemberAssignmentsQuerySerializer

Serializer for query params for the list all team member assignments endpoint.

class openedx_authz.rest_api.v1.serializers.ListRolesWithScopeResponseSerializer(*args, **kwargs)

Bases: Serializer

Serializer for listing roles with a scope response.

class openedx_authz.rest_api.v1.serializers.ListRolesWithScopeSerializer(*args, **kwargs)

Bases: Serializer

Serializer for listing roles within a scope.

validate_scope(value: str) → ScopeData

Validate and convert scope string to a ScopeData instance.

Checks that the provided scope is registered in the scope registry and returns an instance of the appropriate ScopeData subclass.

Parameters:

value – The scope string to validate (e.g., ‘lib’, ‘global’, ‘org’).

Returns:

An instance of the appropriate ScopeData subclass for the scope.

Return type:

ScopeData

Raises:

serializers.ValidationError – If the scope is not registered in the scope registry.

Examples

>>> validate_scope('lib:DemoX:CSPROB')
ContentLibraryData(external_key='lib:DemoX:CSPROB')
class openedx_authz.rest_api.v1.serializers.ListScopesQuerySerializer(*args, **kwargs)

Bases: OrgMixin

Serializer for validating query parameters in ScopesAPIView.

class openedx_authz.rest_api.v1.serializers.ListTeamMemberAssignmentsQuerySerializer(*args, **kwargs)

Bases: OrderMixin

Serializer for listing team member assignments.

class openedx_authz.rest_api.v1.serializers.ListTeamMembersSerializer(*args, **kwargs)

Bases: OrderMixin

Serializer for listing team members. This serializer is TeamMembersAPIView, which is used in the Admin Console. In this content, a team member is anyone with studio access.

class openedx_authz.rest_api.v1.serializers.ListUsersInRoleWithScopeResponseSerializer(*args, **kwargs)

Bases: Serializer

Serializer for listing users in a role with a scope response.

class openedx_authz.rest_api.v1.serializers.ListUsersInRoleWithScopeSerializer(*args, **kwargs)

Bases: ScopeMixin, OrderMixin

Serializer for listing users in a role with a scope.

class openedx_authz.rest_api.v1.serializers.OrderMixin(*args, **kwargs)

Bases: Serializer

Mixin providing ordering field functionality.

class openedx_authz.rest_api.v1.serializers.OrgMixin(*args, **kwargs)

Bases: Serializer

Mixin providing org field functionality.

class openedx_authz.rest_api.v1.serializers.PermissionValidationResponseSerializer(*args, **kwargs)

Bases: PermissionValidationSerializer

Serializer for permission validation response.

class openedx_authz.rest_api.v1.serializers.PermissionValidationSerializer(*args, **kwargs)

Bases: ActionMixin, ScopeMixin

Serializer for permission validation request.

class openedx_authz.rest_api.v1.serializers.RemoveUsersFromRoleWithScopeSerializer(*args, **kwargs)

Bases: RoleScopeValidationMixin, RoleMixin, ScopeMixin

Serializer for removing users from a role with a scope.

class openedx_authz.rest_api.v1.serializers.RoleMixin(*args, **kwargs)

Bases: Serializer

Mixin providing role field functionality.

class openedx_authz.rest_api.v1.serializers.RoleScopeValidationMixin(*args, **kwargs)

Bases: Serializer

Mixin providing role and scope validation logic.

validate(attrs) → dict

Validate that the specified role and scope are valid and that the role exists in the scope.

This method performs the following validations: 1. Validates that the scope is registered in the scope registry 2. Validates that the scope exists in the system 3. Validates that the role is defined into the roles assigned to the scope

Parameters:

attrs – Dictionary containing ‘role’ and ‘scope’ keys with their string values.

Returns:

The validated data dictionary with ‘role’ and ‘scope’ keys.

Return type:

dict

Raises:

serializers.ValidationError – If the scope is not registered, doesn’t exist, or if the role is not defined in the scope.

class openedx_authz.rest_api.v1.serializers.ScopeMixin(*args, **kwargs)

Bases: Serializer

Mixin providing scope field functionality.

class openedx_authz.rest_api.v1.serializers.ScopeSerializer(*args, **kwargs)

Bases: Serializer

Serializer for scope.

get_display_name(obj: dict) → str

Get the display name for the given scope.

get_external_key(obj: dict) → str

Get the external key for the given scope.

get_org(obj: dict) → dict | None

Get the org for the given scope.

class openedx_authz.rest_api.v1.serializers.TeamMemberAssignmentSerializer(*args, **kwargs)

Bases: Serializer

Serializer for team member assignments.

get_is_superadmin(obj: RoleAssignmentData | SuperAdminAssignmentData) → bool

Get whether this assignment entry is for a superadmin.

get_org(obj: RoleAssignmentData | SuperAdminAssignmentData) → str

Get the org for the given role assignment.

get_permission_count(obj: RoleAssignmentData | SuperAdminAssignmentData) → int | None

Get the permission count for the given role assignment.

get_role(obj: RoleAssignmentData | SuperAdminAssignmentData) → str

Get the role for the given role assignment.

get_scope(obj: RoleAssignmentData | SuperAdminAssignmentData) → str

Get the scope for the given role assignment.

class openedx_authz.rest_api.v1.serializers.TeamMemberSerializer(*args, **kwargs)

Bases: Serializer

Serializer for team members. This serializer is APIs used by the Admin Console. In this content, a team member is anyone with studio access.

get_assignation_count(obj: UserAssignments) → int

Get the assignation count for the given role assignment.

get_email(obj: UserAssignments) → str

Get the email for the given role assignment.

get_full_name(obj: UserAssignments) → str

Get the full name for the given role assignment.

get_username(obj: UserAssignments) → str

Get the username for the given role assignment.

class openedx_authz.rest_api.v1.serializers.TeamMemberUserAssignmentSerializer(*args, **kwargs)

Bases: TeamMemberAssignmentSerializer

Serializer for team member assignments with user information.

get_email(obj: UserAssignmentData | SuperAdminAssignmentData) → str

Get user email.

get_full_name(obj: UserAssignmentData | SuperAdminAssignmentData) → str

Get user full name.

get_username(obj: UserAssignmentData | SuperAdminAssignmentData) → str

Get username.

class openedx_authz.rest_api.v1.serializers.UserRoleAssignmentSerializer(*args, **kwargs)

Bases: Serializer

Serializer for a user role assignment.

get_email(obj) → str

Get the email for the given role assignment.

get_full_name(obj) → str

Get the full name for the given role assignment.

get_roles(obj: RoleAssignmentData) → list[str]

Get the roles for the given role assignment.

get_username(obj: RoleAssignmentData) → str

Get the username for the given role assignment.

class openedx_authz.rest_api.v1.serializers.UserValidationAPIViewResponseSerializer(*args, **kwargs)

Bases: Serializer

Serializer for user validation response.

class openedx_authz.rest_api.v1.serializers.UserValidationAPIViewSerializer(*args, **kwargs)

Bases: Serializer

Serializer for validating user existence.

validate_users(value) → list[str]

Eliminate duplicates preserving order

class openedx_authz.rest_api.v1.serializers.UserValidationSummarySerializer(*args, **kwargs)

Bases: Serializer

Serializer for user validation summary statistics.

openedx_authz.rest_api.v1.urls module#

Open edX AuthZ API v1 URLs.

openedx_authz.rest_api.v1.views module#

REST API views for Open edX Authorization (AuthZ) system.

This module provides Django REST Framework views for managing authorization permissions, roles, and user assignments within Open edX platform.

class openedx_authz.rest_api.v1.views.AdminConsoleOrgsAPIView(**kwargs)

Bases: ListAPIView

API view for listing orgs This API is used on the filters functionality on the Admin Console.

Endpoints

  • GET: Retrieve all organizations

Query Parameters

  • search (Optional): Search term to filter organizations by name or short name

  • page (Optional): Page number for pagination

  • page_size (Optional): Number of items per page

Response Format

Returns a paginated list of organization objects, each containing:

  • id: The organization’s ID

  • name: The organization’s name

  • short_name: The organization’s short name

Authentication and Permissions

  • Requires authenticated user.

Example Request

GET /api/authz/v1/orgs/?search=edx&page=1&page_size=10

Example Response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "created": "2026-04-02T19:30:36.779095Z",
            "modified": "2026-04-02T19:30:36.779095Z",
            "name": "OpenedX",
            "short_name": "OpenedX",
            "description": "",
            "logo": null,
            "active": true
        }
    ]
}
authentication_classes = [<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>]
filter_backends = [<class 'rest_framework.filters.SearchFilter'>]
get(request, *args, **kwargs)
get_queryset() → QuerySet

Return active organizations ordered by name.

pagination_class

alias of AuthZAPIViewPagination

permission_classes = [<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx_authz.rest_api.v1.permissions.AnyScopePermission'>]
search_fields = ['name', 'short_name']
serializer_class

alias of OrganizationSerializer

class openedx_authz.rest_api.v1.views.AssignmentsAPIView(**kwargs)

Bases: APIView

API view for listing all user role assignments This API is used on the main team members view on the Admin Console.

Endpoints

  • GET: Retrieve all user role assignments

Query Parameters

  • orgs (Optional): Comma-separated list of orgs to filter assignments by

  • roles (Optional): Comma-separated list of roles to filter assignments by

  • scopes (Optional): Comma-separated list of scopes to filter assignments by

  • search (Optional): Search term to filter assignments by full_name, username, or email

  • sort_by (Optional): Field to sort by. Options: role, org, scope, full_name, username, email. Defaults to full_name

  • order (Optional): Sort order, ‘asc’ or ‘desc’. Defaults to asc

  • page (Optional): Page number for pagination

  • page_size (Optional): Number of items per page

Response Format

Returns a paginated list of user assignment objects, each containing:

  • is_superadmin: whether this entry denotes a superadmin

  • role: The role

  • org: The org over which this role is applied

  • scope: The scope over which this role is applied

  • permission_count: The number of permissions that apply to this role

  • full_name: The full name of the user in this assignment

  • username: The username of the user in this assignment

  • email: The email of the user in this assignment

Authentication and Permissions

  • Requires authenticated user.

  • Results are filtered according to calling user’s “view scope team members” permissions.

Example Request

GET /api/authz/v1/assignments/?order=desc&sort_by=role&page=1&page_size=2&search=cont

Example Response:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "is_superadmin": false,
            "role": "course_staff",
            "org": "OpenedX",
            "scope": "course-v1:OpenedX+DemoX+DemoCourse",
            "permission_count": 27,
            "full_name": "",
            "username": "contributor",
            "email": "contributor@example.com"
        },
        {
            "is_superadmin": true,
            "role": "django.superuser",
            "org": "*",
            "scope": "*",
            "permission_count": null,
            "full_name": "",
            "username": "admin",
            "email": "admin@example.com"
        },
    ]
}
authentication_classes = [<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>]
filter_backends = [<class 'openedx_authz.rest_api.v1.filters.UserAssignmentsSearchFilter'>, <class 'openedx_authz.rest_api.v1.filters.UserAssignmentsOrderingFilter'>]
get(request: HttpRequest) → Response

Retrieve all user role assignments.

pagination_class

alias of AuthZAPIViewPagination

permission_classes = [<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx_authz.rest_api.v1.permissions.AnyScopePermission'>]
class openedx_authz.rest_api.v1.views.PermissionValidationMeView(**kwargs)

Bases: APIView

API view for validating user permissions against authorization policies.

This view enables authenticated users to verify their permissions for specific actions and scopes within the Open edX authorization system. It supports batch validation of multiple permissions in a single request.

Endpoints

  • POST: Validate one or more permissions for the authenticated user

Request Format

Expects a list of permission objects, each containing:

  • action: The action to validate (e.g., ‘content_libraries.edit_library_content’)

  • scope: The authorization scope (e.g., ‘lib:DemoX:CSPROB’)

Response Format

Returns a list of validation results, each containing:

  • action: The requested action

  • scope: The requested scope

  • allowed: Boolean indicating if the user has the permission

Authentication and Permissions

  • Requires authenticated user.

Example Request

POST /api/authz/v1/permissions/validate/me:

[
    {"action": "edit_library", "scope": "lib:DemoX:CSPROB"},
    {"action": "delete_library_content", "scope": "lib:OpenedX:CS50"}
]

Example Response:

[
    {"action": "edit_library", "scope": "lib:DemoX:CSPROB", "allowed": true},
    {"action": "delete_library_content", "scope": "lib:OpenedX:CS50", "allowed": false}
]
authentication_classes = [<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>]
permission_classes = [<class 'rest_framework.permissions.IsAuthenticated'>, <class 'rest_framework.permissions.AllowAny'>]
post(request: HttpRequest) → Response

Validate one or more permissions for the authenticated user.

class openedx_authz.rest_api.v1.views.RoleListView(**kwargs)

Bases: APIView

API view for retrieving role definitions and their associated permissions within a specific scope.

This view provides read-only access to role definitions within a specific authorization scope. It returns detailed information about each role including the permissions granted and the number of users assigned to each role.

Endpoints

  • GET: Retrieve all roles and their permissions for a specific scope

Query Parameters

  • scope (Required): The scope to query roles for (e.g., ‘lib:OpenedX:CSPROB’)

  • page (Optional): Page number for pagination

  • page_size (Optional): Number of items per page

Response Format

Returns a paginated list of role objects, each containing:

  • role: The role’s external identifier (e.g., ‘library_author’, ‘library_user’)

  • permissions: List of permission identifiers granted by this role (e.g., ‘content_libraries.delete_library’)

  • user_count: Number of users currently assigned to this role

Authentication and Permissions

  • Requires authenticated user.

  • Requires manage_library_team permission for the scope.

Example Request

GET /api/authz/v1/roles/?scope=lib:OpenedX:CSPROB&page=1&page_size=10

Example Response:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "role": "library_author",
            "permissions": ["delete_library_content", "edit_library"],
            "user_count": 5
        },
        {
            "role": "library_user",
            "permissions": ["view_library", "view_library_team", "reuse_library_content"],
            "user_count": 12
        }
    ]
}
authentication_classes = [<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>]
get(request: HttpRequest) → Response

Retrieve all roles and their permissions for a specific scope.

pagination_class

alias of AuthZAPIViewPagination

permission_classes = [<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx_authz.rest_api.v1.permissions.DynamicScopePermission'>]
class openedx_authz.rest_api.v1.views.RoleUserAPIView(**kwargs)

Bases: APIView

API view for managing user-role assignments within specific authorization scopes.

This view provides comprehensive role management capabilities, allowing administrators to view, assign, and remove role assignments for users within a given scope. It supports bulk operations for adding and removing multiple users, along with filtering, searching, sorting, and pagination of results.

Endpoints

  • GET: Retrieve all users with their role assignments in a scope

  • PUT: Assign multiple users to a specific role within a scope

  • DELETE: Remove multiple users from a specific role within a scope

Query Parameters (GET)

  • scope (Required): The authorization scope to query (e.g., ‘lib:DemoX:CSPROB’)

  • search (Optional): Search term to filter users by username, email or full name

  • roles (Optional): Filter by comma-separated list of specific role names

  • page (Optional): Page number for pagination

  • page_size (Optional): Number of items per page

  • sort_by (Optional): Field to sort by (e.g., ‘username’, ‘email’, ‘full_name’)

  • order (Optional): Sort order (‘asc’ or ‘desc’)

Request Format (PUT)

  • users: List of user identifiers (username or email)

  • role: The role to add users to

  • scope: The scope to add users to

Request Format (DELETE)

Query parameters:

  • users: Comma-separated list of user identifiers (username or email)

  • role: The role to remove users from

  • scope: The scope to remove users from

Response Format (GET)

Returns HTTP 200 OK with:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "username": "john_doe",
            "email": "john_doe@example.com",
            "full_name": "John Doe"
            "roles": ["library_admin", "library_user"]
        },
        {
            "username": "jane_doe",
            "email": "jane_doe@example.com",
            "full_name": "Jane Doe"
            "roles": ["library_user"]
        }
    ]
}

Response Format (PUT)

Returns HTTP 207 Multi-Status with:

{
    "completed": [{"user_identifier": "john_doe", "status": "role_added"}],
    "errors": [{"user_identifier": "jane_doe", "error": "user_already_has_role"}]
}

Response Format (DELETE)

Returns HTTP 207 Multi-Status with:

{
    "completed": [{"user_identifier": "john_doe", "status": "role_removed"}],
    "errors": [{"user_identifier": "jane_doe", "error": "user_does_not_have_role"}]
}

Authentication and Permissions

  • Requires authenticated user.

  • Requires manage_library_team permission for the scope.

Example Request

GET /api/authz/v1/roles/users/?scope=lib:DemoX:CSPROB&search=john&roles=library_admin

PUT /api/authz/v1/roles/users/

{
    "role": "library_admin",
    "scope": "lib:DemoX:CSPROB",
    "users": ["user1@example.com", "username2"]
}

DELETE /api/authz/v1/roles/users/?role=library_admin&scope=lib:DemoX:CSPROB&users=user1@example.com,username2

authentication_classes = [<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>]
delete(request: HttpRequest) → Response

Remove multiple users from a specific role within a scope.

get(request: HttpRequest) → Response

Retrieve all users with role assignments within a specific scope.

pagination_class

alias of AuthZAPIViewPagination

permission_classes = [<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx_authz.rest_api.v1.permissions.DynamicScopePermission'>]
put(request: HttpRequest) → Response

Assign multiple users to a specific role within one or more scopes.

class openedx_authz.rest_api.v1.views.ScopesAPIView(**kwargs)

Bases: ListAPIView

API view for listing scopes This API is used on the filters and assign roles functionality on the Admin Console.

Endpoints

  • GET: Retrieve all scopes

Query Parameters

  • search (Optional): Search term to filter scopes by display name

  • org (Optional): Filter scopes by org

  • orgs (Optional): Filter scopes by multiple orgs (comma separated list of orgs)

  • page (Optional): Page number for pagination

  • page_size (Optional): Number of items per page

  • scope_type (Optional): Filter scopes by type. Supported values are course and library.

  • management_permission_only (Optional): Filter scopes either by only the ones to which the user has “manage team”

    permissions (if true), or just “view team” permissions.

Response Format

Returns a paginated list of scope objects, each containing:

  • external_key: The scope external key

  • display_name: The scope’s name

  • org: The organization serialized object

Authentication and Permissions

  • Requires authenticated user with either a content library or course view team permission.

Example Request

GET /api/authz/v1/scopes/?search=edx&page=1&page_size=10

Example Response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "external_key": "course-v1:OpenedX+DemoX+DemoCourse",
            "display_name": "Open edX Demo Course",
            "org": {
                "id": 1,
                "created": "2026-04-02T19:30:36.779095Z",
                "modified": "2026-04-02T19:30:36.779095Z",
                "name": "OpenedX",
                "short_name": "OpenedX",
                "description": "",
                "logo": null,
                "active": true
            }
        },
    ]
}
authentication_classes = [<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>]
get(request, *args, **kwargs)
get_queryset() → QuerySet

Return scopes ordered by org, filtered by the user’s permissions.

get_serializer_context()

Extra context provided to the serializer class.

ordering_priority = (ScopesQuerySetFields.ORG_NAME, ScopesQuerySetFields.SCOPE_TYPE, ScopesQuerySetFields.DISPLAY_NAME_COL, ScopesQuerySetFields.SCOPE_ID)
pagination_class

alias of AuthZAPIViewPagination

permission_classes = [<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx_authz.rest_api.v1.permissions.AnyScopePermission'>]
serializer_class

alias of ScopeSerializer

class openedx_authz.rest_api.v1.views.TeamMemberAssignmentsAPIView(**kwargs)

Bases: APIView

API view for listing role assignments for a specific user. This API is used in the Team Member detail view in the Admin Console.

Endpoints

  • GET: Retrieve all role assignments for a specific user

URL Parameters

  • username (Required): The username of the user to retrieve assignments for

Query Parameters

  • orgs (Optional): Comma-separated list of orgs to filter assignments by (e.g., ‘Org1,Org2’)

  • roles (Optional): Comma-separated list of roles to filter assignments by (e.g., ‘library_admin,library_user’)

  • sort_by (Optional): Field to sort by. Options: role, org, scope. Defaults to role

  • order (Optional): Sort order, ‘asc’ or ‘desc’. Defaults to asc

  • page (Optional): Page number for pagination

  • page_size (Optional): Number of items per page

Response Format

Returns a paginated list of assignment objects, each containing:

  • is_superadmin: Whether this entry denotes a superadmin (staff/superuser)

  • role: The role name (e.g., ‘library_admin’, ‘django.superuser’)

  • org: The org over which this role is applied (‘*’ for superadmins)

  • scope: The scope over which this role is applied (‘*’ for superadmins)

  • permission_count: The number of permissions that apply to this role (null for superadmins)

Authentication and Permissions

  • Requires authenticated user.

  • Results are filtered according to calling user’s scope-level view permissions.

  • Superadmin entries are always included when the target user is a staff/superuser.

Example Request

GET /api/authz/v1/users/john_doe/assignments/?orgs=Org1&roles=library_admin&sort_by=role&order=asc&page=1&page_size=10

Example Response:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "is_superadmin": true,
            "role": "django.superuser",
            "org": "*",
            "scope": "*",
            "permission_count": null
        },
        {
            "is_superadmin": false,
            "role": "library_admin",
            "org": "Org1",
            "scope": "lib:Org1:LIB1",
            "permission_count": 11
        }
    ]
}
authentication_classes = [<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>]
filter_backends = [<class 'openedx_authz.rest_api.v1.filters.TeamMemberAssignmentsOrderingFilter'>]
get(request: HttpRequest, username: str) → Response

Retrieve all user role assignments.

pagination_class

alias of AuthZAPIViewPagination

permission_classes = [<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx_authz.rest_api.v1.permissions.AnyScopePermission'>]
class openedx_authz.rest_api.v1.views.TeamMembersAPIView(**kwargs)

Bases: APIView

API view for listing users in relation to role assignments. This API is used in the Team Members section in the Admin Console. In this context, a team member is anyone with studio access.

Endpoints

  • GET: Retrieve all users that have at least one role assignment

Query Parameters

  • scopes (Optional): Comma-separated list of scopes to filter by (e.g., ‘lib:Org1:LIB1’)

  • orgs (Optional): Comma-separated list of orgs to filter by (e.g., ‘Org1,Org2’)

  • search (Optional): Search term to filter users by username, full name, or email

  • sort_by (Optional): Field to sort by. Options: username, full_name, email. Defaults to username

  • order (Optional): Sort order, ‘asc’ or ‘desc’. Defaults to asc

  • page (Optional): Page number for pagination

  • page_size (Optional): Number of items per page

Response Format

Returns a paginated list of team member objects, each containing:

  • username: The user’s username

  • full_name: The user’s full name

  • email: The user’s email address

  • assignation_count: The number of role assignments the user has

Authentication and Permissions

  • Requires authenticated user.

  • Results are filtered according to calling user’s scope-level view permissions.

Example Request

GET /api/authz/v1/users/?orgs=Org1&search=john&sort_by=username&order=asc&page=1&page_size=10

Example Response:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "username": "jane_doe",
            "full_name": "Jane Doe",
            "email": "jane_doe@example.com",
            "assignation_count": 3
        },
        {
            "username": "john_doe",
            "full_name": "John Doe",
            "email": "john_doe@example.com",
            "assignation_count": 1
        }
    ]
}
authentication_classes = [<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>]
filter_backends = [<class 'openedx_authz.rest_api.v1.filters.TeamMemberSearchFilter'>, <class 'openedx_authz.rest_api.v1.filters.TeamMemberOrderingFilter'>]
get(request: HttpRequest) → Response

Retrieve all users that have at least one assignation according to the filtering fields.

pagination_class

alias of AuthZAPIViewPagination

permission_classes = [<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx_authz.rest_api.v1.permissions.AnyScopePermission'>]
class openedx_authz.rest_api.v1.views.UserValidationAPIView(**kwargs)

Bases: 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", "jane@example.com"],
    "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", "jane@example.com", "nonexistent_user"]
}
authentication_classes = [<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>]
permission_classes = [<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx_authz.rest_api.v1.permissions.AnyScopePermission'>]
post(request: HttpRequest) → Response

Validates the provided usernames or emails correspond to existing users.

Module contents#