Add end-user credential management REST API v2 documentation#6185
Open
pamodaaw wants to merge 2 commits into
Open
Add end-user credential management REST API v2 documentation#6185pamodaaw wants to merge 2 commits into
pamodaaw wants to merge 2 commits into
Conversation
Contributor
📝 WalkthroughWalkthroughThis PR introduces OpenAPI 3.0 specifications for the End-User Credential Management v2 REST API, deprecates the v1 API, creates Redoc documentation pages, and updates mkdocs navigation to display both API versions for both WSO2 Identity Server and Asgardeo documentation sets. ChangesEnd-User Credential Management v2 API Documentation
Possibly related issues
Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 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 current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml`:
- Around line 16-18: Global security currently requires OAuth2 but uses an empty
scope array and the authorizationCode.flow.scopes object uses generic keys
(read/create/delete) instead of the canonical scope names; rename the scope keys
under securitySchemes.OAuth2.flows.authorizationCode.scopes to the actual scope
names internal_user_credential_mgt_view, internal_user_credential_mgt_create,
internal_user_credential_mgt_delete (mapping each to the existing description
values), and then enforce those scopes by replacing the global "security: -
OAuth2: []" with per-operation security entries (or update the global security
list) that explicitly declare the required scopes, e.g. for list/view operations
use "security: - OAuth2: [internal_user_credential_mgt_view]" and for
create/delete use the corresponding internal_user_credential_mgt_create or
internal_user_credential_mgt_delete scopes so the OpenAPI contract enforces the
documented requirements.
In
`@en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management.yaml`:
- Line 4: Both v1 OpenAPI specs have a bad relative link on their migration
banner; update the deprecation link in each file so it points one directory up
to the v2 Redoc page: in
en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management.yaml
(lines 4-4) change the link target to
../end-user-credential-management-v2-rest-api.md, and in
en/identity-server/next/docs/apis/restapis/end-user-credential-management.yaml
(lines 4-4) make the identical change to
../end-user-credential-management-v2-rest-api.md.
In
`@en/identity-server/next/docs/apis/restapis/end-user-credential-management-v2.yaml`:
- Around line 16-18: The global security block currently sets OAuth2 with empty
scopes and the OAuth2 securitySchemes.scopes keys (read/create/delete) don't
match the documented scope names; update each operation in the OpenAPI files to
include a per-operation security block that lists OAuth2 with the exact scope
required (e.g., OAuth2: [ "internal_user_credential_mgt_view" ] for
read/list/get operations, OAuth2: [ "internal_user_credential_mgt_create" ] for
create operations, and OAuth2: [ "internal_user_credential_mgt_delete" ] for
delete operations) while keeping BasicAuth where appropriate, and modify
securitySchemes.OAuth2.scopes to use the matching keys
internal_user_credential_mgt_view, internal_user_credential_mgt_create, and
internal_user_credential_mgt_delete so the scheme keys align with the operation
texts.
🪄 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: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 65f92aa4-9ebd-48c3-9f3d-cb2f02d77991
📒 Files selected for processing (7)
en/identity-server/next/docs/apis/end-user-credential-management-v2-rest-api.mden/identity-server/next/docs/apis/organization-apis/end-user-credential-management-v2-rest-api.mden/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yamlen/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management.yamlen/identity-server/next/docs/apis/restapis/end-user-credential-management-v2.yamlen/identity-server/next/docs/apis/restapis/end-user-credential-management.yamlen/identity-server/next/mkdocs.yml
Comment on lines
+16
to
+18
| security: | ||
| - OAuth2: [] | ||
| - BasicAuth: [] |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml"
# Show the exact sections around the reported lines
echo "=== Header/global security (lines 1-120) ==="
nl -ba "$FILE" | sed -n '1,140p'
echo "=== OAuth2 scopes section (lines 320-410) ==="
nl -ba "$FILE" | sed -n '320,430p'
echo "=== Security requirements inside operations (search for 'security:' and 'internal_user_credential_mgt') ==="
rg -n "internal_user_credential_mgt_|security:" "$FILE" | head -n 200Repository: wso2/docs-is
Length of output: 162
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml"
echo "=== Header/global security (lines 1-160) ==="
awk '{printf "%6d %s\n", NR, $0}' "$FILE" | sed -n '1,160p'
echo "=== OAuth2 scopes section (lines 300-430) ==="
awk '{printf "%6d %s\n", NR, $0}' "$FILE" | sed -n '300,430p'
echo "=== All lines containing internal_user_credential_mgt or operation-level security ==="
rg -n "(internal_user_credential_mgt_|^\\s*security\\s*:)" "$FILE" | head -n 200Repository: wso2/docs-is
Length of output: 10127
Fix OpenAPI OAuth2 security modeling to enforce internal_user_credential_mgt_* scopes
- Global
securitysetsOAuth2: [](OAuth2 is required but no OAuth scopes are enforced), while operations only state required scopes in their descriptions. securitySchemes.OAuth2.flows.authorizationCode.scopesdefines scope keys asread/delete/createwithinternal_user_credential_mgt_*values; OpenAPI expects the canonical scope names to be the object keys.- Rename the OAuth2
scopeskeys tointernal_user_credential_mgt_view|create|deleteand add per-operationsecurityrequirements usingOAuth2: [internal_user_credential_mgt_...](or adjust global security) so contract enforcement matches the documented scope requirements.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml`
around lines 16 - 18, Global security currently requires OAuth2 but uses an
empty scope array and the authorizationCode.flow.scopes object uses generic keys
(read/create/delete) instead of the canonical scope names; rename the scope keys
under securitySchemes.OAuth2.flows.authorizationCode.scopes to the actual scope
names internal_user_credential_mgt_view, internal_user_credential_mgt_create,
internal_user_credential_mgt_delete (mapping each to the existing description
values), and then enforce those scopes by replacing the global "security: -
OAuth2: []" with per-operation security entries (or update the global security
list) that explicitly declare the required scopes, e.g. for list/view operations
use "security: - OAuth2: [internal_user_credential_mgt_view]" and for
create/delete use the corresponding internal_user_credential_mgt_create or
internal_user_credential_mgt_delete scopes so the OpenAPI contract enforces the
documented requirements.
| info: | ||
| description: | | ||
| The Credential Management REST API provides a comprehensive interface to list and delete | ||
| This API is deprecated. Use the [User Credential Management REST API v2](end-user-credential-management-v2-rest-api.md) instead. |
Contributor
There was a problem hiding this comment.
Fix the shared deprecation-link path.
Both v1 specs point to the v2 Redoc page with a path that needs one ../ hop. Update both links so the migration banner lands on the intended page.
en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management.yaml#L4-L4: change the link to../end-user-credential-management-v2-rest-api.md.en/identity-server/next/docs/apis/restapis/end-user-credential-management.yaml#L4-L4: change the link to../end-user-credential-management-v2-rest-api.md.
📍 Affects 2 files
en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management.yaml#L4-L4(this comment)en/identity-server/next/docs/apis/restapis/end-user-credential-management.yaml#L4-L4
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management.yaml`
at line 4, Both v1 OpenAPI specs have a bad relative link on their migration
banner; update the deprecation link in each file so it points one directory up
to the v2 Redoc page: in
en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management.yaml
(lines 4-4) change the link target to
../end-user-credential-management-v2-rest-api.md, and in
en/identity-server/next/docs/apis/restapis/end-user-credential-management.yaml
(lines 4-4) make the identical change to
../end-user-credential-management-v2-rest-api.md.
Comment on lines
+16
to
+18
| security: | ||
| - OAuth2: [] | ||
| - BasicAuth: [] |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Locate the target file and (best-effort) related “organization” spec file(s)
target="en/identity-server/next/docs/apis/restapis/end-user-credential-management-v2.yaml"
echo "=== Target file header ==="
ls -l "$target" || true
echo
echo "=== Target file relevant lines (15-25, 340-380) ==="
sed -n '1,60p' "$target" | nl -ba | sed -n '1,80p'
echo
sed -n '330,410p' "$target" | nl -ba
echo
echo "=== Search for organization credential management spec ==="
# Find candidate files with similar naming
fd -a -t f '.*credential-management.*v2\.ya?ml$' en/identity-server/next/docs/apis/restapis | head -n 50
echo
echo "=== Show any matching “organization” spec OAuth2/security blocks ==="
fd -a -t f '*organization*credential*management*v2*.ya?ml' en/identity-server/next/docs/apis/restapis | while read -r f; do
echo "--- $f (top 80 lines) ---"
sed -n '1,80p' "$f" | nl -ba | sed -n '1,120p'
echo
echo "--- $f (security/scopes area around 340-430 if present) ---"
sed -n '330,430p' "$f" | nl -ba
echo "------------------------------------------------------------"
doneRepository: wso2/docs-is
Length of output: 330
🏁 Script executed:
#!/bin/bash
set -euo pipefail
target="en/identity-server/next/docs/apis/restapis/end-user-credential-management-v2.yaml"
echo "=== Target file head (1-120) ==="
sed -n '1,120p' "$target"
echo
echo "=== Target file around global security (8-30) ==="
sed -n '8,30p' "$target"
echo
echo "=== Target file around OAuth2 security/scopes (300-410) ==="
sed -n '300,410p' "$target"
echo
echo "=== List candidate “organization” spec files ==="
fd -a -t f '*credential*management*v2*.ya?ml' en/identity-server/next/docs/apis/restapis | head -n 50
echo
echo "=== Show security blocks in any organization-matching candidate ==="
for f in $(fd -a -t f '*credential*management*v2*.ya?ml' en/identity-server/next/docs/apis/restapis | grep -i 'organization' || true); do
echo "---- $f (global security, if any: lines 1-60) ----"
sed -n '1,60p' "$f"
echo
echo "---- $f (around 330-410) ----"
sed -n '330,410p' "$f"
echo "------------------------------------------------"
doneRepository: wso2/docs-is
Length of output: 7305
🏁 Script executed:
#!/bin/bash
set -euo pipefail
target="en/identity-server/next/docs/apis/restapis/end-user-credential-management-v2.yaml"
echo "=== Line-numbered global security (1-40) ==="
awk 'NR>=1 && NR<=40 {printf "%5d:%s\n", NR, $0}' "$target"
echo
echo "=== Find all occurrences of 'security:' in this file (with line numbers) ==="
rg -n "^[[:space:]]*security:" "$target" || true
echo
echo "=== Show paths section around first endpoint's security (if any) ==="
# Print a broad range where per-operation security would likely appear
awk 'NR>=40 && NR<=240 {printf "%5d:%s\n", NR, $0}' "$target" | sed -n '1,220p'
echo
echo "=== Show the OAuth2 security scheme scopes mapping (line-numbered) ==="
# narrow around securitySchemes block
awk 'NR>=250 && NR<=420 {printf "%5d:%s\n", NR, $0}' "$target" | sed -n '1,220p'
echo
echo "=== Search for related 'organization' credential-management v2 specs ==="
# Use glob (not regex) to avoid fd regex errors
fd --glob '*credential*management*v2*.ya?ml' en/identity-server/next/docs/apis/restapis | sort | head -n 200
echo
echo "=== Filter those candidates that contain 'organization' in filename ==="
fd --glob '*credential*management*v2*.ya?ml' en/identity-server/next/docs/apis/restapis | rg -i 'organization' || true
echo
echo "=== If an organization spec exists, dump its global+per-op security (first 80 lines + securitySchemes area) ==="
for f in $(fd --glob '*credential*management*v2*.ya?ml' en/identity-server/next/docs/apis/restapis | rg -i 'organization' || true); do
echo "---- $f ----"
awk 'NR>=1 && NR<=80 {printf "%5d:%s\n", NR, $0}' "$f"
echo
rg -n "^[[:space:]]*security:" "$f" || true
echo
rg -n "securitySchemes:" "$f" || true
# dump around securitySchemes if present
if rg -n "securitySchemes:" "$f" >/dev/null 2>&1; then
start=$(rg -n "securitySchemes:" "$f" | head -n1 | cut -d: -f1)
s=$((start-30)); e=$((start+120))
awk -v s="$s" -v e="$e" 'NR>=s && NR<=e {printf "%5d:%s\n", NR, $0}' "$f"
fi
doneRepository: wso2/docs-is
Length of output: 14283
🏁 Script executed:
#!/bin/bash
set -euo pipefail
base="en/identity-server/next/docs/apis/restapis"
echo "=== Candidate files with 'credential' and 'management' and 'v2' in name ==="
fd --glob '*credential*management*v2*.ya?ml' "$base" | sort | head -n 200
echo
echo "=== Search for end-user credential management v2 filename string in repo ==="
rg -n "end-user-credential-management-v2\.yaml" -S . || true
echo
echo "=== Search for 'organization' + 'credential management' in any YAML (filenames & contents) ==="
# filenames
fd --glob '*credential*management*v2*.ya?ml' "$base" | rg -i 'organization' || true
# contents (lightweight)
rg -n "organization.*credential|credential.*organization" "$base" -S --glob '*.y?ml' || true
echo
echo "=== Search for OAuth2 scopes keys 'internal_user_credential_mgt_' and see which files they appear in ==="
rg -n "internal_user_credential_mgt_" "$base" -S --glob '*.y?ml' || true
echo
echo "=== List all files that contain 'internal_org_credential_mgt_' (if used) ==="
rg -n "internal_org_credential_mgt_" "$base" -S --glob '*.y?ml' || trueRepository: wso2/docs-is
Length of output: 3067
🏁 Script executed:
#!/bin/bash
set -euo pipefail
org_yaml="en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml"
end_yaml="en/identity-server/next/docs/apis/restapis/end-user-credential-management-v2.yaml"
echo "=== Check both YAML paths exist ==="
ls -l "$end_yaml" || true
ls -l "$org_yaml" || true
echo
echo "=== Org YAML: global security (1-40) ==="
sed -n '1,60p' "$org_yaml" || true
echo
echo "=== Org YAML: find all 'security:' occurrences ==="
rg -n "^[[:space:]]*security:" "$org_yaml" || true
echo
echo "=== Org YAML: securitySchemes OAuth2 scopes (near end) ==="
# print region around components/securitySchemes if present
rg -n "securitySchemes:" "$org_yaml" || true
if rg -n "securitySchemes:" "$org_yaml" >/dev/null 2>&1; then
start=$(rg -n "securitySchemes:" "$org_yaml" | head -n1 | cut -d: -f1)
s=$((start-20)); e=$((start+120))
sed -n "${s},${e}p" "$org_yaml"
else
# fallback: show tail
sed -n '320,420p' "$org_yaml" || true
fi
echo
echo "=== End-user YAML: global security (1-40) ==="
sed -n '1,40p' "$end_yaml"
echo
echo "=== End-user YAML: find all 'security:' occurrences ==="
rg -n "^[[:space:]]*security:" "$end_yaml" || true
echo
echo "=== End-user YAML: OAuth2 scopes (near end) ==="
rg -n "securitySchemes:" "$end_yaml" || true
start=$(rg -n "securitySchemes:" "$end_yaml" | head -n1 | cut -d: -f1)
s=$((start-20)); e=$((start+120))
sed -n "${s},${e}p" "$end_yaml"Repository: wso2/docs-is
Length of output: 6331
Add per-operation OAuth2 scope requirements (and align OAuth2 scope keys) for credential management APIs
security:
- OAuth2: []
- BasicAuth: []- Global
securityusesOAuth2: [], so the OpenAPI contract does not require any OAuth2 scopes for the operations. - This spec has no per-operation
security:blocks; the requiredinternal_user_credential_mgt_*scopes appear only in operation descriptions. securitySchemes.OAuth2...scopesuses keysread/create/deletemapped tointernal_user_credential_mgt_*values, which conflicts with the scope names stated in the per-endpoint text.
Update both en/identity-server/next/docs/apis/restapis/end-user-credential-management-v2.yaml and en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml to (1) add per-operation security for OAuth2 and (2) make the OAuth2 scope keys match the internal_user_credential_mgt_{view,create,delete} scope names used in the operation text.
Also applies to: 357-366
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@en/identity-server/next/docs/apis/restapis/end-user-credential-management-v2.yaml`
around lines 16 - 18, The global security block currently sets OAuth2 with empty
scopes and the OAuth2 securitySchemes.scopes keys (read/create/delete) don't
match the documented scope names; update each operation in the OpenAPI files to
include a per-operation security block that lists OAuth2 with the exact scope
required (e.g., OAuth2: [ "internal_user_credential_mgt_view" ] for
read/list/get operations, OAuth2: [ "internal_user_credential_mgt_create" ] for
create operations, and OAuth2: [ "internal_user_credential_mgt_delete" ] for
delete operations) while keeping BasicAuth where appropriate, and modify
securitySchemes.OAuth2.scopes to use the matching keys
internal_user_credential_mgt_view, internal_user_credential_mgt_create, and
internal_user_credential_mgt_delete so the scheme keys align with the operation
texts.
pamodaaw
force-pushed
the
end-user-credential-management-v2
branch
from
d30e016 to
9a27472
Compare
coderabbitai
Bot
added
Team/User & Identity Administration
and removed
Team/API Access Mgt & Authorization
labels
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@en/identity-server/next/mkdocs.yml`:
- Line 1299: The credential management API navigation structure is inconsistent:
the v1 (deprecated) entry appears under "Server configuration API" at line 1299,
but the v2 entry is only under "End User APIs" at line 1382, whereas the
Organization APIs section (lines 1361-1362) correctly groups both v1 and v2
together. To fix this discoverability issue, add the v2 "User credential
management API" entry under "Server configuration API" section immediately after
the v1 deprecated entry at line 1299 to match the Organization APIs pattern, and
ensure the End User APIs entry at line 1382 is either removed if redundant or
updated to clarify its purpose.
🪄 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: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 1cc0e72a-744a-46ea-a105-e98098bc32fe
📒 Files selected for processing (7)
en/identity-server/next/docs/apis/end-user-credential-management-v2-rest-api.mden/identity-server/next/docs/apis/organization-apis/end-user-credential-management-v2-rest-api.mden/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yamlen/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management.yamlen/identity-server/next/docs/apis/restapis/end-user-credential-management-v2.yamlen/identity-server/next/docs/apis/restapis/end-user-credential-management.yamlen/identity-server/next/mkdocs.yml
✅ Files skipped from review due to trivial changes (4)
- en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management.yaml
- en/identity-server/next/docs/apis/end-user-credential-management-v2-rest-api.md
- en/identity-server/next/docs/apis/organization-apis/end-user-credential-management-v2-rest-api.md
- en/identity-server/next/docs/apis/restapis/end-user-credential-management.yaml
| - Session management API: apis/session-mgt-rest-api.md | ||
| - Server configuration API: apis/configs-rest-api.md | ||
| - User credential management API: apis/end-user-credential-management-rest-api.md | ||
| - User credential management API (deprecated): apis/end-user-credential-management-rest-api.md |
Contributor
There was a problem hiding this comment.
Inconsistent navigation structure for credential management API v1→v2 migration.
The navigation treats the v1-to-v2 transition differently across API contexts:
- Organization APIs (lines 1361-1362): Lists both "User credential management API (deprecated)" and "User credential management API" (v2) together in the same section — clear migration path.
- Server/End User split: Line 1299 has v1 (deprecated) under "Server configuration API", but line 1382 places v2 under "End User APIs" instead of adding it to "Server configuration API".
This creates a discoverability problem: users looking in "Server configuration API" for the v2 endpoint won't find it there.
🗂️ Suggested fix: align Server APIs with Organization APIs pattern
Add the v2 entry under "Server configuration API" to match the Organization APIs pattern:
- Server configuration API: apis/configs-rest-api.md
- User credential management API (deprecated): apis/end-user-credential-management-rest-api.md
+ - User credential management API: apis/end-user-credential-management-v2-rest-api.md
- User Functionality management API: apis/user-functionality-mgt-rest-api.mdAnd update the End User APIs entry title to clarify it's also v2 (or remove it if redundant):
- Push Notification Device API: apis/push-notification-device-rest-api.md
- User account association API: apis/me-association-rest-api.md
- - User credential management API: apis/end-user-credential-management-v2-rest-api.md
+ - User credential management API (v2): apis/end-user-credential-management-v2-rest-api.md
- User discoverable application API: apis/user-discoverable-applications.mdThis way, both versions are discoverable in the same section where users expect to find them.
Also applies to: 1361-1362, 1382-1382
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/identity-server/next/mkdocs.yml` at line 1299, The credential management
API navigation structure is inconsistent: the v1 (deprecated) entry appears
under "Server configuration API" at line 1299, but the v2 entry is only under
"End User APIs" at line 1382, whereas the Organization APIs section (lines
1361-1362) correctly groups both v1 and v2 together. To fix this discoverability
issue, add the v2 "User credential management API" entry under "Server
configuration API" section immediately after the v1 deprecated entry at line
1299 to match the Organization APIs pattern, and ensure the End User APIs entry
at line 1382 is either removed if redundant or updated to clarify its purpose.
Contributor
Author
There was a problem hiding this comment.
Already addressed — the link now points one dir up to ../end-user-credential-management-v2-rest-api/. Keeping it extensionless on purpose: this link lives inside the OpenAPI YAML that Redoc renders at runtime, which MkDocs doesn't post-process, so a .md target wouldn't be rewritten and would 404. Verified both v1 pages resolve to their v2 page (200) locally.
Contributor
There was a problem hiding this comment.
@pamodaaw, it looks like your explanation (extensionless relative links in the OpenAPI YAML for Redoc rendering) addresses a different concern than the one I raised. Your reasoning there is sound — Redoc renders at runtime outside MkDocs's link-rewriting pipeline, so extensionless paths are the right call.
My original concern was specifically about the mkdocs.yml navigation structure: v1 (deprecated) is listed under "Server configuration API", but v2 only appears under "End User APIs" — whereas the Organization APIs section groups both versions together in one place, giving a clear migration path.
That said, I recognize there's a valid semantic argument for the separate placement: the v2 API's base path changed from /api/server/v1 → /api/users/v2, so "End User APIs" is a more accurate home for v2. If this split placement is intentional (reflecting the architectural change in the API tier), I'm happy to withdraw the navigation suggestion. Could you confirm whether the separate placement is by design?
pamodaaw
force-pushed
the
end-user-credential-management-v2
branch
from
9a27472 to
fb850ac
Compare
- Add OpenAPI v2 specs and Redoc pages for the user credential management API (main and organization level), mirroring the Identity Server docs - Mark the v1 specs as deprecated with a migration link to v2 - Update mkdocs nav: v2 under End User APIs, v1 (deprecated) retained, and both v1/v2 listed under Organization APIs Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml`:
- Around line 4-6: Update both Asgardeo credential management OpenAPI spec files
to align with Asgardeo conventions. In
en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml: replace
"WSO2 Identity Server" with Asgardeo/WSO2 Identity Platform wording in lines
4-6, update the servers section at lines 21-27 to use Asgardeo server URL
defaults and templates instead of localhost:9443, and update the OAuth
authorization and token endpoint defaults at lines 361-362 to match Asgardeo
patterns. Apply identical changes to the corresponding locations in
en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml:
product wording at lines 4-6, server URL alignment at lines 21-27, and OAuth
endpoint alignment at lines 361-362. Reference existing Asgardeo OpenAPI
documentation patterns in the repository as the model for these changes.
- Around line 16-18: The global security configuration with OAuth2: [] at lines
16-18 does not enforce any scopes, making the scope definitions (read, delete,
create) in securitySchemes unenforced. To fix this, apply the following changes
to both en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml
and
en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml:
(1) at lines 16-18, optionally remove OAuth2: [] and keep only BasicAuth: [] as
the global fallback if OAuth2 is not required globally, or leave it as-is if it
serves as a fallback; (2) at the GET operation around lines 30-38, add
operation-level security override with OAuth2: [read]; (3) at the POST operation
around lines 97-105, add operation-level security override with OAuth2:
[create]; (4) at the first DELETE operation around lines 164-171, add
operation-level security override with OAuth2: [delete]; (5) at the second
DELETE operation around lines 223-230, add operation-level security override
with OAuth2: [delete]. Operation-level security blocks override the global
security and allow the defined scopes to be enforced by generated clients and
documentation.
🪄 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: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 426c1b8d-8044-41cf-a945-af2d972ca113
📒 Files selected for processing (7)
en/asgardeo/docs/apis/end-user-credential-management-v2-rest-api.mden/asgardeo/docs/apis/organization-apis/end-user-credential-management-v2-rest-api.mden/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yamlen/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management.yamlen/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yamlen/asgardeo/docs/apis/restapis/end-user-credential-management.yamlen/asgardeo/mkdocs.yml
✅ Files skipped from review due to trivial changes (4)
- en/asgardeo/docs/apis/end-user-credential-management-v2-rest-api.md
- en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management.yaml
- en/asgardeo/docs/apis/restapis/end-user-credential-management.yaml
- en/asgardeo/docs/apis/organization-apis/end-user-credential-management-v2-rest-api.md
Comment on lines
+4
to
+6
| The Credential Management REST API v2 provides an interface to list and manage enrolled | ||
| credentials within the WSO2 Identity Server. The GET endpoint returns credentials grouped | ||
| by type. Supported credential types are passkey, push-auth, and backup-code. |
Contributor
There was a problem hiding this comment.
Align Asgardeo spec branding and endpoint defaults with Asgardeo conventions.
Both Asgardeo OpenAPI files still describe Identity Server and use localhost:9443 defaults for server and OAuth endpoints, which is likely to mislead consumers in published Asgardeo docs.
en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L4-L6: replace product wording from “WSO2 Identity Server” to Asgardeo/WSO2 Identity Platform wording used in Asgardeo docs.en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L21-L27: align server URL template/defaults with existing Asgardeo API-doc patterns.en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L361-L362: align OAuth authorization/token endpoint defaults with Asgardeo patterns.en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L4-L6: apply the same product wording correction.en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L21-L27: align server URL template/defaults similarly.en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L361-L362: align OAuth endpoints similarly.
Based on learnings, Asgardeo OpenAPI docs in this repo follow established server URL conventions and this file should match that repository pattern.
📍 Affects 2 files
en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L4-L6(this comment)en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L21-L27en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L361-L362en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L4-L6en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L21-L27en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L361-L362
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml` around
lines 4 - 6, Update both Asgardeo credential management OpenAPI spec files to
align with Asgardeo conventions. In
en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml: replace
"WSO2 Identity Server" with Asgardeo/WSO2 Identity Platform wording in lines
4-6, update the servers section at lines 21-27 to use Asgardeo server URL
defaults and templates instead of localhost:9443, and update the OAuth
authorization and token endpoint defaults at lines 361-362 to match Asgardeo
patterns. Apply identical changes to the corresponding locations in
en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml:
product wording at lines 4-6, server URL alignment at lines 21-27, and OAuth
endpoint alignment at lines 361-362. Reference existing Asgardeo OpenAPI
documentation patterns in the repository as the model for these changes.
Source: Learnings
Comment on lines
+16
to
+18
| security: | ||
| - OAuth2: [] | ||
| - BasicAuth: [] |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify OAuth2 scope requirements are empty globally and missing per-operation.
rg -n -C2 '^\s*security:\s*$|OAuth2:\s*\[\]' en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml
rg -n -C2 'operationId: getUserCredentialsById|operationId: createUserCredentialByType|operationId: deleteUserCredentialsByType|operationId: deleteUserCredentialById' en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yamlRepository: wso2/docs-is
Length of output: 5974
🏁 Script executed:
# Extract securitySchemes and check if OAuth2 has defined scopes
rg -n -A 10 'securitySchemes:' en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml
# Check for any operation-level security overrides
rg -n -B 2 -A 5 'security:' en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml | head -100Repository: wso2/docs-is
Length of output: 585
🏁 Script executed:
# Get the complete OAuth2 scopes definition
sed -n '353,375p' en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml
# Check if any operations have security overrides
rg -n -B 5 'security:' en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml | grep -A 5 "operationId\|security:"Repository: wso2/docs-is
Length of output: 521
🏁 Script executed:
# Check for security blocks within operation definitions (get, post, delete)
rg -n -B 10 'operationId: getUserCredentialsById' en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml | grep -A 10 'get:'
# Check if any operations have security overrides
rg -n '^\s+security:' en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml
# Same check for organization-apis file
rg -n '^\s+security:' en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yamlRepository: wso2/docs-is
Length of output: 552
Bind OAuth2 scopes at operation level instead of OAuth2: [] globally.
The spec defines scopes (read, delete, create) in securitySchemes but never enforces them in security requirements. With OAuth2: [] at lines 16-18, generated clients and documentation won't enforce the intended scope contract. Operations describe required scopes only in descriptions, which are not enforceable.
Add operation-level security overrides to both files:
en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yamlanden/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml:- GET operations (lines ~30-38):
security: - OAuth2: [read] - POST operations (lines ~97-105):
security: - OAuth2: [create] - DELETE operations (lines ~164-171, ~223-230):
security: - OAuth2: [delete]
- GET operations (lines ~30-38):
Alternatively, remove global OAuth2: [] and keep only BasicAuth: [] if OAuth2 is not required as a global fallback.
📍 Affects 2 files
en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L16-L18(this comment)en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L30-L38en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L97-L105en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L164-L171en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml#L223-L230en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L16-L18en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L30-L38en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L97-L105en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L164-L171en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml#L223-L230
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml` around
lines 16 - 18, The global security configuration with OAuth2: [] at lines 16-18
does not enforce any scopes, making the scope definitions (read, delete, create)
in securitySchemes unenforced. To fix this, apply the following changes to both
en/asgardeo/docs/apis/restapis/end-user-credential-management-v2.yaml and
en/asgardeo/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml:
(1) at lines 16-18, optionally remove OAuth2: [] and keep only BasicAuth: [] as
the global fallback if OAuth2 is not required globally, or leave it as-is if it
serves as a fallback; (2) at the GET operation around lines 30-38, add
operation-level security override with OAuth2: [read]; (3) at the POST operation
around lines 97-105, add operation-level security override with OAuth2:
[create]; (4) at the first DELETE operation around lines 164-171, add
operation-level security override with OAuth2: [delete]; (5) at the second
DELETE operation around lines 223-230, add operation-level security override
with OAuth2: [delete]. Operation-level security blocks override the global
security and allow the defined scopes to be enforced by generated clients and
documentation.
NipuniBhagya
approved these changes
Jun 19, 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
Adds documentation for the End User Credential Management REST API v2, introduced in identity-api-user#295 and identity-api-user#299.
V2 improves on V1 with:
/api/users/v2(was/api/server/v1)internal_user_credential_mgt_*(wasinternal_user_mgt_*)Changes
New files:
en/identity-server/next/docs/apis/restapis/end-user-credential-management-v2.yaml— V2 OpenAPI spec (regular API)en/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management-v2.yaml— V2 OpenAPI spec (organization API)en/identity-server/next/docs/apis/end-user-credential-management-v2-rest-api.md— Redoc page for V2en/identity-server/next/docs/apis/organization-apis/end-user-credential-management-v2-rest-api.md— Redoc page for V2 (org)Updated files:
en/identity-server/next/docs/apis/restapis/end-user-credential-management.yaml— deprecated title + deprecation notice in descriptionen/identity-server/next/docs/apis/organization-apis/restapis/end-user-credential-management.yaml— same deprecationen/identity-server/next/mkdocs.yml— both main and org-level nav entries updated to V1 (deprecated) / V2 sub-entriesRelated PRs
Test environment
N/A — documentation only
Security checks