openedx_authz.rest_api.v1.admin_console package#

Submodules#

openedx_authz.rest_api.v1.admin_console.filters module#

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

class openedx_authz.rest_api.v1.admin_console.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.admin_console.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.admin_console.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.admin_console.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.admin_console.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.admin_console.serializers module#

Serializers for the Admin Console REST API views.

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

Bases: ListTeamMemberAssignmentsQuerySerializer

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

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

Bases: OrgMixin

Serializer for validating query parameters in ScopesAPIView.

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

Bases: OrderMixin

Serializer for listing team member assignments.

class openedx_authz.rest_api.v1.admin_console.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.

ASSIGNMENTS_LIMIT_DEFAULT = 3
ASSIGNMENTS_LIMIT_MAX = 10
validate_assignments_limit(value: int) → int

Cap assignments_limit to the maximum allowed value.

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

Bases: Serializer

Mixin providing org field functionality.

class openedx_authz.rest_api.v1.admin_console.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.admin_console.serializers.TeamMemberAssignmentInlineSerializer(*args, **kwargs)

Bases: TeamMemberAssignmentSerializer

Compact serializer for assignment records inlined into the team-members response.

Reuses role, org, scope, and permission_count from TeamMemberAssignmentSerializer. Adds scope_display_name and drops is_superadmin which is not needed inline.

get_scope_display_name(_obj: RoleAssignmentData) → str

Return an empty placeholder; the view injects the real value post-pagination.

to_representation(instance)

Remove is_superadmin from the serialized output.

class openedx_authz.rest_api.v1.admin_console.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.admin_console.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_assignment_count(obj: UserAssignments) → int

Get the assignment count for the given role assignment.

get_assignments(obj: UserAssignments) → list[dict]

Return the first N assignment records, limited by assignments_limit from context.

get_email(obj: UserAssignments) → str

Get the email for the given role assignment.

get_full_name(obj: UserAssignments) → str

Get the full name from the UserProfile.

get_username(obj: UserAssignments) → str

Get the username for the given role assignment.

class openedx_authz.rest_api.v1.admin_console.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 the full name from the UserProfile.

get_username(obj: UserAssignmentData | SuperAdminAssignmentData) → str

Get username.

openedx_authz.rest_api.v1.admin_console.views module#

REST API views built for the Admin Console.

These views operate on Authorization’s own data (roles, permissions, assignments, scopes), but each is shaped around one specific Admin Console screen rather than being a reusable, consumer-agnostic operation. See docs/decisions/0026-rest-api-domain-ownership-boundary.rst.

class openedx_authz.rest_api.v1.admin_console.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

Results are limited to the orgs of the courses and libraries the requesting user has a role assignment in. Staff and superusers see every active org.

Authentication and Permissions

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

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 the active organizations visible to the requesting user, 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.admin_console.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"
        },
    ]
}
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.admin_console.filters.UserAssignmentsSearchFilter'>, <class 'openedx_authz.rest_api.v1.admin_console.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.admin_console.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-v1 and lib.

    course and library are accepted as deprecated aliases.

  • 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.admin_console.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:

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

  • org: The org over which this role is applied

  • scope: The scope over which this role is applied (stable machine identifier)

  • scope_display_name: Human-readable name of the scope (course display name or library title). Empty string for glob scopes or when the course/library no longer exists

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

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/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": [
        {
            "role": "library_admin",
            "org": "Org1",
            "scope": "lib:Org1:LIB1",
            "scope_display_name": "Intro to CS Library",
            "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.admin_console.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.admin_console.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

  • assignments_limit (Optional): Maximum number of assignments for each user. Defaults to 3, maximum 10

  • 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

  • assignment_count: The number of role assignments the user has

  • assignments: A list of the user’s role assignments (limited by assignments_limit), each containing:
    • role: The role name (e.g., ‘library_admin’)

    • org: The org over which this role is applied

    • scope: The scope over which this role is applied

    • scope_display_name: The human-readable display name for the scope (empty string for glob scopes or unresolvable resources)

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

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",
            "assignment_count": 3,
            "assignments": [
                {
                    "role": "library_admin",
                    "org": "Org1",
                    "scope": "lib:Org1:LIB1",
                    "scope_display_name": "Intro to CS Library",
                    "permission_count": 11
                },
                {
                    "role": "course_staff",
                    "org": "Org1",
                    "scope": "course-v1:Org1+CS101+2024",
                    "scope_display_name": "Introduction to Computer Science",
                    "permission_count": 27
                },
                {
                    "role": "library_admin",
                    "org": "Org1",
                    "scope": "lib:Org1:*",
                    "scope_display_name": "",
                    "permission_count": 11
                }
            ]
        },
        {
            "username": "john_doe",
            "full_name": "John Doe",
            "email": "john_doe@example.com",
            "assignment_count": 2,
            "assignments": [
                {
                    "role": "course_staff",
                    "org": "Org2",
                    "scope": "course-v1:Org2+*",
                    "scope_display_name": "",
                    "permission_count": 27
                },
                {
                    "role": "library_user",
                    "org": "*",
                    "scope": "lib:*",
                    "scope_display_name": "",
                    "permission_count": 4
                }
            ]
        }
    ]
}
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.admin_console.filters.TeamMemberSearchFilter'>, <class 'openedx_authz.rest_api.v1.admin_console.filters.TeamMemberOrderingFilter'>]
get(request: HttpRequest) → Response

Retrieve all users that have at least one assignment 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'>]

Module contents#

REST API views built for the Admin Console’s specific workflows.

These endpoints operate on Authorization’s own data (roles, permissions, assignments, scopes), but their shape is built around one consumer’s screens rather than being reusable as-is by any caller. Decision item 4 in ADR 0026 places them in a consumer-specific subpackage for data that still belongs to Authorization.