[Docs] API Docs - Add organization user share v2 API documentation#5913
Merged
BimsaraBodaragama merged 9 commits intowso2:masterfrom Mar 11, 2026
Merged
Conversation
This was referenced Feb 20, 2026
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 OpenAPI v3 specifications and Redoc pages for a new User Sharing Management API V2 (share, share-with-all, unshare, unshare-with-all, patch, and get shared orgs) across Asgardeo and Identity Server, updates mkdocs navigation, and appends scope-sharing notes to existing API docs. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
rect rgba(200,200,255,0.5)
participant Client
end
rect rgba(200,255,200,0.5)
participant API["Asgardeo/Identity API"]
end
rect rgba(255,200,200,0.5)
participant Service["User Sharing Service"]
end
rect rgba(255,255,200,0.5)
participant DB["Organization DB"]
end
Client->>API: POST /users/share (criteria + org configs)
API->>Service: authenticate (OAuth2 scope) & forward request
Service->>DB: persist sharing entries / role assignments
DB-->>Service: ack
Service-->>API: ProcessSuccessResponse (202)
API-->>Client: 202 Accepted
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 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 |
This was referenced Feb 20, 2026
BimsaraBodaragama
changed the title
![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: 7
🧹 Nitpick comments (1)
en/identity-server/next/mkdocs.yml (1)
1249-1249: Consider lowercasev2for consistency with the file's dominant pattern.Most versioned API entries in this file use lowercase
v2/v1(e.g.,Roles v2 API,Notification sender v2 API,Account recovery v2 API). The new labels use uppercaseV2, matching only the single outlierAuthorized apps API V2. Aligning to the predominant style would keep nav labels consistent.✏️ Suggested adjustment
- - User sharing management API V2: apis/organization-user-share-v2-rest-api.md + - User sharing management API v2: apis/organization-user-share-v2-rest-api.md- - User sharing management API V2: apis/organization-apis/organization-user-share-v2.md + - User sharing management API v2: apis/organization-apis/organization-user-share-v2.mdAlso applies to: 1294-1294
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/mkdocs.yml` at line 1249, Change the nav label "User sharing management API V2: apis/organization-user-share-v2-rest-api.md" to use lowercase v2 to match the file's prevailing style; locate the entry containing the exact string "User sharing management API V2: apis/organization-user-share-v2-rest-api.md" in mkdocs.yml and replace "V2" with "v2" (also update the similar occurrence noted around the second instance referenced in the comment) so all versioned API labels follow the same lowercase pattern.
🤖 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/asgardeo/docs/apis/organization-user-share-v2-rest-api.md`:
- Around line 1-5: Add a single top-level sentence-case title (an H1) to the
document and ensure it is the only top-level heading; specifically, insert a
sentence-case heading such as "Organization user share v2 REST API" above the
Redoc embed (before the <redoc
spec-url="{{base_path}}/apis/restapis/organization-user-share-v2.yaml" ...> tag)
so the page has one Markdown H1 and the title uses sentence case, leaving the
existing frontmatter and Redoc tag unchanged.
In
`@en/identity-server/next/docs/apis/organization-apis/organization-user-share-v2.md`:
- Around line 1-7: The document is missing a top-level H1 and a sentence-case
title; add a single top-level title in sentence case (e.g., "Organization user
share v2") and include it as the first Markdown heading in the file, and update
the front-matter or template title if present so the displayed page uses that
sentence-case title; ensure only one H1 exists and keep the existing <redoc
spec-url=...> line unchanged.
In
`@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml`:
- Around line 95-99: The curl sample currently contains an embedded Basic auth
header value ('Authorization: Basic YWRtaW46YWRtaW4='); update all examples (the
curl request block containing -H 'Authorization: Basic ...') to use a
placeholder token instead (e.g., -H 'Authorization: Basic
{{BASIC_AUTH_CREDENTIALS}}' or -H 'Authorization: Basic <BASE64_CREDENTIALS>')
so no real credentials are exposed; apply this replacement to every sample curl
block in the document where the Authorization header is present.
- Around line 20-25: The OpenAPI servers entry currently uses the tenant-based
path string '/t/{tenant-domain}/api/server/v2' and the variable name
tenant-domain; update the servers.url to '/o/api/server/v2' to match the
org-based examples, remove or rename the tenant-domain variable to reflect
organization usage (or delete it if no variables are needed), and ensure the
server-url variable remains intact so all sample links resolve to
'/o/api/server/v2' consistently.
In `@en/identity-server/next/docs/apis/organization-user-share-v2-rest-api.md`:
- Around line 1-8: Update the page to use a sentence-case title and include a
single top-level H1: change the frontmatter "title" value to sentence case (the
"title" field in the YAML block) and add a matching Markdown top-level heading
(H1) at the top of the document before the <redoc ...> tag so the page has one
H1 that mirrors the frontmatter title (e.g., update the YAML title and add "#
<same sentence-case title>" above the redoc spec).
In `@en/identity-server/next/docs/apis/restapis/organization-user-share-v2.yaml`:
- Around line 94-98: The curl examples currently hard-code a Basic auth header
value ('Authorization: Basic YWRtaW46YWRtaW4=') — replace that embedded Base64
credential with a placeholder (for example 'Authorization: Basic
<BASE64_CREDENTIAL>' or switch to 'Authorization: Bearer <ACCESS_TOKEN>') in
every sample block; update the examples around the curl request and any other
occurrences of the exact string 'Authorization: Basic YWRtaW46YWRtaW4=' so no
realistic credentials remain and briefly annotate the placeholder if needed
(e.g., comment or example text) to show how to supply real credentials in
practice.
- Around line 556-599: The example response contains href values using the wrong
base path (/o/api/server/v2); update those hrefs to use the server base path
declared in the OpenAPI servers section (/t/{tenant-domain}/api/server/v2) —
specifically change the hrefs found under the first links array (the one with
rel: "next") and the links array inside sharedWithSelected.value to start with
/t/{tenant-domain}/api/server/v2 while keeping the existing path, query string
and resource IDs unchanged.
---
Nitpick comments:
In `@en/identity-server/next/mkdocs.yml`:
- Line 1249: Change the nav label "User sharing management API V2:
apis/organization-user-share-v2-rest-api.md" to use lowercase v2 to match the
file's prevailing style; locate the entry containing the exact string "User
sharing management API V2: apis/organization-user-share-v2-rest-api.md" in
mkdocs.yml and replace "V2" with "v2" (also update the similar occurrence noted
around the second instance referenced in the comment) so all versioned API
labels follow the same lowercase pattern.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (4)
en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml (2)
22-28:⚠️ Potential issue | 🟠 MajorAlign server base path with org API examples.
servers.urlis tenant-scoped (/t/{tenant-domain}/api/server/v2) while all examples are org-scoped (/o/api/server/v2). Pick one and align them to avoid mismatched clients/docs.🔧 Suggested update (align to org-scoped examples)
- - url: 'https://{server-url}/t/{tenant-domain}/api/server/v2' - variables: - tenant-domain: - default: "carbon.super" - server-url: - default: "localhost:9443" + - url: 'https://{server-url}/o/api/server/v2' + variables: + server-url: + default: "localhost:9443"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml` around lines 22 - 28, The servers.url is tenant-scoped (/t/{tenant-domain}/api/server/v2) but examples are org-scoped; change the servers.url to the org-scoped base path and rename the variable accordingly: update servers.url to use /o/{org-domain}/api/server/v2, replace the tenant-domain variable with org-domain (keep default "carbon.super"), and keep server-url as-is; ensure any references in this YAML use {org-domain} instead of {tenant-domain} so the docs and examples are consistent.
98-101:⚠️ Potential issue | 🟠 MajorReplace embedded Basic auth credentials in samples.
The curl example includes a real Base64 user:pass value. Use a placeholder and apply it to all samples.🔐 Suggested update
- -H 'Authorization: Basic YWRtaW46YWRtaW4=' \ + -H 'Authorization: Basic {base64_username_password}' \🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml` around lines 98 - 101, Replace the embedded Basic auth credential in the curl samples by removing the actual Base64 token "Authorization: Basic YWRtaW46YWRtaW4=" and using a placeholder such as "Authorization: Basic <BASE64_USER_PASS>" (apply this change to every sample containing the header, including the curl example for 'https://localhost:9443/o/api/server/v2/users/share'); ensure the placeholder is consistent across the document and that no real credentials remain.en/identity-server/next/docs/apis/restapis/organization-user-share-v2.yaml (2)
559-592:⚠️ Potential issue | 🟠 MajorAlign example
hrefvalues with the tenant base path.
The responselinks.href(and the Link example) use/o/api/server/v2whileservers.urlis/t/{tenant-domain}/api/server/v2. Align them so examples match the declared base.🔧 Suggested update
- - href: "/o/api/server/v2/users/7a1b7d63-8cfc-4dc9-9332-3f84641b72d8/share?limit=10&after=MTA=" + - href: "/t/{tenant-domain}/api/server/v2/users/7a1b7d63-8cfc-4dc9-9332-3f84641b72d8/share?limit=10&after=MTA=" ... - href: - type: string - example: "/o/api/server/v2/users/7a1b7d63-8cfc-4dc9-9332-3f84641b72d8/share?limit=10&after=MTA=" + href: + type: string + example: "/t/{tenant-domain}/api/server/v2/users/7a1b7d63-8cfc-4dc9-9332-3f84641b72d8/share?limit=10&after=MTA="Also applies to: 1041-1043
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/restapis/organization-user-share-v2.yaml` around lines 559 - 592, Update the example link hrefs so they use the tenant base path declared in servers.url instead of the shortcut /o path: replace occurrences of "/o/api/server/v2" in the example objects (the links.href entries and any Link example) with "/t/{tenant-domain}/api/server/v2" to match the servers.url base; ensure both the top-level example under sharingMode -> organizations -> links.href and the sharedWithSelected -> value -> links.href (and the duplicate occurrences later in the file) are updated so all example URLs consistently use the tenant base path.
97-101:⚠️ Potential issue | 🟠 MajorReplace embedded Basic auth credentials in samples.
The curl example hard-codes a Base64 user:pass value. Use a placeholder and apply it to all samples.🔐 Suggested update
- -H 'Authorization: Basic YWRtaW46YWRtaW4=' \ + -H 'Authorization: Basic {base64_username_password}' \🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/restapis/organization-user-share-v2.yaml` around lines 97 - 101, The curl examples in the YAML embed a literal Basic auth Base64 string (Authorization: Basic YWRtaW46YWRtaW4=); replace that hard-coded value with a clear placeholder (e.g., Authorization: Basic <BASE64_CREDENTIALS> or Authorization: Basic {{BASE64_CREDENTIALS}}) and update every sample in the file that uses the same pattern (notably the curl block for the /api/server/v2/users/share endpoint and any other curl examples) so no real credentials are committed in examples.
🤖 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/asgardeo/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml`:
- Around line 13-14: Update the intro note that currently lists the scopes
`internal_org_user_share`, `internal_org_user_unshare`, and
`internal_org_user_shared_access_view` so they match the actual OAuth2 scope
names used by the operations and definitions (`internal_user_share`,
`internal_user_unshare`, `internal_user_shared_access_view`); do not modify any
operation sections—only edit the sentence in the intro note to replace the
`internal_org_user_*` tokens with the corresponding `internal_user_*` tokens to
keep scope names consistent across the file.
In
`@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml`:
- Around line 13-14: Update the OAuth2 scope names and all per-operation scope
references to use the internal_org_user_* prefix (matching the intro note and v1
API) instead of internal_user_*; specifically rename the scopes under
components.securitySchemes.OAuth2.scopes (replace any internal_user_share,
internal_user_unshare, internal_user_shared_access_view with
internal_org_user_share, internal_org_user_unshare,
internal_org_user_shared_access_view) and update every "Scope required" entry in
the operation objects to reference the corresponding internal_org_user_* scope
names so the definitions and per-operation requirements are consistent.
---
Duplicate comments:
In
`@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml`:
- Around line 22-28: The servers.url is tenant-scoped
(/t/{tenant-domain}/api/server/v2) but examples are org-scoped; change the
servers.url to the org-scoped base path and rename the variable accordingly:
update servers.url to use /o/{org-domain}/api/server/v2, replace the
tenant-domain variable with org-domain (keep default "carbon.super"), and keep
server-url as-is; ensure any references in this YAML use {org-domain} instead of
{tenant-domain} so the docs and examples are consistent.
- Around line 98-101: Replace the embedded Basic auth credential in the curl
samples by removing the actual Base64 token "Authorization: Basic
YWRtaW46YWRtaW4=" and using a placeholder such as "Authorization: Basic
<BASE64_USER_PASS>" (apply this change to every sample containing the header,
including the curl example for
'https://localhost:9443/o/api/server/v2/users/share'); ensure the placeholder is
consistent across the document and that no real credentials remain.
In `@en/identity-server/next/docs/apis/restapis/organization-user-share-v2.yaml`:
- Around line 559-592: Update the example link hrefs so they use the tenant base
path declared in servers.url instead of the shortcut /o path: replace
occurrences of "/o/api/server/v2" in the example objects (the links.href entries
and any Link example) with "/t/{tenant-domain}/api/server/v2" to match the
servers.url base; ensure both the top-level example under sharingMode ->
organizations -> links.href and the sharedWithSelected -> value -> links.href
(and the duplicate occurrences later in the file) are updated so all example
URLs consistently use the tenant base path.
- Around line 97-101: The curl examples in the YAML embed a literal Basic auth
Base64 string (Authorization: Basic YWRtaW46YWRtaW4=); replace that hard-coded
value with a clear placeholder (e.g., Authorization: Basic <BASE64_CREDENTIALS>
or Authorization: Basic {{BASE64_CREDENTIALS}}) and update every sample in the
file that uses the same pattern (notably the curl block for the
/api/server/v2/users/share endpoint and any other curl examples) so no real
credentials are committed in examples.
ℹ️ Review info
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
en/asgardeo/docs/apis/organization-apis/restapis/organization-user-share-v2.yamlen/asgardeo/docs/apis/organization-apis/restapis/organization-user-share.yamlen/asgardeo/docs/apis/restapis/organization-user-share-v2.yamlen/asgardeo/docs/apis/restapis/organization-user-share.yamlen/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yamlen/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share.yamlen/identity-server/next/docs/apis/restapis/organization-user-share-v2.yamlen/identity-server/next/docs/apis/restapis/organization-user-share.yamlen/identity-server/next/mkdocs.yml
✅ Files skipped from review due to trivial changes (4)
- en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share.yaml
- en/asgardeo/docs/apis/restapis/organization-user-share.yaml
- en/asgardeo/docs/apis/organization-apis/restapis/organization-user-share.yaml
- en/identity-server/next/docs/apis/restapis/organization-user-share.yaml
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (3)
en/asgardeo/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml (1)
13-14: Re-validate the shared-scope note against v1 spec.Line 13-14 says v1 and v2 share
internal_org_user_*scopes. Please confirm v1 actually uses the same scope names; if v1 still usesinternal_user_*, the note is inaccurate and should be corrected to avoid misleading readers.#!/bin/bash # Verify v1 scope naming vs v2 in the repo set -euo pipefail echo "=== v1 specs ===" fd -a "organization-user-share-v1.yaml" -t f -x rg -n "internal_.*user_.*" {} echo "=== v2 spec (this file) ===" rg -n "internal_.*user_.*" "en/asgardeo/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/asgardeo/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml` around lines 13 - 14, Verify the actual scope names used in the v1 spec (organization-user-share-v1.yaml) versus the v2 spec by searching for scope patterns like "internal_org_user_*" and "internal_user_*"; if v1 uses "internal_user_*" (not "internal_org_user_*"), update the shared-scope note in the v2 spec (organization-user-share-v2.yaml) to correct the scope names or explain the mapping (e.g., v1 uses internal_user_share while v2 uses internal_org_user_share), and run the provided verification script/rg/fd checks to confirm the change before committing.en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml (2)
22-28:⚠️ Potential issue | 🟠 MajorAlign the
serversbase URL with the sample paths.Line 23 uses
/t/{tenant-domain}/o/api/server/v2while every curl sample in this spec uses/o/api/server/v2. Swagger/Redoc will default to the server URL, so “Try it out” will hit a different base than the examples. Consider adding a super‑tenant server entry or updating all samples to include the tenant segment.🧭 Suggested update (add super‑tenant server entry)
servers: - - url: 'https://{server-url}/t/{tenant-domain}/o/api/server/v2' - variables: - tenant-domain: - default: "carbon.super" - server-url: - default: "localhost:9443" + - url: 'https://{server-url}/o/api/server/v2' + variables: + server-url: + default: "localhost:9443" + - url: 'https://{server-url}/t/{tenant-domain}/o/api/server/v2' + variables: + tenant-domain: + default: "carbon.super" + server-url: + default: "localhost:9443"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml` around lines 22 - 28, The servers entry currently uses '/t/{tenant-domain}/o/api/server/v2' which mismatches the curl samples that call '/o/api/server/v2'; update the OpenAPI servers block to align with samples by adding a super‑tenant server entry (e.g., a second servers item using 'https://{server-url}/o/api/server/v2') or alternatively update all sample paths to include '/t/{tenant-domain}/o/api/server/v2'; adjust the variables (tenant-domain, server-url) as needed so the "Try it out" base matches the examples.
98-101:⚠️ Potential issue | 🟠 MajorReplace the hard‑coded Basic auth value in examples.
Line 101 includes a real Base64 credential string; even in docs this looks like embedded credentials and trips secret scanners. Please use a placeholder and apply the change across all curl samples.
🔐 Suggested update (apply to all samples)
- -H 'Authorization: Basic YWRtaW46YWRtaW4=' \ + -H 'Authorization: Basic {base64_username_password}' \🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml` around lines 98 - 101, The examples in the OpenAPI sample for the users/share endpoint include a hard‑coded Base64 Basic auth value in the Authorization header; replace that literal "Basic YWRtaW46YWRtaW4=" with a placeholder (e.g. "Basic <base64‑credentials>" or "Bearer <token>") in the curl examples and any other Authorization header occurrences so secret scanners aren't triggered; update all curl samples under the organization-user-share-v2.yaml file (look for the 'curl' blocks and the Authorization header for the /o/api/server/v2/users/share endpoint) to use the placeholder consistently.
🤖 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/asgardeo/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml`:
- Around line 575-598: The orgRef example values and any API link hrefs in this
YAML (specifically the orgRef keys and the links.href value shown) are missing
the required "/o/" path segment; update each orgRef value (e.g., the orgRef
entries currently like "/t/wso2.com/api/server/v1/organizations/..." ) to
include the "/o/" prefix ("/t/wso2.com/o/api/server/v1/organizations/...") and
likewise update the links.href entries (e.g.,
"/t/{root-organization-name}/o/api/server/v2/..." should be consistent) so all
example paths include "/o/" to match the base server URL.
---
Duplicate comments:
In
`@en/asgardeo/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml`:
- Around line 13-14: Verify the actual scope names used in the v1 spec
(organization-user-share-v1.yaml) versus the v2 spec by searching for scope
patterns like "internal_org_user_*" and "internal_user_*"; if v1 uses
"internal_user_*" (not "internal_org_user_*"), update the shared-scope note in
the v2 spec (organization-user-share-v2.yaml) to correct the scope names or
explain the mapping (e.g., v1 uses internal_user_share while v2 uses
internal_org_user_share), and run the provided verification script/rg/fd checks
to confirm the change before committing.
In
`@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml`:
- Around line 22-28: The servers entry currently uses
'/t/{tenant-domain}/o/api/server/v2' which mismatches the curl samples that call
'/o/api/server/v2'; update the OpenAPI servers block to align with samples by
adding a super‑tenant server entry (e.g., a second servers item using
'https://{server-url}/o/api/server/v2') or alternatively update all sample paths
to include '/t/{tenant-domain}/o/api/server/v2'; adjust the variables
(tenant-domain, server-url) as needed so the "Try it out" base matches the
examples.
- Around line 98-101: The examples in the OpenAPI sample for the users/share
endpoint include a hard‑coded Base64 Basic auth value in the Authorization
header; replace that literal "Basic YWRtaW46YWRtaW4=" with a placeholder (e.g.
"Basic <base64‑credentials>" or "Bearer <token>") in the curl examples and any
other Authorization header occurrences so secret scanners aren't triggered;
update all curl samples under the organization-user-share-v2.yaml file (look for
the 'curl' blocks and the Authorization header for the
/o/api/server/v2/users/share endpoint) to use the placeholder consistently.
ℹ️ Review info
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
en/asgardeo/docs/apis/organization-apis/restapis/organization-user-share-v2.yamlen/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml (1)
22-28:⚠️ Potential issue | 🟠 MajorServer base path still conflicts with curl samples and
hrefexamples.The
servers.urlresolves tohttps://localhost:9443/t/carbon.super/o/api/server/v2, but every curl sample (e.g., line 98) andhrefexample (e.g., line 561) uses/o/api/server/v2without the/t/{tenant-domain}segment. It appears the previous fix appended/o/but didn't remove the/t/{tenant-domain}prefix.🧭 Suggested fix
servers: - - url: 'https://{server-url}/t/{tenant-domain}/o/api/server/v2' - variables: - tenant-domain: - default: "carbon.super" - server-url: - default: "localhost:9443" + - url: 'https://{server-url}/o/api/server/v2' + variables: + server-url: + default: "localhost:9443"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml` around lines 22 - 28, The OpenAPI `servers.url` currently includes the unwanted tenant segment (`/t/{tenant-domain}/o/api/server/v2`) which conflicts with existing curl samples and href examples that use `/o/api/server/v2`; update the `servers.url` to `https://{server-url}/o/api/server/v2` (remove the `/t/{tenant-domain}` prefix) and remove the `tenant-domain` variable definition (or adjust examples to include tenant if that was intended); ensure references to `servers.url`, `tenant-domain`, and `server-url` in the document are consistent after the change.
🧹 Nitpick comments (5)
en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml (3)
818-820: Sameenumgap forUserSharingPatchOperation.op.
oponly documentsaddandremovein the description; adding anenumkeeps it consistent with other constrained fields in this spec.♻️ Suggested fix
op: type: string + enum: + - add + - remove description: "Operation type. Supported values: `add`, `remove`."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml` around lines 818 - 820, The schema for UserSharingPatchOperation.op lacks an enum constraint; update the OpenAPI definition for the field named op in the UserSharingPatchOperation object to add an enum containing "add" and "remove" so the documented allowed values are enforced consistently with other constrained fields in the spec.
844-857: Clarify themodedefault vs "omit entireroleAssignment" semantics.
RoleAssignment.modedeclaresdefault: SELECTED, so if a consumer provides aroleAssignmentobject without specifyingmode, the schema impliesSELECTED. Meanwhile, the description onUserOrgShareConfig.roleAssignment(line 736) states that omitting the entire field meansmode = NONE. While technically non-contradictory, this subtlety is easy to misread. Consider adding a brief note in themodedescription to disambiguate, e.g.: "Defaults to SELECTED when roleAssignment is provided. Omitting roleAssignment entirely is equivalent to NONE."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml` around lines 844 - 857, Clarify the semantics mismatch by updating the description for RoleAssignment.mode to state that the declared default applies only when a roleAssignment object is present: e.g., add a sentence to mode's description like "Defaults to SELECTED when a roleAssignment object is provided; omitting the entire UserOrgShareConfig.roleAssignment is equivalent to mode = NONE." Reference RoleAssignment.mode and UserOrgShareConfig.roleAssignment so readers know this default only applies when the field exists.
725-731: Consider usingenumfor constrainedpolicyfields.
UserOrgShareConfig.policyandUserShareAllRequestBody.policydocument specific allowed values in the description only. By contrast,SharingModeAll.policy(line 903) andSharingModeSelected.policy(line 920) correctly useenum. Addingenumhere would improve code-generation accuracy and keep the spec internally consistent.♻️ Suggested fix for UserOrgShareConfig.policy
policy: type: string + enum: + - SELECTED_ORG_ONLY + - SELECTED_ORG_WITH_ALL_EXISTING_AND_FUTURE_CHILDREN description: |- Sharing scope for this organization. - - Possible values: - - `SELECTED_ORG_ONLY` - - `SELECTED_ORG_WITH_ALL_EXISTING_AND_FUTURE_CHILDREN`♻️ Suggested fix for UserShareAllRequestBody.policy
policy: type: string + enum: + - ALL_EXISTING_AND_FUTURE_ORGS description: |- Global sharing policy. - - Possible values: - - `ALL_EXISTING_AND_FUTURE_ORGS`Also applies to: 749-755
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml` around lines 725 - 731, The spec documents allowed values for policy in UserOrgShareConfig.policy and UserShareAllRequestBody.policy only in the description; update both schema entries (and the similar block around lines 749-755) to add an explicit enum listing the permitted string values (e.g., include "SELECTED_ORG_ONLY" and any other values referenced elsewhere such as those used by SharingModeAll.policy and SharingModeSelected.policy) so codegen and validation use the same constrained set as the other SharingMode* schemas.en/identity-server/next/docs/apis/restapis/organization-user-share-v2.yaml (2)
724-731: Same missingenumconstraints as the org-apis variant.
UserOrgShareConfig.policy,UserShareAllRequestBody.policy, andUserSharingPatchOperation.opdocument allowed values in descriptions only, whileSharingModeAll.policyandSharingModeSelected.policyuseenum. Consider addingenumfor consistency and better code-generation support (same suggestion as in the org-apis file).Also applies to: 748-755, 817-819
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/restapis/organization-user-share-v2.yaml` around lines 724 - 731, The OpenAPI spec documents allowed values in descriptions but omits explicit enum constraints for several schemas; add an enum listing the two allowed values ("SELECTED_ORG_ONLY" and "SELECTED_ORG_WITH_ALL_EXISTING_AND_FUTURE_CHILDREN") to UserOrgShareConfig.policy, UserShareAllRequestBody.policy, and UserSharingPatchOperation.op so they match SharingModeAll.policy and SharingModeSelected.policy and enable consistent validation and codegen; update those schema entries to include the enum array alongside the existing type/description.
843-856: Samemodedefault ambiguity as the org-apis variant.
RoleAssignment.modehasdefault: SELECTED, while omitting the entireroleAssignmentobject means no roles. Consider adding a clarifying note tomode's description to reduce consumer confusion.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/restapis/organization-user-share-v2.yaml` around lines 843 - 856, The default for RoleAssignment.mode is currently SELECTED which conflicts with omitting roleAssignment meaning no roles; update the description for the RoleAssignment.mode property (symbol: mode under RoleAssignment) to explicitly state that the default is SELECTED but omitting the entire roleAssignment object or setting mode to NONE results in no role assignments, and clarify when the roles array is required (i.e., required only when mode = SELECTED) so consumers aren’t confused by the default value.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In
`@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml`:
- Around line 22-28: The OpenAPI `servers.url` currently includes the unwanted
tenant segment (`/t/{tenant-domain}/o/api/server/v2`) which conflicts with
existing curl samples and href examples that use `/o/api/server/v2`; update the
`servers.url` to `https://{server-url}/o/api/server/v2` (remove the
`/t/{tenant-domain}` prefix) and remove the `tenant-domain` variable definition
(or adjust examples to include tenant if that was intended); ensure references
to `servers.url`, `tenant-domain`, and `server-url` in the document are
consistent after the change.
---
Nitpick comments:
In
`@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml`:
- Around line 818-820: The schema for UserSharingPatchOperation.op lacks an enum
constraint; update the OpenAPI definition for the field named op in the
UserSharingPatchOperation object to add an enum containing "add" and "remove" so
the documented allowed values are enforced consistently with other constrained
fields in the spec.
- Around line 844-857: Clarify the semantics mismatch by updating the
description for RoleAssignment.mode to state that the declared default applies
only when a roleAssignment object is present: e.g., add a sentence to mode's
description like "Defaults to SELECTED when a roleAssignment object is provided;
omitting the entire UserOrgShareConfig.roleAssignment is equivalent to mode =
NONE." Reference RoleAssignment.mode and UserOrgShareConfig.roleAssignment so
readers know this default only applies when the field exists.
- Around line 725-731: The spec documents allowed values for policy in
UserOrgShareConfig.policy and UserShareAllRequestBody.policy only in the
description; update both schema entries (and the similar block around lines
749-755) to add an explicit enum listing the permitted string values (e.g.,
include "SELECTED_ORG_ONLY" and any other values referenced elsewhere such as
those used by SharingModeAll.policy and SharingModeSelected.policy) so codegen
and validation use the same constrained set as the other SharingMode* schemas.
In `@en/identity-server/next/docs/apis/restapis/organization-user-share-v2.yaml`:
- Around line 724-731: The OpenAPI spec documents allowed values in descriptions
but omits explicit enum constraints for several schemas; add an enum listing the
two allowed values ("SELECTED_ORG_ONLY" and
"SELECTED_ORG_WITH_ALL_EXISTING_AND_FUTURE_CHILDREN") to
UserOrgShareConfig.policy, UserShareAllRequestBody.policy, and
UserSharingPatchOperation.op so they match SharingModeAll.policy and
SharingModeSelected.policy and enable consistent validation and codegen; update
those schema entries to include the enum array alongside the existing
type/description.
- Around line 843-856: The default for RoleAssignment.mode is currently SELECTED
which conflicts with omitting roleAssignment meaning no roles; update the
description for the RoleAssignment.mode property (symbol: mode under
RoleAssignment) to explicitly state that the default is SELECTED but omitting
the entire roleAssignment object or setting mode to NONE results in no role
assignments, and clarify when the roles array is required (i.e., required only
when mode = SELECTED) so consumers aren’t confused by the default value.
ℹ️ Review info
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yamlen/identity-server/next/docs/apis/restapis/organization-user-share-v2.yaml
9 tasks
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml (1)
577-577: AlignorgRefpaths with other organization-apis examples.The
orgRefpaths in this file omit the/o/prefix (e.g.,/t/wso2.com/api/server/v1/organizations/...), while theorganization-management.yamlfile includes it in response examples (e.g.,/o/api/server/v1/organizations/...). Update these paths for consistency across the organization-apis documentation.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml` at line 577, Update the orgRef values to include the missing "/o/" segment so they match other organization-apis examples; specifically change occurrences like orgRef: "/t/wso2.com/api/server/v1/organizations/b028ca17-8f89-449c-ae27-fa955e66465d" to include the "/o/" prefix (e.g., orgRef: "/o/t/wso2.com/api/server/v1/organizations/b028ca17-8f89-449c-ae27-fa955e66465d"), ensuring any other orgRef keys in this YAML are updated for consistency with organization-management.yaml.
🤖 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/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yaml`:
- Line 577: Update the orgRef values to include the missing "/o/" segment so
they match other organization-apis examples; specifically change occurrences
like orgRef:
"/t/wso2.com/api/server/v1/organizations/b028ca17-8f89-449c-ae27-fa955e66465d"
to include the "/o/" prefix (e.g., orgRef:
"/o/t/wso2.com/api/server/v1/organizations/b028ca17-8f89-449c-ae27-fa955e66465d"),
ensuring any other orgRef keys in this YAML are updated for consistency with
organization-management.yaml.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 4dbcaab6-339e-4282-9bd2-a11ec311a017
📒 Files selected for processing (5)
en/asgardeo/docs/apis/organization-apis/restapis/organization-user-share-v2.yamlen/asgardeo/docs/apis/restapis/organization-user-share-v2.yamlen/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share-v2.yamlen/identity-server/next/docs/apis/restapis/organization-user-share-v2.yamlen/identity-server/next/mkdocs.yml
🚧 Files skipped from review as they are similar to previous changes (1)
- en/identity-server/next/mkdocs.yml
himeshsiriwardana
approved these changes
Mar 10, 2026
himeshsiriwardana
force-pushed
the
feature/user-share-v2
branch
from
25bff39 to
3a414c4
Compare
This was referenced Mar 11, 2026
Restructure shared user sharing mode resolution
wso2-extensions/identity-organization-management#611
Merged
BimsaraBodaragama
changed the title
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
3 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
Add documentation and OpenAPI definitions for the Organization User Share V2 APIs in both Asgardeo and Identity Server docs.
Goals
Approach
organization-apisandrestapispaths.en/asgardeo/mkdocs.ymlanden/identity-server/next/mkdocs.ymlto include the new docs in navigation.Related PRs
Related Issues
Summary by CodeRabbit
New Features
Documentation