Add token exchange support for organization applications and improve the existing docs#6031
Merged
himeshsiriwardana merged 1 commit intowso2:masterfrom Apr 6, 2026
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdds Jinja Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@en/includes/guides/organization-management/generate-tokens-for-organization-apps.md`:
- Line 143: The instructional sentence in the markdown uses the typo "asubject";
edit the sentence in generate-tokens-for-organization-apps.md (the line that
currently reads "Use the following steps to use asubject token to get an access
token using the token exchange.") and change "asubject" to "a subject" so it
reads "Use the following steps to use a subject token to get an access token
using the token exchange."
- Line 162: The curl example currently includes a realistic-looking client
key/secret in the "curl --user ..." sample; replace those hardcoded credentials
with clear placeholders (e.g., <CLIENT_KEY>:<CLIENT_SECRET> or
{CLIENT_KEY}:{CLIENT_SECRET}) in the "curl --user" line so the docs do not
expose secret-like values and readers know to substitute their own credentials.
- Around line 154-156: The token exchange curl block contains a trailing comma
and a malformed/duplicative Authorization header; edit the request in
generate-tokens-for-organization-apps.md to remove the extra line '-H
"Content-Type: Authorization: Basic <base64 Encoded (clientId:clientSecret)>"'
and the trailing comma after '-H "Content-Type:
application/x-www-form-urlencoded"', leaving only the Content-Type header and
relying on the existing --user flag for Basic auth when calling the {{
root_org_url }}/o/<ORG_ID>/oauth2/token endpoint.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 3b033d07-a4e2-4758-862a-7fcdd19a279f
📒 Files selected for processing (3)
en/identity-server/next/docs/guides/organization-management/generate-tokens-for-organization-apps.mden/includes/guides/authentication/configure-token-exchange.mden/includes/guides/organization-management/generate-tokens-for-organization-apps.md
en/includes/guides/organization-management/generate-tokens-for-organization-apps.md
Outdated
Show resolved
Hide resolved
en/includes/guides/organization-management/generate-tokens-for-organization-apps.md
Outdated
Show resolved
Hide resolved
en/includes/guides/organization-management/generate-tokens-for-organization-apps.md
Show resolved
Hide resolved
ShanChathusanda93
force-pushed
the
sub-org-token-exchange-branch
branch
2 times, most recently
from
067b1b5 to
77093ce
Compare
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (5)
en/includes/guides/authentication/configure-token-exchange.md (3)
153-153: Replace ambiguous pronoun for clarity.“after which it will appear” can be misread. Replace
itwiththe attributefor unambiguous guidance.As per coding guidelines, “Avoid ambiguous pronouns (it, this, that, they) by replacing them with explicit nouns when ambiguity exists.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/includes/guides/authentication/configure-token-exchange.md` at line 153, In the sentence "Administrators can make an attribute unique across the user stores, after which it will appear in the lookup attributes list," replace the ambiguous pronoun "it" with "the attribute" so the sentence reads "...after which the attribute will appear in the lookup attributes list" to remove ambiguity; update this line in configure-token-exchange.md accordingly.
159-160: Prefer internal canonical path instead of hardcoded docs domain.Use an internal
{{base_path}}link for the API reference to avoid coupling this include tois.docs.wso2.comdirectly.As per coding guidelines, “Use descriptive link text for internal links and prefer linking to canonical pages.”🔧 Suggested edit
-In {{ product_name }}, implicit account linking can be configured via the -[Implicit Association API](https://is.docs.wso2.com/en/{{ is_version }}/apis/idp/#tag/Implicit-Association/operation/updateImplicitAssociation). +In {{ product_name }}, you can configure implicit account linking through the +[Implicit Association API]({{base_path}}/apis/idp/#tag/Implicit-Association/operation/updateImplicitAssociation).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/includes/guides/authentication/configure-token-exchange.md` around lines 159 - 160, Replace the hardcoded docs domain link in the sentence that references the Implicit Association API with the internal canonical variable {{base_path}} and use descriptive link text; specifically update the link target in the line mentioning the Implicit Association API so it points to {{base_path}}/apis/idp/#tag/Implicit-Association/operation/updateImplicitAssociation (or the canonical page URL under {{base_path}}) instead of https://is.docs.wso2.com..., and ensure the link text remains descriptive (e.g., "Implicit Association API") per the guidelines.
185-188: Link directly to the relevant section anchor.This note points to the page root; linking to
#token-exchange-grantgets readers to the exact workflow immediately.As per coding guidelines, “Use descriptive link text for internal links and prefer linking to canonical pages.”🔗 Suggested edit
- To learn how token exchange can be invoked in organization applications, see [Generate tokens for organization applications]({{base_path}}/guides/organization-management/generate-tokens-for-organization-apps). + To learn how token exchange can be invoked in organization applications, see [Token exchange grant for organization applications]({{base_path}}/guides/organization-management/generate-tokens-for-organization-apps/#token-exchange-grant).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/includes/guides/authentication/configure-token-exchange.md` around lines 185 - 188, Update the internal link inside the conditional block so it points directly to the token-exchange grant section by appending the anchor "#token-exchange-grant" to the URL built with {{base_path}} and make the link text descriptive (e.g., "Generate tokens for organization applications — Token Exchange Grant") to follow the guideline; locate the link currently labeled "Generate tokens for organization applications" in the {% if product_name ... %} block and change only the href to include "/generate-tokens-for-organization-apps#token-exchange-grant" (or equivalent using {{base_path}}) and adjust the link text accordingly.en/includes/guides/organization-management/generate-tokens-for-organization-apps.md (2)
173-179: Add a language tag to the sample response code fence.This is JSON; tagging improves rendering and consistency.
As per coding guidelines, “Use fenced code blocks with a language tag when known.”🧩 Suggested edit
- ``` + ```json { "access_token": "bc978da1-6c56-3125-a999-a8d61c889672", "token_type": "Bearer", "expires_in": 3600 } ```🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/includes/guides/organization-management/generate-tokens-for-organization-apps.md` around lines 173 - 179, The sample response code fence is missing a JSON language tag; update the fenced block containing the sample access_token/token_type/expires_in JSON to use a JSON tag by changing the opening backticks from ``` to ```json so the block is rendered and highlighted as JSON (locate the response example with keys "access_token", "token_type", and "expires_in" and add the json tag).
143-143: Tighten the instruction sentence to remove repetition.The current wording repeats “use” three times. A shorter imperative reads better.
As per coding guidelines, “Use plain language and short sentences” and “Use precise nouns and strong verbs.”✍️ Suggested edit
-Use the following steps to use a subject token to get an access token using the token exchange. +Use the following steps to exchange a subject token for an access token.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/includes/guides/organization-management/generate-tokens-for-organization-apps.md` at line 143, Replace the sentence "Use the following steps to use a subject token to get an access token using the token exchange." with a tighter imperative such as "Exchange a subject token for an access token using token exchange." — update the line in the guide where that exact sentence appears so it removes the repeated "use" and reads as a short, precise instruction.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@en/includes/guides/authentication/configure-token-exchange.md`:
- Line 153: In the sentence "Administrators can make an attribute unique across
the user stores, after which it will appear in the lookup attributes list,"
replace the ambiguous pronoun "it" with "the attribute" so the sentence reads
"...after which the attribute will appear in the lookup attributes list" to
remove ambiguity; update this line in configure-token-exchange.md accordingly.
- Around line 159-160: Replace the hardcoded docs domain link in the sentence
that references the Implicit Association API with the internal canonical
variable {{base_path}} and use descriptive link text; specifically update the
link target in the line mentioning the Implicit Association API so it points to
{{base_path}}/apis/idp/#tag/Implicit-Association/operation/updateImplicitAssociation
(or the canonical page URL under {{base_path}}) instead of
https://is.docs.wso2.com..., and ensure the link text remains descriptive (e.g.,
"Implicit Association API") per the guidelines.
- Around line 185-188: Update the internal link inside the conditional block so
it points directly to the token-exchange grant section by appending the anchor
"#token-exchange-grant" to the URL built with {{base_path}} and make the link
text descriptive (e.g., "Generate tokens for organization applications — Token
Exchange Grant") to follow the guideline; locate the link currently labeled
"Generate tokens for organization applications" in the {% if product_name ... %}
block and change only the href to include
"/generate-tokens-for-organization-apps#token-exchange-grant" (or equivalent
using {{base_path}}) and adjust the link text accordingly.
In
`@en/includes/guides/organization-management/generate-tokens-for-organization-apps.md`:
- Around line 173-179: The sample response code fence is missing a JSON language
tag; update the fenced block containing the sample
access_token/token_type/expires_in JSON to use a JSON tag by changing the
opening backticks from ``` to ```json so the block is rendered and highlighted
as JSON (locate the response example with keys "access_token", "token_type", and
"expires_in" and add the json tag).
- Line 143: Replace the sentence "Use the following steps to use a subject token
to get an access token using the token exchange." with a tighter imperative such
as "Exchange a subject token for an access token using token exchange." — update
the line in the guide where that exact sentence appears so it removes the
repeated "use" and reads as a short, precise instruction.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e67c12f2-1217-4122-816e-a46bd36912c4
📒 Files selected for processing (3)
en/identity-server/next/docs/guides/organization-management/generate-tokens-for-organization-apps.mden/includes/guides/authentication/configure-token-exchange.mden/includes/guides/organization-management/generate-tokens-for-organization-apps.md
✅ Files skipped from review due to trivial changes (1)
- en/identity-server/next/docs/guides/organization-management/generate-tokens-for-organization-apps.md
en/includes/guides/organization-management/generate-tokens-for-organization-apps.md
Outdated
Show resolved
Hide resolved
ShanChathusanda93
force-pushed
the
sub-org-token-exchange-branch
branch
from
77093ce to
85ff32c
Compare
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
en/includes/guides/organization-management/generate-tokens-for-organization-apps.md (1)
183-184: Consider moving this note closer to the client credentials grant section.The note appears after the conditional token exchange section. When the token exchange section renders (for Asgardeo or WSO2 IS > 7.2.0), readers might think the note applies to token exchange—but those examples already include the
scopeparameter. The note seems intended for the client credentials grant section.Consider moving this note to line 138 (before the token exchange conditional) so it stays visually associated with the client credentials grant section.
📝 Suggested placement
Move the note from lines 183-184 to appear at line 138 (after the client credentials sample response and before the token exchange conditional):
} ``` +!!! note + If you need scopes in the response, add the `scope` parameter to the token request with the required scopes. + {% if product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and is_version > "7.2.0") %} ## Token exchange grantThen remove the note from lines 183-184.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/includes/guides/organization-management/generate-tokens-for-organization-apps.md` around lines 183 - 184, Move the informational note ("If you need scopes in the response, add the `scope` parameter to the token request with the required scopes.") from its current location after the conditional token exchange examples to directly after the client credentials grant sample response and before the token exchange conditional (i.e., place it just before the `{% if product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and is_version > "7.2.0") %}` token exchange block), and remove the original note so it no longer appears after the token exchange section.en/includes/guides/authentication/configure-token-exchange.md (1)
185-188: Consider adding an anchor to link directly to the token exchange section.The link text is descriptive and the target page exists, but readers will need to scroll to find the token exchange grant section. Adding
#token-exchange-grantto the link would provide direct navigation.🔗 Suggested improvement
- To learn how token exchange can be invoked in organization applications, see [Generate tokens for organization applications]({{base_path}}/guides/organization-management/generate-tokens-for-organization-apps). + To learn how token exchange can be invoked in organization applications, see [Generate tokens for organization applications]({{base_path}}/guides/organization-management/generate-tokens-for-organization-apps#token-exchange-grant).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/includes/guides/authentication/configure-token-exchange.md` around lines 185 - 188, Update the conditional link that points to Generate tokens for organization applications to include the token-exchange anchor so readers land directly on the token exchange section; modify the URL built with {{base_path}}/guides/organization-management/generate-tokens-for-organization-apps to append `#token-exchange-grant` (inside the same {% if product_name ... %} block) so the rendered link targets the token exchange grant heading.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@en/includes/guides/authentication/configure-token-exchange.md`:
- Around line 185-188: Update the conditional link that points to Generate
tokens for organization applications to include the token-exchange anchor so
readers land directly on the token exchange section; modify the URL built with
{{base_path}}/guides/organization-management/generate-tokens-for-organization-apps
to append `#token-exchange-grant` (inside the same {% if product_name ... %}
block) so the rendered link targets the token exchange grant heading.
In
`@en/includes/guides/organization-management/generate-tokens-for-organization-apps.md`:
- Around line 183-184: Move the informational note ("If you need scopes in the
response, add the `scope` parameter to the token request with the required
scopes.") from its current location after the conditional token exchange
examples to directly after the client credentials grant sample response and
before the token exchange conditional (i.e., place it just before the `{% if
product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and
is_version > "7.2.0") %}` token exchange block), and remove the original note so
it no longer appears after the token exchange section.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: dadff58b-33c1-4224-9f01-589b696bdf65
📒 Files selected for processing (3)
en/identity-server/next/docs/guides/organization-management/generate-tokens-for-organization-apps.mden/includes/guides/authentication/configure-token-exchange.mden/includes/guides/organization-management/generate-tokens-for-organization-apps.md
🚧 Files skipped from review as they are similar to previous changes (1)
- en/identity-server/next/docs/guides/organization-management/generate-tokens-for-organization-apps.md
ShanChathusanda93
force-pushed
the
sub-org-token-exchange-branch
branch
2 times, most recently
from
d80bd43 to
00148c7
Compare
himeshsiriwardana
previously approved these changes
Apr 6, 2026
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@en/includes/guides/organization-management/generate-tokens-for-organization-apps.md`:
- Line 139: The Asgardeo wrapper for the generate-tokens-for-organization-apps
guide fails to define the root_org_url variable used by the included shared
guide; add a Jinja2 set statement defining root_org_url to
"https://api.asgardeo.io/t/{root-organization-name}" at the very top of the
Asgardeo wrapper (before the shared include) so the token exchange URLs
(references to root_org_url at lines where the shared file renders URLs) render
correctly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: a8d6fddd-85ec-4460-9548-1537d201528f
📒 Files selected for processing (4)
.vale/styles/config/vocabularies/vocab/accept.txten/identity-server/next/docs/guides/organization-management/generate-tokens-for-organization-apps.mden/includes/guides/authentication/configure-token-exchange.mden/includes/guides/organization-management/generate-tokens-for-organization-apps.md
✅ Files skipped from review due to trivial changes (1)
- .vale/styles/config/vocabularies/vocab/accept.txt
🚧 Files skipped from review as they are similar to previous changes (1)
- en/identity-server/next/docs/guides/organization-management/generate-tokens-for-organization-apps.md
en/includes/guides/organization-management/generate-tokens-for-organization-apps.md
Show resolved
Hide resolved
…the existing docs
ShanChathusanda93
force-pushed
the
sub-org-token-exchange-branch
branch
from
00148c7 to
75d2949
Compare
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
en/includes/guides/authentication/configure-token-exchange.md (1)
185-188: Add anchor fragment to deep-link to the Token exchange grant section.The link points to the page root, requiring users to scroll to find the Token exchange grant section. For better user experience, append the section anchor.
🔗 Suggested improvement
- To learn how token exchange can be invoked in organization applications, see [Generate tokens for organization applications]({{base_path}}/guides/organization-management/generate-tokens-for-organization-apps). + To learn how token exchange can be invoked in organization applications, see [Generate tokens for organization applications]({{base_path}}/guides/organization-management/generate-tokens-for-organization-apps#token-exchange-grant).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/includes/guides/authentication/configure-token-exchange.md` around lines 185 - 188, Update the link target so it deep-links directly to the Token exchange grant section by appending the section anchor fragment to the existing URL used in the conditional block; locate the template that renders the link text "Generate tokens for organization applications" and change the href from "{{base_path}}/guides/organization-management/generate-tokens-for-organization-apps" to include the appropriate fragment (for example "#token-exchange-grant") so users land directly on the Token exchange grant section.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@en/includes/guides/authentication/configure-token-exchange.md`:
- Around line 185-188: Update the link target so it deep-links directly to the
Token exchange grant section by appending the section anchor fragment to the
existing URL used in the conditional block; locate the template that renders the
link text "Generate tokens for organization applications" and change the href
from
"{{base_path}}/guides/organization-management/generate-tokens-for-organization-apps"
to include the appropriate fragment (for example "#token-exchange-grant") so
users land directly on the Token exchange grant section.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: df5a1a9d-0763-4dea-a832-7ceda05a84cd
📒 Files selected for processing (5)
.vale/styles/config/vocabularies/vocab/accept.txten/asgardeo/docs/guides/organization-management/generate-tokens-for-organization-apps.mden/identity-server/next/docs/guides/organization-management/generate-tokens-for-organization-apps.mden/includes/guides/authentication/configure-token-exchange.mden/includes/guides/organization-management/generate-tokens-for-organization-apps.md
✅ Files skipped from review due to trivial changes (2)
- .vale/styles/config/vocabularies/vocab/accept.txt
- en/asgardeo/docs/guides/organization-management/generate-tokens-for-organization-apps.md
🚧 Files skipped from review as they are similar to previous changes (1)
- en/identity-server/next/docs/guides/organization-management/generate-tokens-for-organization-apps.md
himeshsiriwardana
approved these changes
Apr 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
Related to Improve docs for token exchange support for sub organization applications product-is#27386
generate-tokens-for-organization-apps
Related PRs
Test environment
Security checks
Summary by CodeRabbit