Update organization application doc with authorization code grant support and improve structure #5787
Conversation
WalkthroughDocumentation shifts organization-application onboarding to a console-first flow for eligible products/versions, adds product-version conditional grant allowances (including authorization_code for Asgardeo/WSO2 >7.2.0), and supplies explicit token generation, introspection, revocation examples while templating root-organization URLs. Changes
Sequence Diagram(s)sequenceDiagram
participant Dev as Developer/Admin
participant Console as Management Console
participant API as Organization API
participant Authz as Authorization Server
rect rgba(50,115,220,0.06)
Note over Console,Authz: Console-driven onboarding (conditional by product/version)
end
Dev->>Console: Create org application (select template & grants)
Console->>API: POST /organizations/{id}/applications (app metadata)
API-->>Console: 201 Created (app metadata, client_id, client_secret?)
alt Authorization Code (Asgardeo/WSO2 >7.2.0)
Dev->>Authz: GET /authorize (consent)
Authz-->>Dev: Redirect with authorization_code
Dev->>Authz: POST /token (grant_type=authorization_code, code, redirect_uri)
Authz-->>Dev: access_token + refresh_token (JSON)
else Client Credentials / Password / Refresh
Dev/Console->>Authz: POST /token (client_credentials | password | refresh_token)
Authz-->>Dev/Console: access_token (JSON)
end
Dev->>Authz: POST /introspect (token)
Authz-->>Dev: token active? (JSON)
Dev->>Authz: POST /revoke (token)
Authz-->>Dev: 200 OK
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
en/includes/guides/organization-management/organization-applications.md (1)
84-175: Remove/replace sample secrets/tokens and avoid insecure curl patterns (-k)
Multiple “Sample request” blocks include what appear to be realcurl --user <client_id>:<client_secret>values and token-like strings (also flagged by Gitleaks). These should be replaced with clearly fake placeholders (or obvious non-secret dummy values), and the PR checklist about not committing secrets should be completed accordingly. Also,-kdisables TLS verification; remove it or explicitly call out it’s for local/testing only and not recommended.Proposed doc-safe diff (illustrative; apply similarly to all sample blocks that contain secrets/tokens):
- curl --user 7wYeybBGCVfLxPmS0z66WNMffyMa:WYfwHUsbsEvwtqmDLuaxF_VCQJwa -k + curl --user <APPLICATION_CLIENT_ID>:<APPLICATION_CLIENT_SECRET> -d "grant_type=authorization_code&code=<AUTHORIZATION_CODE>&redirect_uri=https://bestcarmart.com/login" -H "Content-Type: application/x-www-form-urlencoded" {{ root_org_url }}/o/7e98b86f-63c7-41a1-8c56-c909a21a2615/oauth2/tokenAlso applies to: 176-208, 211-270
🧹 Nitpick comments (1)
en/includes/guides/organization-management/organization-applications.md (1)
9-10: Keep grant-type/template restrictions, but ensure they’re defined/linked and consistent across sections
You repeat the same “only authorization code, client credentials, password and refresh” + “only Standard-Based / M2M templates” constraints twice; consider defining once and referencing it, or ensure both sections stay in sync as the product evolves.Also applies to: 58-60
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (6)
en/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.png
📒 Files selected for processing (1)
en/includes/guides/organization-management/organization-applications.md(6 hunks)
🧰 Additional context used
🪛 Gitleaks (8.30.0)
en/includes/guides/organization-management/organization-applications.md
[high] 132-132: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 121-121: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 156-156: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 190-190: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 224-224: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 223-223: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 260-260: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
🪛 LanguageTool
en/includes/guides/organization-management/organization-applications.md
[grammar] ~174-~174: Ensure spelling is correct
Context: ... you need the scopes with the response, the add the scope path parameter to the t...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~207-~207: Ensure spelling is correct
Context: ... you need the scopes with the response, the add the scope path parameter to the t...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (2)
en/includes/guides/organization-management/organization-applications.md (2)
139-141: Refresh token note: ensure it matches actual product behavior for auth code
The note says refresh tokens require enabling “refresh token grant” in Protocol. Please double-check whether refresh tokens are also subject to client/app settings (and/or offline_access scope) in your product’s current behavior, and adjust the note if needed.
86-138: Rendering compatibility: confirm tab/admonition syntax is supported on this docs site
This file uses=== "Request format"tab blocks and!!! noteadmonitions; please confirm the site pipeline foren/includes/...renders these correctly (and that indentation is correct), otherwise readers may see raw markup.Also applies to: 144-172, 178-205, 211-245, 248-270
en/includes/guides/organization-management/organization-applications.md
Outdated
Show resolved
Hide resolved
en/includes/guides/organization-management/organization-applications.md
Outdated
Show resolved
Hide resolved
ShanChathusanda93
force-pushed
the
sub-org-app-auth-code-branch
branch
from
0d9e1ba to
fe8d3e5
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
en/includes/guides/organization-management/organization-applications.md (1)
206-208: Unresolved grammar and parameter clarity issue (duplicate of previous review feedback).Line 207 still contains the grammar and parameter description issues flagged in the previous review. The text reads:
"the add thescopepath parameter"which should be"add thescopeparameter". Additionally, scope is a form/body parameter (or query parameter for the authorize endpoint), not a path parameter.Compare with line 174, which was correctly fixed:
"add thescopeparameter to the token request"— apply the same fix here.- If you need the scopes with the response, the add the `scope` path parameter to the token request with the required scopes. + If you need scopes in the response, add the `scope` parameter to the token request with the required scopes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (6)
en/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.png
📒 Files selected for processing (1)
en/includes/guides/organization-management/organization-applications.md(5 hunks)
🧰 Additional context used
🪛 Gitleaks (8.30.0)
en/includes/guides/organization-management/organization-applications.md
[high] 132-132: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 121-121: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 156-156: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 190-190: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 224-224: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 223-223: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 260-260: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
🪛 LanguageTool
en/includes/guides/organization-management/organization-applications.md
[grammar] ~75-~75: Use a hyphen to join words.
Context: ...r organization applications. - Protocol level configurations - User attributes r...
(QB_NEW_EN_HYPHEN)
[grammar] ~207-~207: Ensure spelling is correct
Context: ... you need the scopes with the response, the add the scope path parameter to the t...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (1)
en/includes/guides/organization-management/organization-applications.md (1)
77-80: Verify referenced sections exist in the file.Lines 77 and 80 reference "Login Flow configurations" and "Advanced configurations" as operations supported for organization applications, but these sections are not visible in the provided code excerpt. Please confirm these sections exist elsewhere in the file, or if they are planned additions, ensure they are completed before merging.
en/includes/guides/organization-management/organization-applications.md
Outdated
Show resolved
Hide resolved
ShanChathusanda93
force-pushed
the
sub-org-app-auth-code-branch
branch
from
fe8d3e5 to
d19883d
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
en/includes/guides/organization-management/organization-applications.md (1)
206-207: Fix grammar and parameter classification in scope note.Line 207 has residual text from editing: "the add the
scopepath parameter" should be "add thescopeparameter". Additionally,scopeis a form/body parameter in this token request, not a path parameter.- If you need the scopes with the response, the add the `scope` path parameter to the token request with the required scopes. + If you need scopes in the response, add the `scope` parameter to the token request with the required scopes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (6)
en/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.png
📒 Files selected for processing (1)
en/includes/guides/organization-management/organization-applications.md(5 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-01T15:31:14.922Z
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.
Applied to files:
en/includes/guides/organization-management/organization-applications.md
🪛 Gitleaks (8.30.0)
en/includes/guides/organization-management/organization-applications.md
[high] 121-121: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 156-156: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 132-132: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 190-190: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 223-223: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 224-224: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 260-260: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
🪛 LanguageTool
en/includes/guides/organization-management/organization-applications.md
[grammar] ~75-~75: Use a hyphen to join words.
Context: ...r organization applications. - Protocol level configurations - User attributes r...
(QB_NEW_EN_HYPHEN)
[grammar] ~207-~207: Ensure spelling is correct
Context: ... you need the scopes with the response, the add the scope path parameter to the t...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (1)
en/includes/guides/organization-management/organization-applications.md (1)
51-141: Excellent structural improvements for Authorization Code Grant prominence and console-driven workflow.The reorganization to elevate Authorization Code Grant as the primary flow, the shift from API-based to Console-based application creation with visual guidance (lines 61–71), and the introduction of tabbed Request format / Sample request / Sample response sections provide clarity and improve developer experience. The explicit note about refresh_token behavior (line 140) and scope handling in responses is also helpful.
en/includes/guides/organization-management/organization-applications.md
Outdated
Show resolved
Hide resolved
ShanChathusanda93
force-pushed
the
sub-org-app-auth-code-branch
branch
from
d19883d to
fb975d8
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
en/includes/guides/organization-management/organization-applications.md (1)
226-226: Fix grammar error in note text.Line 226 has a double article: "the add the" should be just "add the".
- If you need the scopes with the response, the add the `scope` path parameter to the token request with the required scopes. + If you need the scopes with the response, add the `scope` parameter to the token request with the required scopes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (6)
en/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.png
📒 Files selected for processing (4)
en/identity-server/7.1.0/docs/guides/organization-management/organization-applications.md(1 hunks)en/identity-server/7.2.0/docs/guides/organization-management/organization-applications.md(1 hunks)en/identity-server/next/docs/guides/organization-management/organization-applications.md(1 hunks)en/includes/guides/organization-management/organization-applications.md(5 hunks)
✅ Files skipped from review due to trivial changes (1)
- en/identity-server/7.1.0/docs/guides/organization-management/organization-applications.md
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-01T15:31:14.922Z
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.
Applied to files:
en/includes/guides/organization-management/organization-applications.md
🪛 Gitleaks (8.30.0)
en/includes/guides/organization-management/organization-applications.md
[high] 151-151: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 140-140: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 175-175: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 209-209: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 243-243: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 242-242: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 279-279: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
🪛 LanguageTool
en/includes/guides/organization-management/organization-applications.md
[grammar] ~226-~226: Ensure spelling is correct
Context: ... you need the scopes with the response, the add the scope path parameter to the t...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (5)
en/identity-server/7.2.0/docs/guides/organization-management/organization-applications.md (1)
3-3: Parameterized root organization URL placeholder.The root URL has been updated to use a dynamic placeholder for the organization handle instead of the hardcoded "carbon.super" value. This aligns with the PR's intent to improve structure by enabling dynamic root organization resolution.
⚠️ Verify placeholder naming consistency across versions. The AI summary indicates that version 7.1.0 uses{root-organization-name}while this version (7.2.0) and the next version use{root-organization-handle}. Please verify if this inconsistency is intentional or if placeholder naming should be standardized across all versions.en/identity-server/next/docs/guides/organization-management/organization-applications.md (1)
3-3: Parameterized root organization URL placeholder (consistent with 7.2.0).The root URL parameterization matches the update in the 7.2.0 version, using
{root-organization-handle}for dynamic organization resolution. This consistency between current and next versions is good.Same verification needed: Please confirm whether the placeholder naming difference with version 7.1.0 (
{root-organization-name}vs{root-organization-handle}) is intentional or should be standardized.en/includes/guides/organization-management/organization-applications.md (3)
105-160: Approve Authorization Code Grant section structure.The Authorization Code Grant section is well-structured with clear Request format (lines 105–113) and Sample request (lines 115–123) tabs showing placeholders and concrete examples. The authorization flow description (line 125) is clear, and the token endpoint request/response handling is properly documented with sample responses (lines 146–156) and helpful notes about refresh token behavior (lines 158–159).
161-227: Approve Password and Client Credentials Grant sections.Both grant sections follow the same consistent structure as Authorization Code: Request format with placeholders, Sample request with example values, and Sample response with token details. Notes about scope handling are appropriate and match the patterns from past reviews (line 193 for Password Grant, line 225 for Client Credentials).
228-289: Approve token introspection and revocation sections.The new token introspection (lines 228–264) and token revocation (lines 265–289) sections are well-structured with consistent Request format, Sample request, and Sample response tabs. The use of placeholders (e.g.,
<OAUTH_CLIENT_KEY>:<OAUTH_CLIENT_SECRET>,<SUB_ORG_APP_TOKEN>,<TOKEN_TYPE>) in Request format sections makes it clear how to substitute real values, and the sample sections provide concrete examples.
ShanChathusanda93
force-pushed
the
sub-org-app-auth-code-branch
branch
from
fb975d8 to
6fa0247
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @en/includes/guides/organization-management/organization-applications.md:
- Line 244: Fix the typo and clarify parameter type in the Client Credentials
Grant note: replace "the add the `scope` path parameter" with "add the `scope`
request parameter" so the sentence reads that you should "add the `scope`
request parameter to the token request with the required scopes" (matching the
Password Grant note wording).
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (6)
en/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.png
📒 Files selected for processing (4)
en/identity-server/7.1.0/docs/guides/organization-management/organization-applications.mden/identity-server/7.2.0/docs/guides/organization-management/organization-applications.mden/identity-server/next/docs/guides/organization-management/organization-applications.mden/includes/guides/organization-management/organization-applications.md
🚧 Files skipped from review as they are similar to previous changes (1)
- en/identity-server/next/docs/guides/organization-management/organization-applications.md
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-01T15:31:14.922Z
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.
Applied to files:
en/includes/guides/organization-management/organization-applications.md
🪛 Gitleaks (8.30.0)
en/includes/guides/organization-management/organization-applications.md
[high] 156-156: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 193-193: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 167-167: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 227-227: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 260-260: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 261-261: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 297-297: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
🪛 LanguageTool
en/includes/guides/organization-management/organization-applications.md
[grammar] ~99-~99: Use a hyphen to join words.
Context: ...nd is_version > "7.2.0" ) %} - Protocol level configurations - User attributes r...
(QB_NEW_EN_HYPHEN)
[grammar] ~108-~108: Use a hyphen to join words.
Context: ...d configurations {% else %} - Protocol level configurations - User attributes r...
(QB_NEW_EN_HYPHEN)
[grammar] ~244-~244: Ensure spelling is correct
Context: ... you need the scopes with the response, the add the scope path parameter to the t...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (6)
en/identity-server/7.1.0/docs/guides/organization-management/organization-applications.md (1)
3-3: ✅ Root organization URL parameterization is correct.Replacing the hardcoded
carbon.superreference with a{root-organization-name}placeholder supports dynamic multi-tenancy resolution and aligns with the version-specific configuration pattern.en/identity-server/7.2.0/docs/guides/organization-management/organization-applications.md (1)
3-3: ✅ Version-specific placeholder naming is correct.Using
{root-organization-handle}for the 7.2.0+ versions aligns with the documented versioning strategy. The distinction between{root-organization-name}(7.1.0) and{root-organization-handle}(7.2.0+) reflects appropriate version-specific API/naming conventions.en/includes/guides/organization-management/organization-applications.md (4)
9-18: ✅ Grant type and template conditionals are properly structured.Authorization code grant is correctly restricted to Asgardeo and IS > 7.2.0. The conditional blocks properly hide unsupported grant types and template options for earlier versions, preventing version-specific documentation inconsistencies.
77-89: ✅ Console-based creation flow with proper conditionals and accessibility.The UI-guided creation flow is correctly restricted to eligible versions, with appropriate fallback to API-based guidance for others. Images include descriptive alt text and consistent styling. This addresses the past concern about image accessibility.
97-113: ✅ Operations configuration is properly versioned.The conditional blocks correctly limit operation types to supported versions. Login Flow and Advanced configurations are appropriately hidden from versions that don't support them.
246-306: ✅ Token introspection and revocation sections are well-structured.Both sections follow the established pattern with clear separation between placeholder-based request formats and concrete sample requests. Sample responses are realistic and helpful for implementation guidance.
en/includes/guides/organization-management/organization-applications.md
Outdated
Show resolved
Hide resolved
…port and improve structure
ShanChathusanda93
force-pushed
the
sub-org-app-auth-code-branch
branch
from
6fa0247 to
b795bf3
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In
@en/identity-server/7.1.0/docs/guides/organization-management/organization-applications.md:
- Line 3: The placeholder in organization-applications.md uses
{root-organization-name} while other versions use {root-organization-handle};
decide on the canonical placeholder and update this file to match (replace
{root-organization-name} with {root-organization-handle} if standardizing on
-handle), or document the intentional difference with a brief note; ensure the
change targets the string "{root-organization-name}" in the 7.1.0
organization-applications.md so it aligns with the other version files.
In @en/includes/guides/organization-management/organization-applications.md:
- Around line 156-160: Replace all literal high-entropy credentials and tokens
in the sample requests/responses with the same explicit placeholder syntax used
in the "Request format" sections: for the Authorization Code Grant sample
request shown (the curl block with client key/secret and code), change the user
credential to <OAUTH_CLIENT_KEY>:<OAUTH_CLIENT_SECRET>, the code to <AUTH_CODE>,
and the redirect URI to <REDIRECT_URI>; do the same for Password Grant, Client
Credentials Grant, Token Introspection, and Token Revocation sample request
blocks (use <USERNAME>, <PASSWORD>, <ORG_ID>, etc. as appropriate), and replace
sample response tokens (access_token/refresh_token) with placeholders like
<ACCESS_TOKEN> and <REFRESH_TOKEN> so no real-looking secrets remain.
🧹 Nitpick comments (2)
en/includes/guides/organization-management/organization-applications.md (2)
99-99: Resolve hyphenation style inconsistency.Lines 99 and 108 contain "Protocol level configurations" which LanguageTool flags as needing hyphenation ("Protocol-level configurations"). However, project learnings indicate a preference for unhyphenated compound adjectives. Ensure consistency with the documentation style guide.
Based on learnings, resolve this by either:
- Following LanguageTool: Update to "Protocol-level configurations" (standard English grammar)
- Following project style: Update learnings/lint config if unhyphenated is the intended style
Also applies to: 108-108
25-27: Clarify Inherited API Resources description with better phrasing.Line 25-27 reads: "The {{ product_name }} defined Organization API Resources and the API Resources that are created in the root organization are now inherited to the organization."
This phrasing is slightly awkward. Consider: "Organization API Resources and API Resources defined in the root organization are inherited to sub-organizations." This more clearly separates the two resource types and improves readability.
📝 Proposed phrasing improvement
- The Organization API Resources and the API Resources that are created - in the root organization are inherited to the organizations directly. These API Resources are available in read only mode through the {{ product_name}} Console. + Organization API Resources and API Resources created in the root organization are inherited to sub-organizations and available in read-only mode through the {{ product_name }} Console.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (6)
en/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/asgardeo/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-create.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-edit.pngis excluded by!**/*.pngen/identity-server/next/docs/assets/img/guides/applications/organization-applications/organization-application-templates.pngis excluded by!**/*.png
📒 Files selected for processing (4)
en/identity-server/7.1.0/docs/guides/organization-management/organization-applications.mden/identity-server/7.2.0/docs/guides/organization-management/organization-applications.mden/identity-server/next/docs/guides/organization-management/organization-applications.mden/includes/guides/organization-management/organization-applications.md
🚧 Files skipped from review as they are similar to previous changes (1)
- en/identity-server/7.2.0/docs/guides/organization-management/organization-applications.md
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-01T15:31:14.922Z
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.
Applied to files:
en/includes/guides/organization-management/organization-applications.md
🪛 Gitleaks (8.30.0)
en/includes/guides/organization-management/organization-applications.md
[high] 156-156: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 193-193: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 167-167: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 227-227: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 260-260: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 261-261: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 297-297: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
🪛 LanguageTool
en/includes/guides/organization-management/organization-applications.md
[grammar] ~99-~99: Use a hyphen to join words.
Context: ...nd is_version > "7.2.0" ) %} - Protocol level configurations - User attributes r...
(QB_NEW_EN_HYPHEN)
[grammar] ~108-~108: Use a hyphen to join words.
Context: ...d configurations {% else %} - Protocol level configurations - User attributes r...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (1)
en/includes/guides/organization-management/organization-applications.md (1)
9-18: Verify version string comparison handles all expected version formats.The condition
is_version > "7.2.0"uses string comparison for semantic versioning. While this works for the common case of single-digit minor/patch versions, verify that all versions passed to this template use consistent formatting (e.g., no "v7.2.0" prefix, no pre-release suffixes like "7.2.0-beta").Confirm that the template rendering context consistently provides version strings in the format expected by this comparison (e.g., always "X.Y.Z" format).
Also applies to: 66-75
en/identity-server/7.1.0/docs/guides/organization-management/organization-applications.md
Show resolved
Hide resolved
| curl --user 7wYeybBGCVfLxPmS0z66WNMffyMa:WYfwHUsbsEvwtqmDLuaxF_VCQJwa -k | ||
| -d "grant_type=authorization_code&code=111c6b23-e395-4263-8792-87dc5db3c8a9&redirect_uri=https://bestcarmart.com/login" | ||
| -H "Content-Type: application/x-www-form-urlencoded" | ||
| {{ root_org_url }}/o/7e98b86f-63c7-41a1-8c56-c909a21a2615/oauth2/token | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's read the file to see the context around these lines
head -310 en/includes/guides/organization-management/organization-applications.md | tail -160Repository: wso2/docs-is
Length of output: 4984
🏁 Script executed:
# Check if the file exists and get its size
wc -l en/includes/guides/organization-management/organization-applications.mdRepository: wso2/docs-is
Length of output: 131
🏁 Script executed:
# Let's look at specific sections where credentials appear with surrounding context
echo "=== Context around lines 156-160 ===" && sed -n '150,165p' en/includes/guides/organization-management/organization-applications.md
echo -e "\n=== Context around lines 193-197 ===" && sed -n '187,202p' en/includes/guides/organization-management/organization-applications.md
echo -e "\n=== Context around lines 227-231 ===" && sed -n '221,236p' en/includes/guides/organization-management/organization-applications.md
echo -e "\n=== Context around lines 260-264 ===" && sed -n '254,269p' en/includes/guides/organization-management/organization-applications.md
echo -e "\n=== Context around lines 297-301 ===" && sed -n '291,306p' en/includes/guides/organization-management/organization-applications.mdRepository: wso2/docs-is
Length of output: 2469
🏁 Script executed:
# Check git history for when these lines were added and if there are any comments about them being examples
git log --oneline -p en/includes/guides/organization-management/organization-applications.md | head -500Repository: wso2/docs-is
Length of output: 12827
Use explicit placeholder syntax for all example credentials to prevent credential leaks.
The file has a documented structure where "Request format" sections use placeholder syntax like <OAUTH_CLIENT_KEY>:<OAUTH_CLIENT_SECRET> and <ORG_ID>, but the "Sample request" sections contain high-entropy credential-like values without clear example markings. This inconsistency causes Gitleaks to flag potential secrets.
Apply the same placeholder syntax from "Request format" sections to all "Sample request" examples:
Example fix for Authorization Code Grant (lines 156-160)
- curl --user 7wYeybBGCVfLxPmS0z66WNMffyMa:WYfwHUsbsEvwtqmDLuaxF_VCQJwa -k
- -d "grant_type=authorization_code&code=111c6b23-e395-4263-8792-87dc5db3c8a9&redirect_uri=https://bestcarmart.com/login"
- -H "Content-Type: application/x-www-form-urlencoded"
- {{ root_org_url }}/o/7e98b86f-63c7-41a1-8c56-c909a21a2615/oauth2/token
+ curl --user <OAUTH_CLIENT_KEY>:<OAUTH_CLIENT_SECRET> -k
+ -d "grant_type=authorization_code&code=<AUTHORIZATION_CODE>&redirect_uri=<REDIRECT_URI>"
+ -H "Content-Type: application/x-www-form-urlencoded"
+ {{ root_org_url }}/o/<ORG_ID>/oauth2/tokenApply the same pattern to Password Grant (lines 193-197), Client Credentials Grant (lines 227-231), Token Introspection (lines 260-264), and Token Revocation (lines 297-301). Also update sample response tokens (lines 167, 261) with placeholder syntax.
📝 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.
| curl --user 7wYeybBGCVfLxPmS0z66WNMffyMa:WYfwHUsbsEvwtqmDLuaxF_VCQJwa -k | |
| -d "grant_type=authorization_code&code=111c6b23-e395-4263-8792-87dc5db3c8a9&redirect_uri=https://bestcarmart.com/login" | |
| -H "Content-Type: application/x-www-form-urlencoded" | |
| {{ root_org_url }}/o/7e98b86f-63c7-41a1-8c56-c909a21a2615/oauth2/token | |
| ``` | |
| curl --user <OAUTH_CLIENT_KEY>:<OAUTH_CLIENT_SECRET> -k | |
| -d "grant_type=authorization_code&code=<AUTHORIZATION_CODE>&redirect_uri=<REDIRECT_URI>" | |
| -H "Content-Type: application/x-www-form-urlencoded" | |
| {{ root_org_url }}/o/<ORG_ID>/oauth2/token |
🧰 Tools
🪛 Gitleaks (8.30.0)
[high] 156-156: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
🤖 Prompt for AI Agents
In @en/includes/guides/organization-management/organization-applications.md
around lines 156 - 160, Replace all literal high-entropy credentials and tokens
in the sample requests/responses with the same explicit placeholder syntax used
in the "Request format" sections: for the Authorization Code Grant sample
request shown (the curl block with client key/secret and code), change the user
credential to <OAUTH_CLIENT_KEY>:<OAUTH_CLIENT_SECRET>, the code to <AUTH_CODE>,
and the redirect URI to <REDIRECT_URI>; do the same for Password Grant, Client
Credentials Grant, Token Introspection, and Token Revocation sample request
blocks (use <USERNAME>, <PASSWORD>, <ORG_ID>, etc. as appropriate), and replace
sample response tokens (access_token/refresh_token) with placeholders like
<ACCESS_TOKEN> and <REFRESH_TOKEN> so no real-looking secrets remain.
There was a problem hiding this comment.
These values are dummy values which was added only to present the sample request. However if we add the suggested changes, then the request format and the sample request become a single value. So no point of having a sample request section in the doc.
There was a problem hiding this comment.
@ShanChathusanda93, you make a fair point about the documentation structure. Having concrete examples in the "Sample request" sections does provide value for users who want to see what an actual request looks like.
To address the Gitleaks warnings while preserving your sample requests, you have a few options:
-
Add a Gitleaks allowlist - Create or update
.gitleaks.tomlin your repository to allowlist this specific file or pattern:[[rules]] description = "Ignore sample credentials in documentation" id = "docs-sample-creds" path = '''(en/includes/guides/.*\.md)'''
-
Make dummy values more obviously fake - Use values that are clearly example format like:
example_client_key_here:example_client_secret_here00000000-0000-0000-0000-000000000000for UUIDs- This reduces false positives while keeping the sample structure
-
Add explicit callout text - Add a note above the sample requests stating:
!!! example The following examples use dummy credentials for demonstration purposes only.
Would any of these approaches work for your documentation needs?
2 participants
Purpose
Related PRs
Test environment
Security checks
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.