docs: add ADR 0028 API contract for the role and permission catalog by BryanttV · Pull Request #508 · openedx/openedx-authz

BryanttV · 2026-09-30T22:53:16Z

Description

Adds ADR 0028, which defines the response contract of GET /api/authz/v1/roles/ when queried by scope_types. ADR 0021 decided that this endpoint returns the definitions stored in the authz model, but left the exact response shape open. This ADR defines it.

The Roles and Permissions tab of the Admin Console renders a matrix (roles × permissions grouped by category) for one or more scope types at a time. Today the frontend hardcodes all of this (course/constants.ts, library/constants.ts). The matrix needs every permission of the requested scope types, including the ones a role does not grant, so a list of roles that only carries the permissions each one grants is not enough.

Key decisions

Query by scope_types (required): a comma-separated list of course and/or library, with at least one value. Duplicates are collapsed. An empty item or an unsupported value returns a 400. The scope parameter is removed.
Authorization per scope type: courses.view_course_team for course and content_libraries.view_library_team for library, in any scope. When several scope types are requested, the user must hold the permission for each one. This needs a new permission class, since DynamicScopePermission and AnyScopePermission cannot express it.
Union across scope types: permissions contains the permissions supported by any requested scope type. A role is listed if it has grants in any of them, and its permissions are the ones it grants across them.
Normalized response: the categories and permissions catalogs are sent once, and each role references permissions by id. The response echoes the requested scope_types. The client can build each matrix cell directly.
Pagination applies to roles only: every page carries the complete catalogs.
user_count is calculated across the requested scope types and counts distinct users, not a single scope.
Data source: the authz schema models, not raw Casbin rows. hidden roles (ADR 0023) are excluded, and roles without a stored definition are not listed.

Manual testing

Documentation only. To review, read docs/decisions/0028-api-contract-for-role-catalog.rst or check the docs.

Merge checklist

Documentation updated (not only docstrings)
Fixup commits are squashed away
Unit tests added/updated (n/a, docs only)
Manual testing instructions provided
Noted any: Concerns, dependencies, migration issues, deadlines, documented above)

Define the response of GET /api/authz/v1/roles/ queried by scope_type, returning paginated roles with the categories and permissions catalogs needed by the Admin Console roles and permissions matrix. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

openedx-webhooks · 2026-09-30T22:53:22Z

Thanks for the pull request, @BryanttV!

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.

rodmgwgu · 2026-10-01T17:06:29Z

+translated. Since the body depends on the request language, the response must vary on
+``Accept-Language``.
+
+Icons are Paragon icon names (validated by the schema, see `ADR 0026`_). The client maps


Just to keep in mind: There is already a ADR 0026 that is not related to paragon icons, I'll change the number on my PR, this will need updating once my PR is merged.

rodmgwgu

Overall looking good, Added some comments for consideration. Thanks!

rodmgwgu · 2026-10-01T17:14:07Z

+``library`` (``ScopesTypeField``). The catalog describes what a scope type offers, not a
+particular course or library, so a concrete scope is not needed.
+
+* ``scope_type`` is required. Unlike ``/scopes/``, a request without it is invalid (400)


I'm thinking that perhaps we should support a "scope_types" param instead, that accepts a list of scope types.

This for supporting future requirements, like listing the roles dynamically for assignments, when we enable support for roles with multiple scope types.

Good point, thanks. I agree it's cheaper to settle this now, while no released client calls the endpoint, than to introduce a second breaking change when roles with multiple scope types arrive.

I'd update the ADR as follows:

The query parameter becomes scope_types: a required list with at least one value, each one of course or library (e.g. ?scope_types=course,library). Empty values and unknown values return 400.

Semantics: a role is returned if it has grants in any of the requested scope types (OR). permissions and categories are the union of those used by the requested types, and a role's permissions lists its grants in those namespaces.

Authorization: the user must hold the corresponding view-team permission for each requested scope type (in any scope, as today), so a request can't expose roles of a type the user can't see.

user_count: counts the users assigned to the role across the requested scope types.

Response: scope_type becomes scope_types: Array<"course" | "library">.

The Roles and Permissions tab keeps sending a single value, since one matrix still can't mix course and library roles. The list is what the dynamic role listing for assignments will use.

What do you think?

Here is the change: 6e9ce37

rodmgwgu · 2026-10-01T17:16:28Z

+
+* ``scope_type`` is required. Unlike ``/scopes/``, a request without it is invalid (400)
+  because one matrix cannot mix course and library roles.
+* The scope type is mapped to its scope namespace (``course`` to ``course-v1``, ``library``


Not necessarily for now, but to keep in mind: How would we handle this mapping if we introduce new scopes in the future? specially when the scope is not defined by authz itself?

Good question. I think ideally we should pull the scope types from the existing scope_registry, maybe using the NAMESPACE as the key. That way, any plugin could contribute a scope type without modifying authz. What do you think?

I added a note: 2677b7e

rodmgwgu · 2026-10-01T17:17:59Z

+Authorization
+=============
+
+The permission needed depends on the requested ``scope_type``, so a user cannot read the


If we change this to "scope_types", then should we check for permissions on all the requested scope types inclusive? or just filter the output to only what the user can view?

I mentioned this in this comment. What do you think?

rodmgwgu · 2026-10-01T17:24:57Z

+* A new permission class is needed for the per-scope-type authorization.
+* ``definition_kind`` is reserved for user-defined roles. Their storage, the translation of
+  their names and any source detail remain out of scope.
+* A role present in the Casbin policy but with no stored definition cannot be described. It


I think if a role is present in Casbin but not stored, then we should not show it. Otherwise the filtering and pagination will become much more complex as we will need to query Casbin in addition to the DB.

I agree. I updated the ADR: bd25133

Record that scope types could later be resolved from scope_registry so plugins can contribute new ones, while course and library stay explicit for now. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Replace scope_type with a comma-separated scope_types parameter so the catalog can later serve roles with multiple scope types. A role is returned if it has grants in any requested type, and the user needs the view-team permission of each one. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Roles that exist only in the Casbin policy are no longer listed, so the catalog reads only from the database and filtering and pagination stay in a single query. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

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 30, 2026

openedx-webhooks added this to Contributions Sep 30, 2026

BryanttV linked an issue Sep 30, 2026 that may be closed by this pull request

Role and permission metadata (Catalog API) #413

Open

This was referenced Oct 1, 2026

Implement extraction and translation of static YAML authz metadata (Internationalization) #432

Open

feat: extract translatable strings from the authz schema #509

Open

BryanttV marked this pull request as ready for review October 1, 2026 15:14

BryanttV requested review from dcoa, mariajgrimaldi and rodmgwgu October 1, 2026 16:59

rodmgwgu reviewed Oct 1, 2026

View reviewed changes

rodmgwgu requested changes Oct 1, 2026

View reviewed changes

BryanttV mentioned this pull request Oct 1, 2026

feat: serve the role and permission catalog by scope type #510

Open

5 tasks

BryanttV and others added 3 commits October 2, 2026 10:39

docs: note scope registry as future work in ADR 0028

2677b7e

Record that scope types could later be resolved from scope_registry so plugins can contribute new ones, while course and library stay explicit for now. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs: omit roles without a stored definition in ADR 0028

bd25133

Roles that exist only in the Casbin policy are no longer listed, so the catalog reads only from the database and filtering and pagination stay in a single query. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

BryanttV requested a review from rodmgwgu October 2, 2026 15:52

Navigation Menu

docs: add ADR 0028 API contract for the role and permission catalog - #508

docs: add ADR 0028 API contract for the role and permission catalog#508
BryanttV wants to merge 4 commits into
mainfrom
bav/roles-catalog-api-adr

BryanttV commented Sep 30, 2026 •

edited

Loading

Uh oh!

openedx-webhooks commented Sep 30, 2026 •

edited

Loading

Uh oh!

rodmgwgu Oct 1, 2026

Uh oh!

rodmgwgu left a comment

Uh oh!

rodmgwgu Oct 1, 2026

Uh oh!

BryanttV Oct 2, 2026

Uh oh!

BryanttV Oct 2, 2026

Uh oh!

rodmgwgu Oct 1, 2026

Uh oh!

BryanttV Oct 2, 2026

Uh oh!

BryanttV Oct 2, 2026

Uh oh!

rodmgwgu Oct 1, 2026

Uh oh!

BryanttV Oct 2, 2026

Uh oh!

rodmgwgu Oct 1, 2026

Uh oh!

BryanttV Oct 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

Description

Key decisions

Manual testing

Merge checklist

Uh oh!

openedx-webhooks commented Sep 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rodmgwgu 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

BryanttV commented Sep 30, 2026 •

edited

Loading

openedx-webhooks commented Sep 30, 2026 •

edited

Loading