Update organization application doc with authorization code grant support and improve structure #5787
Conversation
WalkthroughDocumentation updates shift organization-application onboarding from an API-first flow to a Console-driven workflow, promote Authorization Code as the primary OAuth2 grant, add explicit token/introspection/revocation request/response examples, and replace hardcoded root-organization URLs with parameterized placeholders. (33 words) Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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
…port and improve structure
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.
| {% if product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and is_version > "7.2.0" ) %} | ||
| - Only authorization code, client credentials, password and refresh grant types can be used. | ||
| - Only Standard-Based Application and M2M Application templates can be used. | ||
| {% else %} | ||
| - Only client credentials, password and refresh grant types can be used. | ||
| {% endif %} |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for "authorization code" references in the file to ensure all are properly conditioned
rg -n "authorization code|Authorization Code" en/includes/guides/organization-management/organization-applications.mdRepository: wso2/docs-is
Length of output: 618
🏁 Script executed:
#!/bin/bash
# Read the file to check the full context and conditional structure
head -n 130 en/includes/guides/organization-management/organization-applications.md | cat -nRepository: wso2/docs-is
Length of output: 7870
🏁 Script executed:
#!/bin/bash
# Read more of the file to see the full Authorization Code Grant section
sed -n '101,200p' en/includes/guides/organization-management/organization-applications.md | cat -nRepository: wso2/docs-is
Length of output: 4085
Wrap Authorization Code Grant section in conditional to prevent display in unsupported versions.
The Authorization Code Grant section starting at line 103 lacks a conditional wrapper. While lines 10 and 63 correctly restrict the grant type to Asgardeo/IS 7.3.0+, the entire "Authorization Code Grant" documentation block (lines 103–160+) remains visible to all versions, including IS 7.1.0 and 7.2.0 where the grant type is unsupported. Wrap this section with:
{% if product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and is_version > "7.2.0" ) %}
- Authorization Code Grant
[entire grant section content]
{% endif %}
The remaining conditionals at lines 9–14, 62–67, 69–79, and 87–99 are correctly applied.
2 participants
Purpose
Related PRs
Test environment
Security checks
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.