Update required scopes of application and role mgt APIs #5763
Conversation
WalkthroughExpanded OpenAPI documentation across several organization and application API specs: added "Additional Scopes" sections with new internal scopes, refined component schema descriptions, and updated OpenAPI/version metadata in role-related YAMLs. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🔇 Additional comments (4)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (4)
en/asgardeo/docs/apis/restapis/application-management.yaml (2)
1668-1718: OIDC PUT example — minor typo and trailing backslash.Sample URL path contains “{appplication-id}” elsewhere in the file; if you touch this next, fix the triple “p”. Also ensure the header line backslash has a trailing space to avoid rendering issues.
3510-3513: Query param casing consistency (“Supported values”).Tiny nit: start with capital “Supported values” to match house style elsewhere.
en/asgardeo/docs/apis/organization-apis/restapis/org-application-mgt.yaml (2)
467-479: Minor grammatical issue in endpoint description.Line 467 has an awkward phrasing: "authorized an API to the application" should be "authorize an API to the application" (use the base verb form in the infinitive context). The Additional Scopes documentation structure and table format are well-formatted and provide helpful clarity.
- This API provides the capability to authorized an API to the application. + This API provides the capability to authorize an API to the application.
536-548: Consistent Additional Scopes documentation pattern.The PATCH endpoint's Additional Scopes section follows the same well-structured format as the POST endpoint. Consider removing the extra blank lines (536-541) for more concise YAML formatting.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
en/asgardeo/docs/apis/organization-apis/restapis/org-application-mgt.yaml(7 hunks)en/asgardeo/docs/apis/organization-apis/restapis/role-management.yaml(4 hunks)en/asgardeo/docs/apis/restapis/application-management.yaml(41 hunks)en/asgardeo/docs/apis/restapis/roles.yaml(4 hunks)
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: Thisara-Welmilla
Repo: wso2/docs-is PR: 5732
File: en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-update-profile-action-v1.x.md:273-273
Timestamp: 2025-12-01T15:31:14.922Z
Learning: In the wso2/docs-is repository documentation files, prefer unhyphenated compound adjectives (e.g., "SCIM API compliant", "Admin initiated profile update") over hyphenated versions for better readability and natural flow.
🔇 Additional comments (19)
en/asgardeo/docs/apis/organization-apis/restapis/role-management.yaml (3)
4-4: Version metadata added — LGTM.info.version: v2 improves discoverability; ensure downstream navigation/renderers read this field.
1-1: OpenAPI version downgraded to 3.0.0 — verify tooling requirement and consistency.Confirm whether this downgrade is required by a tooling constraint. If not, align with the version used in other OpenAPI specs in the repository for consistency. If the downgrade is intentional, document the reason in the PR description.
95-113: Additional Scopes table — verified and accurate.All three scope keys are documented in Asgardeo's official scope registry:
internal_org_role_mgt_permissions_update— enables updating role metadata and permissionsinternal_org_role_mgt_users_update— enables assigning/removing users to/from rolesinternal_org_role_mgt_groups_update— enables assigning/removing groups to/from rolesThe mapping of actions to scopes is correct per Asgardeo documentation.
en/asgardeo/docs/apis/restapis/application-management.yaml (10)
296-312: Import application — additional scope and “Recommendation” — LGTM.Consistent with create flow; no schema impact.
364-377: Import update — additional scope — LGTM.Consistent wording; keep using the dedicated script endpoint for edits.
1017-1028: Authorized APIs PATCH — additional scopes — LGTM.Consistent with POST; no schema impact.
1091-1102: Authorized APIs DELETE — additional scopes — LGTM.Consistent wording across CRUD.
1552-1564: OIDC GET — “view client secret” additional scope — LGTM.Good to make secret-view explicit via separate scope.
495-510: PATCH application — additional scope + authentication script recommendationLGTM. The additional scope documentation and recommendation to use the
/applications/{applicationId}/authenticationSequence/scriptendpoint are appropriate. Verify that the anchor#tag/Applications/operation/updateAuthenticationScriptexists in the OpenAPI specification.
74-88: Create application — scope section addition looks good.Good separation between base and additional scope; link recommendation is helpful. Verify the anchor '#tag/Applications/operation/updateAuthenticationScript' exists in the YAML (check for
operationId: updateAuthenticationScriptunder tagApplications) and test the link in the built documentation to confirm it resolves correctly.
688-700: Export application — client secret view scope block — LGTM.Nice clarity on viewing client secrets; ensure the scope key
internal_application_mgt_client_secret_viewmatches server-side enforcement.
1781-1786: Verify scope naming —internal_application_mgt_client_secret_createfollows Asgardeo conventions but needs confirmation.The scope name follows the established
internal_application_mgt_*pattern used in Asgardeo, and the_createsuffix aligns with action-based naming. However, explicit documentation for this specific scope was not found in public sources. Confirm with the API team or internal scope registry that this is the correct and current scope before finalizing documentation references.
3400-3612: Add automated linting to catch specification issues.Run a linter on the OpenAPI specification file to flag potential typos, schema inconsistencies, and structural issues early in the review process.
#!/bin/bash # Lint the Application Management OpenAPI spec npx @redocly/cli@latest lint en/asgardeo/docs/apis/restapis/application-management.yamlen/asgardeo/docs/apis/restapis/roles.yaml (2)
3-4: Title/version metadata — LGTM.Matches the V2 surface while keeping deprecation note in description.
104-115: Verify and clarify the permissions scope name — likely needs correction for Roles V3.The scopes
internal_role_mgt_users_updateandinternal_role_mgt_groups_updateare confirmed in Asgardeo documentation. However,internal_role_mgt_permissions_updaterequires clarification: Asgardeo's Roles V3 (SCIM2) API replaced the singleinternal_role_mgt_updatescope with split scopes, usinginternal_role_mgt_meta_updatefor permission/metadata updates rather thaninternal_role_mgt_permissions_update. Verify whether this documentation applies to Roles V2 or V3, and confirm the correct scope name matches the Asgardeo Console's actual enumeration for the target API version.en/asgardeo/docs/apis/organization-apis/restapis/org-application-mgt.yaml (4)
611-622: Additional Scopes section consistent across all authorized-apis endpoints.The DELETE endpoint's Additional Scopes documentation maintains consistency with POST and PATCH endpoints. This pattern across the three related endpoints provides clear action-to-scope mappings for API consumers.
932-935: Updated scope for client secret regeneration is appropriate.The new scope
internal_org_application_mgt_client_secret_createproperly separates regeneration permissions from viewing permissions, aligning with the GET endpoint's use ofinternal_org_application_mgt_client_secret_view. The naming convention is consistent throughout the API specification.
1957-1967: Improved clarity in AccessTokenConfiguration descriptions.The refinements to the
bindingType,revokeTokensWhenIDPSessionTerminated, andvalidateTokenBindingdescriptions provide better clarity to API consumers about the conditional behavior and validation requirements. The phrasing is now more explicit and actionable.
2085-2089: AuthenticationSequence description improved with HTML list structure.The conversion from YAML bullet format to HTML unordered list provides better formatting and clarity for API consumers. The update correctly references "organization-level default sequence," which aligns with the PR's focus on organization-level API documentation enhancements.
Please verify that the HTML unordered list has proper closing tags (the provided snippet ends at line 2089; ensure
</ul>is included after line 2089).
| description: | | ||
| This API provides the capability to retrieve OIDC authentication protocol parameters of an application. <br> | ||
| <b>Scope(Permission) required:</b> `internal_org_application_mgt_view` | ||
| <b>Scope(Permission) required:</b> | ||
| - `internal_org_application_mgt_view` | ||
| <b>➕ Additional Scopes</b> | ||
| To view the client secret, you also need the following additional scope: | ||
| | Action | Scope | | ||
| |---------|--------| | ||
| | View client secret | `internal_org_application_mgt_client_secret_view` | |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Indentation inconsistency in GET OIDC description.
Line 716 has unusual indentation for "Scope(Permission) required:" that differs from the POST/PATCH/DELETE endpoints. For consistency, align the scope requirement indicator at the same indentation level as the "➕ Additional Scopes" marker on line 719.
description: |
This API provides the capability to retrieve OIDC authentication protocol parameters of an application. <br>
-
- <b>Scope(Permission) required:</b>
+
+ <b>Scope(Permission) required:</b>
- `internal_org_application_mgt_view`
-
+
<b>➕ Additional Scopes</b>
-
+
To view the client secret, you also need the following additional scope:
-
+
| Action | Scope |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| description: | | |
| This API provides the capability to retrieve OIDC authentication protocol parameters of an application. <br> | |
| <b>Scope(Permission) required:</b> `internal_org_application_mgt_view` | |
| <b>Scope(Permission) required:</b> | |
| - `internal_org_application_mgt_view` | |
| <b>➕ Additional Scopes</b> | |
| To view the client secret, you also need the following additional scope: | |
| | Action | Scope | | |
| |---------|--------| | |
| | View client secret | `internal_org_application_mgt_client_secret_view` | | |
| description: | | |
| This API provides the capability to retrieve OIDC authentication protocol parameters of an application. <br> | |
| <b>Scope(Permission) required:</b> | |
| - `internal_org_application_mgt_view` | |
| <b>➕ Additional Scopes</b> | |
| To view the client secret, you also need the following additional scope: | |
| | Action | Scope | | |
| |---------|--------| | |
| | View client secret | `internal_org_application_mgt_client_secret_view` | |
🤖 Prompt for AI Agents
In en/asgardeo/docs/apis/organization-apis/restapis/org-application-mgt.yaml
around lines 713 to 725, the "Scope(Permission) required:" line is indented more
than the "➕ Additional Scopes" marker, causing inconsistency with
POST/PATCH/DELETE endpoints; outdent the "Scope(Permission) required:" line to
match the same indentation level as the "➕ Additional Scopes" marker and the
surrounding section headers so the bullet and subsequent scope list align
consistently with other endpoint descriptions.
| <b>Scope(Permission) required:</b> | ||
| - `internal_application_mgt_update` | ||
| <b>➕ Additional Scopes</b> | ||
| To authorize management/organization APIs and business APIs, you also need the following additional scopes: | ||
| | Action | Scope | | ||
| |---------|--------| | ||
| | Authorize management/organization API | `internal_application_internal_api_update` | | ||
| | Authorize business APIs | `internal_application_business_api_update` | | ||
| parameters: |
There was a problem hiding this comment.
Fix spacing and verb in Authorized APIs POST description.
There’s an extra space before “business” and the verb form in the description above should be “authorize” (not “authorized”).
- | Authorize business APIs | `internal_application_business_api_update` |
+ | Authorize business APIs | `internal_application_business_api_update` |If you’re touching the adjacent description, prefer: “This API provides the capability to authorize an API for the application.”
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <b>Scope(Permission) required:</b> | |
| - `internal_application_mgt_update` | |
| <b>➕ Additional Scopes</b> | |
| To authorize management/organization APIs and business APIs, you also need the following additional scopes: | |
| | Action | Scope | | |
| |---------|--------| | |
| | Authorize management/organization API | `internal_application_internal_api_update` | | |
| | Authorize business APIs | `internal_application_business_api_update` | | |
| parameters: | |
| <b>Scope(Permission) required:</b> | |
| - `internal_application_mgt_update` | |
| <b>➕ Additional Scopes</b> | |
| To authorize management/organization APIs and business APIs, you also need the following additional scopes: | |
| | Action | Scope | | |
| |---------|--------| | |
| | Authorize management/organization API | `internal_application_internal_api_update` | | |
| | Authorize business APIs | `internal_application_business_api_update` | | |
| parameters: |
🤖 Prompt for AI Agents
en/asgardeo/docs/apis/restapis/application-management.yaml around lines 948 to
959: fix the wording and spacing in the Additional Scopes table and adjacent
description — remove the extra space before “business” in the “Authorize
business APIs” cell, change any instance of the verb “authorized” in the
POST/description to “authorize”, and if you edit the surrounding description
replace it with: “This API provides the capability to authorize an API for the
application.”
| description: | | ||
| This API updates the role details and returns the updated role details | ||
| using a PUT operation. | ||
| <b>Scope(Permission) required:</b> `internal_role_mgt_update` | ||
| <b>Scope(Permission) required:</b> | ||
| - `internal_role_mgt_update` | ||
| <b>➕ Additional Scopes</b> | ||
| To update permissions, users, or groups assignments of the role, you also need the following additional scopes: | ||
| | Action | Scope | | ||
| |---------|--------| | ||
| | Update permissions | `internal_role_mgt_permissions_update` | | ||
| | Update users | `internal_role_mgt_users_update` | | ||
| | Update groups | `internal_role_mgt_groups_update` | | ||
| operationId: updateRoleV2 |
There was a problem hiding this comment.
Tighten PUT description phrasing.
Avoid “assignments of the role” redundancy; prefer concise wording.
- To update permissions, users, or groups assignments of the role, you also need the following additional scopes:
+ To update the role’s permissions, users, or groups, you also need the following additional scopes:🤖 Prompt for AI Agents
In en/asgardeo/docs/apis/restapis/roles.yaml around lines 313 to 329, the PUT
operation description is wordy and repeats “assignments of the role”; update the
phrasing to be concise by replacing the sentence "To update permissions, users,
or groups assignments of the role, you also need the following additional
scopes:" with a leaner variant such as "To update the role's permissions, users,
or groups, you also need the following additional scopes:" and keep the table
and scope names unchanged.
| description: | | ||
| This API updates the role details and returns the updated role details | ||
| using a PATCH operation. | ||
| <b>Scope(Permission) required:</b> `internal_role_mgt_update` | ||
| <b>Scope(Permission) required:</b> | ||
| - `internal_role_mgt_update` | ||
| <b>➕ Additional Scopes</b> | ||
| To update permissions, users, or groups assignments of the role, you also need the following additional scopes: | ||
| | Action | Scope | | ||
| |---------|--------| | ||
| | Update permissions | `internal_role_mgt_permissions_update` | | ||
| | Update users | `internal_role_mgt_users_update` | | ||
| | Update groups | `internal_role_mgt_groups_update` | |
There was a problem hiding this comment.
Mirror the phrasing fix in PATCH description.
Keep PUT/PATCH wording consistent.
- To update permissions, users, or groups assignments of the role, you also need the following additional scopes:
+ To update the role’s permissions, users, or groups, you also need the following additional scopes:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| description: | | |
| This API updates the role details and returns the updated role details | |
| using a PATCH operation. | |
| <b>Scope(Permission) required:</b> `internal_role_mgt_update` | |
| <b>Scope(Permission) required:</b> | |
| - `internal_role_mgt_update` | |
| <b>➕ Additional Scopes</b> | |
| To update permissions, users, or groups assignments of the role, you also need the following additional scopes: | |
| | Action | Scope | | |
| |---------|--------| | |
| | Update permissions | `internal_role_mgt_permissions_update` | | |
| | Update users | `internal_role_mgt_users_update` | | |
| | Update groups | `internal_role_mgt_groups_update` | | |
| description: | | |
| This API updates the role details and returns the updated role details | |
| using a PATCH operation. | |
| <b>Scope(Permission) required:</b> | |
| - `internal_role_mgt_update` | |
| <b>➕ Additional Scopes</b> | |
| To update the role's permissions, users, or groups, you also need the following additional scopes: | |
| | Action | Scope | | |
| |---------|--------| | |
| | Update permissions | `internal_role_mgt_permissions_update` | | |
| | Update users | `internal_role_mgt_users_update` | | |
| | Update groups | `internal_role_mgt_groups_update` | |
🤖 Prompt for AI Agents
In en/asgardeo/docs/apis/restapis/roles.yaml around lines 455 to 471, the PATCH
operation description uses wording that is inconsistent with the PUT
description; update the PATCH description to mirror the exact phrasing used for
the PUT endpoint (use the same concise verb tense and structure), ensure scopes
and the "Additional Scopes" section match the PUT formatting and labels, and
keep references to required scopes (`internal_role_mgt_update` and the three
additional scopes) identical in wording and table format so PUT/PATCH
descriptions are consistent.
en/asgardeo/docs/apis/organization-apis/restapis/org-application-mgt.yaml
Outdated
Show resolved
Hide resolved
…nt.yaml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
3 participants
Purpose
$Subject
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.