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 returns the requested scopes. 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.

Implementation PR

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

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)

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

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

dcoa

it looks good so far, just 1 change and some questions.

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>

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>

Frame the API as the source of truth for the descriptive information of the authz model instead of around the current matrix UI. The same data also feeds the permissions sub-table and the wizard role list, so generalize the remaining matrix-specific wording. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Rename the response scope_types to scopes using backend namespaces (course-v1, lib) and add scopes to each permission. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Match the field name used by the authz schema. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Describe extracting the logic shared with AnyScopePermission instead of duplicating it in the permission of the role catalog endpoint. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

mariajgrimaldi

LGTM! Thanks so much for addressing my comments :)

rodmgwgu

Looks good, thanks!

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

Closed

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

Comment thread docs/decisions/0028-api-contract-for-role-catalog.rst

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

3 of 5 tasks

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

dcoa reviewed Oct 6, 2026

View reviewed changes

Comment thread docs/decisions/0028-api-contract-for-role-catalog.rst Outdated

Comment thread docs/decisions/0028-api-contract-for-role-catalog.rst

Comment thread docs/decisions/0028-api-contract-for-role-catalog.rst Outdated

BryanttV and others added 6 commits October 6, 2026 12:44

docs: note scope registry as future work in ADR 0028

766cbd5

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

6220a76

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>

docs: return scopes in the role catalog response in ADR 0028

45b3db7

Rename the response scope_types to scopes using backend namespaces (course-v1, lib) and add scopes to each permission. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

BryanttV force-pushed the bav/roles-catalog-api-adr branch from bd25133 to 45b3db7 Compare October 6, 2026 17:44

BryanttV requested a review from dcoa October 6, 2026 17:46

docs: rename permission category to category_id in ADR 0028

fc1b409

Match the field name used by the authz schema. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

mariajgrimaldi requested changes Oct 7, 2026

View reviewed changes

BryanttV and others added 4 commits October 7, 2026 17:28

docs: reuse shared permission logic for the role catalog in ADR 0028

8d80e83

Describe extracting the logic shared with AnyScopePermission instead of duplicating it in the permission of the role catalog endpoint. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs: use scope namespaces as the scope type naming in ADR 0028

4938650

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs: remove user_count from the role catalog in ADR 0028

8ccb137

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs: simplify permission fields and localization in ADR 0028

39c7043

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

BryanttV requested a review from mariajgrimaldi October 8, 2026 16:31

mariajgrimaldi approved these changes Oct 8, 2026

View reviewed changes

rodmgwgu approved these changes Oct 8, 2026

View reviewed changes

BryanttV merged commit 8de7971 into main Oct 8, 2026
8 checks passed

BryanttV deleted the bav/roles-catalog-api-adr branch October 8, 2026 21:36

Navigation Menu

Repository navigation

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 merged 11 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!

Uh oh!

rodmgwgu left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dcoa left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mariajgrimaldi left a comment

Uh oh!

rodmgwgu left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 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

Implementation PR

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!

Uh oh!

rodmgwgu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dcoa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mariajgrimaldi left a comment

Choose a reason for hiding this comment

Uh oh!

rodmgwgu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

BryanttV commented Sep 30, 2026 •

edited

Loading

openedx-webhooks commented Sep 30, 2026 •

edited

Loading