Scim2 agent rest apis section #5807
Conversation
WalkthroughAdds OpenAPI 3.1 SCIM Agent management specs and Redoc pages for Asgardeo and Identity Server 7.2.0, introducing /Agents and /Agents/{agentId} endpoints, complete request/response schemas (create/update/list/role/patch/error), OAuth2/BasicAuth security schemes, examples, and mkdocs navigation entries. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Client
participant AuthServer as OAuth2 Server
participant SCIMAPI as SCIM Agents API
participant Store as Data Store
Note over Client,SCIMAPI: Create Agent (POST /Agents)
Client->>AuthServer: Exchange auth code for access token
AuthServer-->>Client: Access token
Client->>SCIMAPI: POST /Agents (Bearer token)
SCIMAPI->>AuthServer: Validate token and scopes
AuthServer-->>SCIMAPI: Token valid
SCIMAPI->>Store: Persist agent
Store-->>SCIMAPI: Created (id, meta)
SCIMAPI-->>Client: 201 Created (AgentResponseObject)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~40 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (3)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml (2)
853-869: ErrorConflict schema is defined but never referenced.The
ErrorConflictschema for 409 responses is defined but not used in any endpoint. Consider either adding 409 response handling to the POST endpoint (for duplicate agent creation) or removing this unused schema.Proposed fix: Add 409 response to POST /Agents
Add to POST /Agents responses after line 183:
description: Conflict - Agent already exists content: application/scim+json: schema: $ref: '#/components/schemas/ErrorConflict'
8-14: Server URL uses localhost defaults inappropriate for Asgardeo.The server URL defaults to
localhost:9443and uses tenant domaincarbon.super, which are Identity Server conventions. For Asgardeo documentation, consider using Asgardeo-appropriate defaults.Proposed fix
servers: - - url: https://{serverUrl}/t/{tenantDomain}/scim2 + - url: https://api.asgardeo.io/t/{organization-name}/scim2 variables: - serverUrl: - default: localhost:9443 - tenantDomain: - default: carbon.super + organization-name: + default: <your-organization-name>en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml (1)
853-869: ErrorConflict schema is defined but not used.Same issue as the Asgardeo spec: the ErrorConflict schema is defined but not referenced in any endpoint responses. Consider adding 409 response handling to POST /Agents or removing this unused schema.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
en/asgardeo/docs/apis/restapis/scim2-agents.yamlen/asgardeo/docs/apis/scim2-agents-rest-apis.mden/asgardeo/mkdocs.ymlen/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yamlen/identity-server/7.2.0/docs/apis/scim2-agents-rest-apis.mden/identity-server/7.2.0/mkdocs.yml
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: Thisara-Welmilla
Repo: wso2/docs-is PR: 5732
File: en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-update-profile-action-v1.x.md:273-273
Timestamp: 2025-12-01T15:31:14.922Z
Learning: In the wso2/docs-is repository documentation files, prefer unhyphenated compound adjectives (e.g., "SCIM API compliant", "Admin initiated profile update") over hyphenated versions for better readability and natural flow.
🪛 Checkov (3.2.334)
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml
[medium] 57-61: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
[medium] 57-61: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🔇 Additional comments (5)
en/asgardeo/docs/apis/scim2-agents-rest-apis.md (1)
1-5: LGTM!The Redoc documentation page follows the established pattern for API documentation in this repository.
en/identity-server/7.2.0/mkdocs.yml (1)
1076-1076: LGTM!The navigation entry is correctly placed under Management APIs in alphabetical order, consistent with the existing documentation structure.
en/identity-server/7.2.0/docs/apis/scim2-agents-rest-apis.md (1)
1-5: LGTM!The Redoc documentation page follows the established pattern and is consistent with the Asgardeo counterpart.
en/asgardeo/mkdocs.yml (1)
628-628: LGTM!The navigation entry is correctly placed under Management APIs in alphabetical order, consistent with the documentation structure.
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml (1)
1-7: Well-structured OpenAPI specification for SCIM 2.0 Agents API.The specification is comprehensive with proper CRUD operations, PATCH support, detailed schemas, error responses, and code samples. The security schemes and scope definitions are appropriate for the Identity Server context.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml (3)
58-71: Consider addingmaxItemsconstraint to array parameters.The
attributesandexcludedAttributesarray parameters lack amaxItemsconstraint, which could allow clients to send excessively large arrays. Consider adding a reasonable limit to prevent abuse and ensure API stability.🔎 Proposed fix
- name: attributes in: query description: A multi-valued list of strings indicating the names of resource attributes to include in the response. schema: type: array + maxItems: 100 items: type: string - name: excludedAttributes in: query description: A multi-valued list of strings indicating the names of resource attributes to exclude in the response. schema: type: array + maxItems: 100 items: type: string
858-874: Remove unusedErrorConflictschema.The
ErrorConflictschema is defined but not referenced by any endpoint. No operation returns a 409 status code. Consider removing this schema to reduce maintenance overhead, or add it to relevant endpoints if conflict scenarios are expected (e.g., duplicate agent creation).If conflicts are expected, add 409 responses
For example, add to POST /Agents if duplicate agents should return 409:
description: Conflict content: application/scim+json: schema: $ref: '#/components/schemas/ErrorConflict'Otherwise, remove the schema:
- ErrorConflict: - type: object - properties: - schemas: - type: array - items: - type: string - example: - - "urn:ietf:params:scim:api:messages:2.0:Error" - detail: - type: string - description: A more specific error message. - example: "The requested operation would create a duplicate resource" - status: - type: string - description: The HTTP status code. - example: "409"
586-612: Consider adding required fields toAgentUpdateObject.For a PUT operation (which performs full replacement per SCIM semantics), the
AgentUpdateObjectschema has no required fields. Consider makingidanduserNamerequired to enforce proper PUT semantics and prevent incomplete updates.🔎 Proposed fix
AgentUpdateObject: type: object description: SCIM agent resource for update. properties: id: type: string description: A unique identifier for the SCIM resource. example: "ced368ab-29f5-46c1-a192-ffb678b8f747" userName: type: string description: Unique identifier for the agent. example: "AGENT/ced368ab-29f5-46c1-a192-ffb678b8f747" "urn:scim:wso2:agent:schema": type: object properties: Description: type: string description: A description for the agent. example: "Updated Description" DisplayName: type: string description: A human-readable name for the agent. example: "Vetassist AI Lite2" Owner: type: string description: The ID of the owner of this agent. example: "7a6f7b26-f9ea-48ea-9012-87d6b54f4055@carbon.super" + required: + - id + - userName
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-01T15:31:14.922Z
Learnt from: Thisara-Welmilla
Repo: wso2/docs-is PR: 5732
File: en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-update-profile-action-v1.x.md:273-273
Timestamp: 2025-12-01T15:31:14.922Z
Learning: In the wso2/docs-is repository documentation files, prefer unhyphenated compound adjectives (e.g., "SCIM API compliant", "Admin initiated profile update") over hyphenated versions for better readability and natural flow.
Applied to files:
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
🪛 Checkov (3.2.334)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
[medium] 62-66: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🔇 Additional comments (1)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml (1)
183-188: Verify if 404 response is needed for create operation.The POST /Agents endpoint includes a 404 (Not Found) response. This is unusual for a create operation, as 404 typically indicates a resource doesn't exist. If this is intended for cases where the referenced owner doesn't exist, consider using 400 (Bad Request) instead, as the error is with the input data rather than the endpoint itself.
If 404 is indeed required for this API's semantics (e.g., owner validation), please ensure the API documentation clearly explains when this status code is returned.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @en/asgardeo/docs/apis/restapis/scim2-agents.yaml:
- Around line 8-14: Replace the local dev server host with Asgardeo's cloud API
host by updating the OpenAPI servers variable: change the
variables.serverUrl.default from "localhost:9443" to Asgardeo's cloud endpoint
(e.g., "api.asgardeo.io") while keeping the servers.url template
"https://{serverUrl}/t/{tenantDomain}/scim2" and the tenantDomain variable
(variables.tenantDomain.default) as needed.
In @en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml:
- Around line 24-44: The getAgents operationId's description mentions filter and
sorting but only pagination parameters (startIndex, count) are defined; either
update the description to remove references to filter/sort or add the missing
SCIM parameters (add query parameters named filter (string, SCIM filter syntax),
sortBy (string, attribute name), and sortOrder (string, enum:
ascending|descending)) to the parameters list for getAgents so the doc and
behavior are consistent with SCIM 2.0 and the Asgardeo spec; ensure each
parameter has a clear description, appropriate schema (type/format/enums), and
defaults where applicable.
🧹 Nitpick comments (3)
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml (1)
845-861:ErrorConflictschema is defined but never used.The
ErrorConflictschema for 409 responses is defined but not referenced in any endpoint. Consider either:
- Adding a 409 response to the POST
/Agentsendpoint for duplicate agent creation scenarios, or- Removing the unused schema to keep the spec clean.
en/asgardeo/docs/apis/restapis/scim2-agents.yaml (2)
858-874:ErrorConflictschema is defined but never used.Same as the Identity Server spec - consider adding 409 responses where applicable or removing the unused schema.
103-109: Curl examples use localhost instead of Asgardeo endpoint.The code samples reference
localhost:9443which should be updated to match Asgardeo's cloud endpoint for consistency with the server URL correction.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
en/asgardeo/docs/apis/restapis/scim2-agents.yamlen/asgardeo/docs/apis/scim2-agents-rest-apis.mden/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yamlen/identity-server/7.2.0/docs/apis/scim2-agents-rest-apis.md
🚧 Files skipped from review as they are similar to previous changes (1)
- en/identity-server/7.2.0/docs/apis/scim2-agents-rest-apis.md
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: Thisara-Welmilla
Repo: wso2/docs-is PR: 5732
File: en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-update-profile-action-v1.x.md:273-273
Timestamp: 2025-12-01T15:31:14.922Z
Learning: In the wso2/docs-is repository documentation files, prefer unhyphenated compound adjectives (e.g., "SCIM API compliant", "Admin initiated profile update") over hyphenated versions for better readability and natural flow.
📚 Learning: 2025-12-01T15:31:14.922Z
Learnt from: Thisara-Welmilla
Repo: wso2/docs-is PR: 5732
File: en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-update-profile-action-v1.x.md:273-273
Timestamp: 2025-12-01T15:31:14.922Z
Learning: In the wso2/docs-is repository documentation files, prefer unhyphenated compound adjectives (e.g., "SCIM API compliant", "Admin initiated profile update") over hyphenated versions for better readability and natural flow.
Applied to files:
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
🪛 Checkov (3.2.334)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
[medium] 62-66: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml
[medium] 49-53: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🔇 Additional comments (3)
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml (1)
1-894: Overall spec structure looks good.The OpenAPI 3.1.0 specification is well-structured with comprehensive endpoint definitions, error schemas, security schemes, and code samples. The SCIM 2.0 compliance with proper schema URIs and PATCH operations is correctly implemented.
en/asgardeo/docs/apis/scim2-agents-rest-apis.md (1)
1-5: LGTM!The Redoc integration follows the standard documentation pattern with proper front matter template and dynamic base path for the spec URL.
en/asgardeo/docs/apis/restapis/scim2-agents.yaml (1)
560-907: Schema definitions and security schemes are well-structured.The component schemas follow SCIM 2.0 conventions correctly with proper use of WSO2 extension URIs, error schemas, and OAuth2/BasicAuth security schemes with appropriate scopes.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @en/asgardeo/docs/apis/restapis/scim2-agents.yaml:
- Around line 874-886: The OAuth2 security scheme is pointing at localhost:9443;
update the authorizationUrl and tokenUrl under securitySchemes -> OAuth2 ->
flows -> authorizationCode to use Asgardeo's OAuth endpoints (replace the
localhost URLs with the correct Asgardeo endpoints), e.g. use the Asgardeo
authorization and token endpoints for your tenant/organization (authorization:
https://api.asgardeo.io/t/{TENANT}/oauth2/authorize and token:
https://api.asgardeo.io/t/{TENANT}/oauth2/token or your org-specific
equivalents), keeping scopes and flow unchanged.
- Around line 85-91: Replace all curl examples that use
'https://localhost:9443/...' with the Asgardeo API host pattern
'https://api.asgardeo.io/t/{tenant}/...' so the GET /Agents sample becomes
'https://api.asgardeo.io/t/{tenant}/scim2/Agents' and similarly update the other
samples (the other curl blocks for list/create/get/update/delete Agents) to use
'https://api.asgardeo.io/t/{tenant}/scim2/...' replacing localhost:9443 while
preserving query paths, headers, and placeholder {access_token}.
- Around line 119-146: The response examples embed hardcoded localhost:9443 URLs
(e.g., meta.location and roles.$ref) which must be replaced with
Asgardeo-appropriate URLs or a placeholder pattern; update the values for
meta.location and any $ref entries inside the roles array (seen in the example
block containing id "ced368ab-29f5-46c1-a192-ffb678b8f747" and userName
"AGENT/ced368ab-29f5-46c1-a192-ffb678b8f747") to use the Asgardeo base URL or a
configurable placeholder (for example {ASGARDEO_BASE_URL}/scim2/...) and apply
the same change for other occurrences of localhost:9443 in this file so all
meta.location and $ref fields reference the Asgardeo pattern instead of
localhost.
🧹 Nitpick comments (6)
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml (5)
45-58: Consider addingmaxItemsconstraint to array parameters.The
attributesandexcludedAttributesarray parameters don't specify a maximum number of items. While this is a minor concern for query parameters used for attribute filtering, addingmaxItemscan prevent potential abuse.Optional: Add maxItems constraint
- name: attributes in: query description: A multi-valued list of strings indicating the names of resource attributes to include in the response. schema: type: array items: type: string + maxItems: 50 - name: excludedAttributes in: query description: A multi-valued list of strings indicating the names of resource attributes to exclude in the response. schema: type: array items: type: string + maxItems: 50
112-116: InconsistentDisplayNamebetween request example and code sample.The inline request body example uses
"DisplayName": "Vetassist AI"(line 115), but the curl code sample uses"DisplayName": "Vetassist AI Lite2"(line 193). Consider aligning these for consistency.Align examples
example: urn:scim:wso2:agent:schema: Description: "Intelligent Vet Assistant" - DisplayName: "Vetassist AI" + DisplayName: "Vetassist AI Lite2" Owner: "7a6f7b26-f9ea-48ea-9012-87d6b54f4055@carbon.super"Also applies to: 182-196
327-333: Consider adding a response example for the 200 status.The PUT endpoint's 200 response references
AgentResponseObjectbut doesn't include an inline example like other endpoints do. Adding one would improve documentation consistency.
440-446: Minor HTML inconsistency in description.The PATCH endpoint description uses
</br></br>(line 445) for line breaks, which differs from the standard approach used elsewhere in this spec. Consider using standard markdown or removing the explicit breaks for consistency.Suggested fix
- Updating agent description - Deactivating an agent - - Updating agent secret/password</br></br> + - Updating agent secret/password + <b>Scope(Permission) required:</b> `internal_agent_mgt_update`
845-861:ErrorConflictschema is defined but not used.The
ErrorConflictschema (409) is defined but not referenced by any endpoint response. Consider either:
- Adding a 409 response to the POST
/Agentsendpoint for duplicate agent scenarios, or- Removing the unused schema to reduce spec size.
en/asgardeo/docs/apis/restapis/scim2-agents.yaml (1)
840-856:ErrorConflictschema defined but unused.Same as in the Identity Server spec - consider adding 409 response to POST endpoint or removing the unused schema.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
en/asgardeo/docs/apis/restapis/scim2-agents.yamlen/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-01T15:31:14.922Z
Learnt from: Thisara-Welmilla
Repo: wso2/docs-is PR: 5732
File: en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-update-profile-action-v1.x.md:273-273
Timestamp: 2025-12-01T15:31:14.922Z
Learning: In the wso2/docs-is repository documentation files, prefer unhyphenated compound adjectives (e.g., "SCIM API compliant", "Admin initiated profile update") over hyphenated versions for better readability and natural flow.
Applied to files:
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
🪛 Checkov (3.2.334)
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml
[medium] 49-53: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
[medium] 44-48: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🔇 Additional comments (6)
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml (4)
1-17: LGTM!The OpenAPI metadata, server configuration with variables, and global security definitions are well-structured.
197-297: LGTM!The GET by ID endpoint is well-defined with proper parameters, response schema, and code sample.
381-435: LGTM!The DELETE endpoint correctly returns 204 No Content on success and includes appropriate error responses.
879-894: LGTM!Security schemes are well-defined with appropriate OAuth2 scopes for each operation type and BasicAuth as an alternative.
en/asgardeo/docs/apis/restapis/scim2-agents.yaml (2)
1-12: LGTM!The server URL and API description are correctly configured for Asgardeo.
435-441: LGTM!The PATCH endpoint description formatting is cleaner here compared to the Identity Server version.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @en/asgardeo/docs/apis/restapis/scim2-agents.yaml:
- Around line 363-378: Update the PUT curl example payload so placeholder values
match the URL and avoid hardcoded test data: replace the hardcoded tenant
segment "ranukaorg" in the request URL and in the "Owner" value with
"{organization-name}", and change the hardcoded id value
"14a11c02-d947-482c-9084-734fa1c22c2c" in the JSON body to "{agentId}" so it
aligns with the 'Agents/{agentId}' URL placeholder and the "userName" field
remains "AGENT/{agentId}".
- Around line 87-91: The curl example in the multi-line string for the SCIM
Agents endpoint uses the inconsistent placeholder `{organization_name}`; update
that placeholder to `{organization-name}` to match the rest of the file (change
the URL string 'https://api.asgardeo.io/t/{organization_name}/scim2/Agents' to
'https://api.asgardeo.io/t/{organization-name}/scim2/Agents' in the source
block).
- Around line 108-112: The examples under urn:scim:wso2:agent:schema incorrectly
use Identity Server tenant notation "@carbon.super"; update every Owner example
value (the Request example Owner, the Response example Owner, and the schema
example Owner fields) to use Asgardeo organization notation such as
"@{organization-name}" or a generic placeholder like "@myorg" instead of
"@carbon.super" so all Owner examples consistently reflect Asgardeo usage.
🧹 Nitpick comments (5)
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml (4)
112-116: Minor inconsistency in example DisplayName values.The request body example uses
"DisplayName": "Vetassist AI"(line 115) while the curl sample uses"DisplayName": "Vetassist AI Lite2"(line 193). Consider aligning these for consistency.Also applies to: 190-195
327-333: Consider adding a response example for consistency.The PUT operation's 200 response references
AgentResponseObjectbut doesn't include an example, unlike the POST and GET operations. Adding an example would improve documentation consistency.
440-446: Minor HTML inconsistency in description.The
</br>tag on line 445 is inconsistent with other endpoint descriptions. Consider using<br>(self-closing in HTML5) or removing it entirely for consistency.
845-861: Unused schema:ErrorConflictis defined but not referenced.The
ErrorConflict(409) schema is defined but not used in any endpoint's responses. If duplicate agent creation should return 409 Conflict, consider adding it to the POST/Agentsendpoint responses. Otherwise, consider removing this unused schema.en/asgardeo/docs/apis/restapis/scim2-agents.yaml (1)
845-861: Unused schema:ErrorConflictis defined but not referenced.Same as the Identity Server spec - this schema is defined but not used in any endpoint responses. Consider adding it to POST responses or removing it.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
en/asgardeo/docs/apis/restapis/scim2-agents.yamlen/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-01T15:31:14.922Z
Learnt from: Thisara-Welmilla
Repo: wso2/docs-is PR: 5732
File: en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-update-profile-action-v1.x.md:273-273
Timestamp: 2025-12-01T15:31:14.922Z
Learning: In the wso2/docs-is repository documentation files, prefer unhyphenated compound adjectives (e.g., "SCIM API compliant", "Admin initiated profile update") over hyphenated versions for better readability and natural flow.
Applied to files:
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
🪛 Checkov (3.2.334)
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml
[medium] 49-53: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
[medium] 44-48: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🔇 Additional comments (7)
en/identity-server/7.2.0/docs/apis/restapis/scim2-agents.yaml (5)
1-17: LGTM! Well-structured OpenAPI 3.1.0 specification header.The info section, server configuration with tenant domain variable, and dual security scheme setup (OAuth2 + BasicAuth) are properly defined.
28-58: Consider addingfilterandsortByparameters if supported by the API.The PR description mentions "List Agents with filtering/sorting" but the spec only includes pagination (
startIndex,count) and attribute selection parameters. If the SCIM2 endpoint supports filtering (e.g.,filter=displayName eq "test"), consider adding:- name: filter in: query description: A SCIM filter expression to filter the query results. schema: type: string - name: sortBy in: query description: The attribute whose value shall be used to order the returned responses. schema: type: string - name: sortOrder in: query description: The order in which the sortBy parameter is applied (ascending or descending). schema: type: string enum: - ascending - descending
198-297: LGTM!The GET by ID endpoint is properly defined with path parameter, query parameters for attribute filtering, and comprehensive response/error handling.
381-435: LGTM!DELETE endpoint correctly returns 204 No Content on success with appropriate error responses.
879-894: LGTM!Security schemes are well-defined with appropriate OAuth2 scopes matching the required permissions documented in each endpoint.
en/asgardeo/docs/apis/restapis/scim2-agents.yaml (2)
1-12: LGTM!The Asgardeo-specific server URL and security scheme setup are properly configured for the Asgardeo environment.
547-572: LGTM! Schema definitions are well-structured.The component schemas properly define the SCIM agent resource model with appropriate types, descriptions, and examples (aside from the
@carbon.superreferences noted separately).
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @en/asgardeo/docs/apis/restapis/scim2-agents.yaml:
- Around line 362-378: The curl example has inconsistent agent IDs: the URL uses
the {agentId} placeholder while the request body contains a hardcoded id
(14a11c02-...) and other examples use ced368ab-29f5-46c1-a192-ffb678b8f747;
update the request body so the "id" field uses the {agentId} placeholder (and
align any other examples to the same placeholder) and ensure "userName" still
references AGENT/{agentId} so all IDs/placeholders are consistent across the
scim2 Agents examples.
🧹 Nitpick comments (5)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml (5)
8-9: Consider defining{organization-name}as a server variable.The
{organization-name}placeholder in the server URL is not defined as a server variable. While this may work for documentation purposes, explicit server variable definitions improve tooling compatibility and provide default values/descriptions for consumers.✨ Suggested improvement
servers: - url: https://api.asgardeo.io/t/{organization-name}/scim2 + variables: + organization-name: + description: The name of your Asgardeo organization. + default: "{organization-name}"
40-53: Consider addingmaxItemsconstraints to array parameters.The
attributesandexcludedAttributesarray parameters lackmaxItemsconstraints. While not critical for documentation, adding these constraints can improve API validation and protect against excessively large requests.✨ Suggested improvement
- name: attributes in: query description: A multi-valued list of strings indicating the names of resource attributes to include in the response. schema: type: array + maxItems: 50 items: type: string - name: excludedAttributes in: query description: A multi-valued list of strings indicating the names of resource attributes to exclude in the response. schema: type: array + maxItems: 50 items: type: string
573-599: Consider addingrequiredconstraints toAgentUpdateObject.The
AgentUpdateObjectschema lacksrequiredfield constraints. For a PUT (replace) operation, typicallyidanduserNameshould be required to ensure the resource can be properly identified and updated.✨ Suggested improvement
AgentUpdateObject: type: object description: SCIM agent resource for update. + required: + - id + - userName + - "urn:scim:wso2:agent:schema" properties: id: type: string
747-769: Addrequiredconstraint foropfield in patch Operations.Per SCIM 2.0 specification (RFC 7644), the
opfield is required for each patch operation. The schema should reflect this requirement.✨ Suggested improvement
Operations: type: array items: type: object + required: + - op properties: op: type: string description: The type of operation. Valid values are 'add', 'remove', or 'replace'. enum: - add - remove - replace
845-861: RemoveErrorConflictschema or add a comment explaining its purpose.The
ErrorConflictschema (line 845) is defined but never referenced by any endpoint responses. If reserved for future use, add a clarifying comment. Otherwise, remove it to reduce schema clutter.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-12-01T15:31:14.922Z
Learnt from: Thisara-Welmilla
Repo: wso2/docs-is PR: 5732
File: en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-update-profile-action-v1.x.md:273-273
Timestamp: 2025-12-01T15:31:14.922Z
Learning: In the wso2/docs-is repository documentation files, prefer unhyphenated compound adjectives (e.g., "SCIM API compliant", "Admin initiated profile update") over hyphenated versions for better readability and natural flow.
Applied to files:
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
📚 Learning: 2026-01-09T05:24:28.139Z
Learnt from: ShanChathusanda93
Repo: wso2/docs-is PR: 5787
File: en/identity-server/7.1.0/docs/guides/organization-management/organization-applications.md:3-3
Timestamp: 2026-01-09T05:24:28.139Z
Learning: In WSO2 Identity Server documentation, the placeholder `{root-organization-name}` is used in version 7.1.0 and earlier, while `{root-organization-handle}` is used from version 7.2.0 onwards. This is an intentional terminology change, not an inconsistency.
Applied to files:
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
🪛 Checkov (3.2.334)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml
[medium] 44-48: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🔇 Additional comments (5)
en/asgardeo/docs/apis/restapis/scim2-agents.yaml (5)
166-171: Clarify when 404 is returned for agent creation.A
404 Not Foundresponse on aPOST(create) operation is unusual. If this occurs when the specifiedOwnerdoes not exist, consider adding clarification in the response description.✨ Suggested clarification
- description: Not Found + description: Not Found - The specified owner does not exist. content: application/scim+json: schema: $ref: '#/components/schemas/ErrorNotFound'
195-294: LGTM!The GET by ID endpoint is well-structured with appropriate parameters, response codes, and example responses.
380-434: LGTM!The DELETE endpoint follows REST conventions correctly with a 204 No Content success response.
436-546: LGTM!The PATCH endpoint is well-documented with multiple practical examples covering common use cases (updating description, deactivating agent, updating secret).
879-894: LGTM!Security schemes are properly defined with appropriate OAuth2 scopes matching the documented endpoint permissions.
2 participants
Add Missing Documentation for SCIM2 Agent CRUD APIs
Description
This PR adds comprehensive documentation for the SCIM2 Agent CRUD APIs in WSO2 Identity Server 7.2.0.
These APIs were previously available and functional (e.g., /scim2/Agents for POST, PUT, PATCH, and DELETE operations), but there was no official documentation covering:
This PR introduces detailed content for all Agent CRUD operations, improving developer clarity and enabling proper usage and testing of these endpoints.
Changes Included
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.