docs: Define api contract for User-Grouped role assignments by rodmgwgu · Pull Request #437 · openedx/openedx-authz

rodmgwgu · 2026-09-02T21:07:01Z

Closes: #405

The new Team Members tab design for the Admin Console requires fields that are not currently available in the API.

This ADR proposes the contract for updating the existing /api/authz/v1/users/ to support the new Team Members tab use cases.

Merge checklist:
Check off if complete or not applicable:

Version bumped
Changelog record added
Documentation updated (not only docstrings)
Fixup commits are squashed away
Unit tests added/updated
Manual testing instructions provided
Noted any: Concerns, dependencies, migration issues, deadlines, tickets

AI Usage

Kiro was used to refine the prose and clarity of the text, help with rst formatting, as well as to assist on research.

The core ADR contents and direction were drafted by hand.

openedx-webhooks · 2026-09-02T21:07:07Z

Thanks for the pull request, @rodmgwgu!

This repository is currently maintained by @openedx/committers-openedx-authz.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

dcoa · 2026-09-03T01:20:36Z

+
+Query Parameters:
+"""""""""""""""""
+


it is missing the roles filter

Suggested change

`roles`` (optional): Comma-separated list of roles to filter by (e.g. ``course_auditor,library_admin``).

Good catch, I've added it, thanks!

dcoa · 2026-09-03T04:38:11Z

+                       "is_superadmin": false,
+                       "role": "library_admin",
+                       "org": "Org1",
+                       "scope": "lib:Org1:LIB1",


the table shows the name of the scope instead of the id

Thanks for pointing this out. I added a new "scope_display_name" key and documented edge cases and implementation details.

carlos-marquez-wgu · 2026-09-03T18:33:55Z

+-  ``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.


What is the full name field here? Is this something visible in the UI?

edit: I see it is just the user's full name, wondering if we should allow to search by this given is not visible in the UI, it can return results where the search string isn't visible, I think it might be confusing but maybe no big deal

It's not being displayed in the design, but in past discussions with Guillermo we decided to include it in the search fields.

mariajgrimaldi

I agree with the current contract! I only have a few clarifying questions. Thanks a lot!

mariajgrimaldi · 2026-09-04T09:33:48Z

+Following that design, the view displays a table of users. Each row shows the
+username, email, a single scope the related assigned role, along with a control to
+expand the row and reveal up to three assigned roles and the user's total number
+of assigned roles.


I think pointing here to the public figma design will illustrate it better, at least to the most stable version of the design

I've been using this as reference: https://www.figma.com/design/xnmQJq1cTRVqNrs31R8zDM/AuthZ---v2?node-id=40000174-1081

I'm asking María de los Ángeles what would be the best link to add. Thanks for the suggestion.

Confirmed and added the link.

mariajgrimaldi · 2026-09-04T09:47:15Z

+           email: string
+           assignment_count: number
+           assignments: Array<{
+               is_superadmin: boolean


I thought we removed this while we properly support django staff / superuser. Here are the relevant issues:
#347
#345

Oh I wasn't aware of this, so we are no longer showing superadmins at all?

mariajgrimaldi · 2026-09-04T10:17:03Z

+               "full_name": "Jane Doe",
+               "email": "jane_doe@example.com",
+               "assignment_count": 3,
+               "assignments": [


I'm guessing this will return all types of assignments, right? Will the UI ever have a scope type filter?

Yes, all type of assignments, the UI as I understand it only filters by specific scopes, not by type, but let me confirm this with María de los Ángeles.

Confirmed by María de los Ángeles: it only filters by specific scopes.

mariajgrimaldi · 2026-09-04T10:20:20Z

+               "full_name": "Jane Doe",
+               "email": "jane_doe@example.com",
+               "assignment_count": 3,
+               "assignments": [


I thought assignments would be paginated, not only truncated.

EDIT: I see in the consequences that this won't be immediately supported.

Yes, not paginated, as the current UI design only shows a "preview" of the assignments, to see more, it links to the single user page which uses a different endpoint.

BryanttV

Thanks for working on this! I only have a couple of suggestions.

BryanttV · 2026-09-03T23:32:30Z

+The table can be searched by username, email, or full name; sorted by username or
+full name; filtered by organization, role, or scope; and is paginated.


And also sorted by email, right?

yes, it's mentioned latter but I forgot to add it here. Added now, thanks!

BryanttV · 2026-09-03T23:36:47Z

+   ``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 to populate in


Maybe we should set an upper limit for assignment_limit? That way, we prevent someone from requesting, for example, 1000 assignments with page_size=50, which could be quite expensive.

what would be a good number? maybe 10?

Yeah, I think 10 is fine.

BryanttV · 2026-09-04T13:06:00Z

+               is_superadmin: boolean
+               role: string
+               org: string
+               scope: string
+               scope_display_name: string
+               permission_count: number


I'd like to confirm if these fields in assignments are sufficient to display the information in the table correctly, especially when the scope is a Glob type (org and platform). I was thinking maybe it would be good to have a scope_type field?

cc @dcoa

BryanttV · 2026-09-04T13:07:28Z

+
+Example:
+
+.. code:: json


I think it would be good to include glob scopes in the example (org and platform)

Added examples for courses and glob scopes. Thanks for the suggestion!

…e-assignments.rst Co-authored-by: Bryann Valderrama <bryann.valderrama@edunext.co>

docs: Define api contract for Team Members tab

f6c3c87

openedx-webhooks added open-source-contribution PR author is not from Axim or 2U core contributor PR author is a Core Contributor (who may or may not have write access to this repo). labels Sep 2, 2026

openedx-webhooks added this to Contributions Sep 2, 2026

github-project-automation Bot moved this to Needs Triage in Contributions Sep 2, 2026

rodmgwgu requested review from BryanttV, mariajgrimaldi and wgu-taylor-payne September 2, 2026 21:07

mphilbrick211 added the mao-onboarding Reviewing this will help onboard devs from an Axim mission-aligned organization (MAO). label Sep 2, 2026

mphilbrick211 moved this from Needs Triage to Ready for Review in Contributions Sep 2, 2026

dcoa reviewed Sep 3, 2026

View reviewed changes

carlos-marquez-wgu reviewed Sep 3, 2026

View reviewed changes

squash!: Attend PR comments

fad654a

mariajgrimaldi reviewed Sep 4, 2026

View reviewed changes

BryanttV requested changes Sep 4, 2026

View reviewed changes

rodmgwgu and others added 6 commits September 4, 2026 09:14

squash!: Update docs/decisions/0024-api-contract-for-user-grouped-rol…

89d8470

…e-assignments.rst Co-authored-by: Bryann Valderrama <bryann.valderrama@edunext.co>

squash!: Update docs/decisions/0024-api-contract-for-user-grouped-rol…

f8ed179

…e-assignments.rst Co-authored-by: Bryann Valderrama <bryann.valderrama@edunext.co>

squash!: Update docs/decisions/0024-api-contract-for-user-grouped-rol…

c1aba85

…e-assignments.rst Co-authored-by: Bryann Valderrama <bryann.valderrama@edunext.co>

squash!: Update docs/decisions/0024-api-contract-for-user-grouped-rol…

5258a21

…e-assignments.rst Co-authored-by: Bryann Valderrama <bryann.valderrama@edunext.co>

squash!: Attend PR comments

0d3dde8

squash!: Add figma link

782591f


	`roles`` (optional): Comma-separated list of roles to filter by (e.g. ``course_auditor,library_admin``).

		The table can be searched by username, email, or full name; sorted by username or
		full name; filtered by organization, role, or scope; and is paginated.


		Query Parameters:
		"""""""""""""""""

Uh oh!

Conversation

rodmgwgu commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openedx-webhooks commented Sep 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carlos-marquez-wgu Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mariajgrimaldi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BryanttV left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

rodmgwgu commented Sep 2, 2026 •

edited

Loading

carlos-marquez-wgu Sep 3, 2026 •

edited

Loading