Scim2 agent rest apis section #5807
Conversation
WalkthroughAdds OpenAPI 3.1 SCIM 2.0 Agents API specifications and Redoc documentation pages for Asgardeo and Identity Server 7.2.0, defining CRUD and PATCH endpoints, request/response schemas, error models, OAuth2/BasicAuth schemes, examples, and mkdocs navigation entries. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Client as Client
participant API as "SCIM Agents API\n(Identity Server)"
participant Auth as "OAuth2 Authorization\nServer"
participant DB as "Data Store"
Note over Client,API: Create Agent flow (POST /Agents)
Client->>Auth: Obtain access token (authorizationCode flow)
Auth-->>Client: Access token
Client->>API: POST /Agents (Authorization: Bearer token)
API->>Auth: Validate token / scope
Auth-->>API: Token valid
API->>DB: Persist agent (create)
DB-->>API: Created (id, meta)
API-->>Client: 201 Created (AgentResponseObject)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Poem
Pre-merge checks❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
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: "[email protected]" + 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.
| - name: sortOrder | ||
| in: query | ||
| description: A string indicating the order in which the 'sortBy' parameter is applied. | ||
| schema: | ||
| type: string | ||
| enum: | ||
| - ascending | ||
| - descending |
There was a problem hiding this comment.
Add missing sortBy parameter for sorting functionality.
The sortOrder parameter specifies whether to sort ascending or descending, but there's no sortBy parameter to indicate which field should be sorted. Without sortBy, the sortOrder parameter is meaningless.
🔎 Proposed fix
Add the sortBy parameter before sortOrder:
- name: count
in: query
description: Specifies the desired maximum number of query results per page.
schema:
type: integer
format: int32
minimum: 0
default: 100
+ - 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: A string indicating the order in which the 'sortBy' parameter is applied.🤖 Prompt for AI Agents
In en/asgardeo/docs/apis/restapis/scim2-agents.yaml around lines 50-57, add a
new query parameter named "sortBy" immediately before the existing "sortOrder"
entry; define it with "in: query", a brief description like "The field to sort
results by", and a "schema" of type "string" (optionally include an enum of
allowed sortable fields if known), ensuring the YAML structure matches the
existing parameter style so the sortOrder parameter becomes meaningful.
1 participant
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.