diff --git a/en/asgardeo/docs/apis/organization-apis/index.md b/en/asgardeo/docs/apis/organization-apis/index.md index 4d34e81462..72912028fb 100644 --- a/en/asgardeo/docs/apis/organization-apis/index.md +++ b/en/asgardeo/docs/apis/organization-apis/index.md @@ -12,6 +12,8 @@ Some of these APIs are used for organization management purposes, and they have - [Organization group management API (SCIM2)]({{base_path}}/apis/organization-apis/org-group-mgt/) +- [Organization roles management API (SCIM2)]({{base_path}}/apis/organization-apis/org-role-mgt/) + - [Organization application management API]({{base_path}}/apis/organization-apis/org-application-management) - [Organization identity provider management API]({{base_path}}/apis/organization-apis/org-idp/) diff --git a/en/asgardeo/docs/apis/organization-apis/org-role-mgt.md b/en/asgardeo/docs/apis/organization-apis/org-role-mgt.md new file mode 100644 index 0000000000..721b3a7f7c --- /dev/null +++ b/en/asgardeo/docs/apis/organization-apis/org-role-mgt.md @@ -0,0 +1,5 @@ +--- +template: templates/redoc.html +--- + + diff --git a/en/asgardeo/docs/apis/organization-apis/restapis/role-management.yaml b/en/asgardeo/docs/apis/organization-apis/restapis/role-management.yaml new file mode 100644 index 0000000000..50ff91c3cd --- /dev/null +++ b/en/asgardeo/docs/apis/organization-apis/restapis/role-management.yaml @@ -0,0 +1,869 @@ +openapi: 3.0.1 +info: + version: "v2" + title: Asgardeo - SCIM 2.0 Roles API + description: | + "This is the RESTful API for SCIM 2.0 Roles API in Asgardeo organizations. + This API allows listing roles and updating users and groups of the roles." +servers: + - url: https://api.asgardeo.io/t/{root-organization-name}/o/scim2/v2 + variables: + server-url: + default: https://api.asgardeo.io/t/{root-organization-name}/o/ + root-organization-name: + default: "{root-organization-name}" +security: + - OAuth2: [] + +paths: + /v2/Roles: + get: + tags: + - Roles Endpoint + summary: Filter Roles + description: | + This API returns roles according to the specified filter, sort and pagination parameters. + + Scope(Permission) required: `internal_org_role_mgt_view` + operationId: getRoleV2 + parameters: + - name: filter + in: query + description: Filter expression for filtering + schema: + type: string + - name: startIndex + in: query + description: The 1-based index of the first query result + schema: + type: integer + format: int32 + - name: count + in: query + description: Specifies the desired maximum number of query results per page. + schema: + type: integer + format: int32 + - name: sortBy + in: query + description: | + Specifies the attribute whose value + SHALL be used to order the returned responses + schema: + type: string + - name: sortOder + in: query + description: The order in which the "sortBy" parameter is applied. + schema: + type: string + responses: + "200": + description: Valid roles are found + content: + application/scim+json: + schema: + $ref: '#/components/schemas/RolesListResponseObjectV2' + "401": + description: Unauthorized + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorUnauthorized' + "403": + description: Forbidden + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorForbidden' + "404": + description: No Role found + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorNoRoleAvailable' + x-codeSamples: + - lang: Curl + source: | + curl -X 'GET' \ + 'https://api.asgardeo.io/t/{root-organization-name}/o/scim2/v2/Roles' \ + -H 'accept: application/scim+json' \ + -H 'Authorization: Bearer {bearer_token}' + /v2/Roles/.search: + post: + tags: + - Roles Endpoint + summary: Search Roles + description: | + This API returns roles according to the specified filter, sort and pagination parameters. + + Scope(Permission) required: `internal_org_role_mgt_view` + operationId: getRolesByPostV2 + requestBody: + content: + application/scim+json: + schema: + $ref: '#/components/schemas/RoleSearchRequestObjectV2' + required: false + responses: + "200": + description: Valid roles are found + content: + application/scim+json: + schema: + $ref: '#/components/schemas/RoleSearchResponseObjectV2' + "401": + description: Unauthorized + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorUnauthorized' + "403": + description: Forbidden + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorForbidden' + "404": + description: Valid roles are not found + content: + application/scim+json: + schema: + $ref: '#/components/schemas/RoleSearchErrorResponseObject' + x-codeSamples: + - lang: Curl + source: | + curl -X 'POST' \ + 'https://api.asgardeo.io/t/{root-organization-name}/o/scim2/v2/Roles/.search' \ + -H 'accept: application/scim+json' \ + -H 'Content-Type: application/scim+json' \ + -H 'Authorization: Bearer {bearer_token}' \ + -d '{ + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:SearchRequest" + ], + "startIndex": 1, + "filter": "displayName eq loginRole" + }' + x-codegen-request-body-name: body + /v2/Roles/{id}: + get: + tags: + - Roles Endpoint + summary: Get Role by ID + description: | + This API returns the role details of a particular role using its unique ID. + + Scope(Permission) required: `internal_org_role_mgt_view` + operationId: getRolebyIdV2 + parameters: + - name: id + in: path + description: Unique ID of the resource type. + required: true + schema: + type: string + - name: attributes + in: query + description: SCIM defined attributes parameter. + schema: + type: string + - name: excludedAttributes + in: query + description: SCIM defined excludedAttribute parameter. + schema: + type: string + responses: + "200": + description: Valid role is found + content: + application/scim+json: + schema: + $ref: '#/components/schemas/RoleGetResponseObjectV2' + "401": + description: Unauthorized + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorUnauthorized' + "403": + description: Forbidden + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorForbidden' + "404": + description: Valid role is not found + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorNoRoleAvailable' + x-codeSamples: + - lang: Curl + source: | + curl -X 'GET' \ + 'https://api.asgardeo.io/t/{root-organization-name}/o/scim2/v2/Roles/{role-id}' \ + -H 'accept: application/scim+json' \ + -H 'Authorization: Bearer {bearer_token}' + put: + tags: + - Roles Endpoint + summary: Update Role - PUT + description: "This API updates the **assigned users and groups** of the role.\ + \ \n**Role name, role audience, role permissions and associated applications**\ + \ cannot be updated through this API.\n\nScope(Permission) required:\ + \ `internal_org_role_mgt_update`\n" + operationId: updateRoleV2 + parameters: + - name: id + in: path + description: Unique ID of the resource type. + required: true + schema: + type: string + requestBody: + content: + application/scim+json: + schema: + $ref: '#/components/schemas/RolePutRequestObjectV2' + required: false + responses: + "200": + description: Role is updated + content: + application/scim+json: + schema: + $ref: '#/components/schemas/RolePutResponseObjectV2' + "400": + description: Invalid Input + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorInvalidInput' + "401": + description: Unauthorized + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorUnauthorized' + "403": + description: Forbidden + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorForbidden' + "404": + description: Valid role is not found + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorNoRoleAvailable' + "406": + description: Not Acceptable + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorNotAcceptable' + x-codeSamples: + - lang: Curl + source: | + curl -X 'PUT' \ + 'https://api.asgardeo.io/t/{root-organization-name}/o/scim2/v2/Roles/{role-id}' \ + -H 'accept: application/scim+json' \ + -H 'Content-Type: application/scim+json' \ + -H 'Authorization: Bearer {bearer_token}' \ + -d '{ + "displayName": "loginRole", + "audience": { + "value": "3645709f-ea8d-5595-7690-e1fa0efe3df9", + "display": "My Org", + "type": "organization" + }, + "users": [ + { + "value": "409ca90b-2ba6-4474-9a45-2cf7376e6e43" + } + ], + "groups": [ + { + "value": "7bac6a86-1f21-4937-9fb1-5be4a93ef469" + } + ], + "permissions": [ + { + "value": "internal_login", + "display": "Internal Login" + } + ], + "associatedApplications": [ + { + "value": "9bbc6a86-1f21-4937-9fb1-5be4a93ef499", + "display": "XY Web Application" + }, + { + "value": "67bc6a86-1f21-4937-9fb1-5be4a93ef488", + "display": "XY Mobile Application" + } + ] + }' + x-codegen-request-body-name: body + patch: + tags: + - Roles Endpoint + summary: Update Role - PATCH + description: "This API updates the **assigned users and groups** of the role.\ + \ \n**Role name, role audience, role permissions and associated applications**\ + \ cannot be updated through this API.\n\nScope(Permission) required:\ + \ `internal_org_role_mgt_update`\n" + operationId: patchRole + parameters: + - name: id + in: path + description: Unique id of the resource type. + required: true + schema: + type: string + requestBody: + content: + application/scim+json: + schema: + $ref: '#/components/schemas/PatchRoleOperationRequestObjectV2' + required: false + responses: + "200": + description: Role is updated + content: + application/scim+json: + schema: + $ref: '#/components/schemas/PatchRoleOperationResponseObjectV2' + "401": + description: Unauthorized + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorUnauthorized' + "403": + description: Forbidden + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorForbidden' + "404": + description: Valid role is not found + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorNoRoleAvailable' + "406": + description: Not Acceptable + content: + application/scim+json: + schema: + $ref: '#/components/schemas/ErrorNotAcceptable' + x-codeSamples: + - lang: Curl + source: | + curl -X 'PATCH' \ + 'https://api.asgardeo.io/t/{root-organization-name}/o/scim2/v2/Roles/{role-id}' \ + -H 'accept: application/scim+json' \ + -H 'Content-Type: application/scim+json' \ + -H 'Authorization: Bearer {bearer_token}' \ + -d '{ + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:PatchOp" + ], + "Operations": [ + { + "op": "add", + "path": "groups", + "value": [ + { + "value": "7bac6a86-1f21-4937-9fb1-5be4a93ef469" + } + ] + }, + { + "op": "add", + "path": "users", + "value": [ + { + "value": "9cac6a86-1f21-4937-9fb1-5be4a93ef349" + } + ] + }, + { + "op": "remove", + "path": "users[value eq 0565f472-28fe-4d93-83ad-096c66ed4a47]" + }, + { + "op": "remove", + "path": "groups[value eq 9065f445-265e-4rfg3-83ad-666c66ed4a55]" + } + ] + }' + x-codegen-request-body-name: body +components: + schemas: + RolesListResponseObjectV2: + type: object + properties: + totalResults: + type: integer + example: 3 + startIndex: + type: integer + example: 1 + itemsPerPage: + type: integer + example: 3 + schemas: + type: array + items: + type: string + example: urn:ietf:params:scim:api:messages:2.0:ListResponse + Resources: + type: array + items: + $ref: '#/components/schemas/RoleObV2' + RoleSearchRequestObjectV2: + type: object + properties: + schemas: + type: object + properties: {} + example: + - urn:ietf:params:scim:api:messages:2.0:SearchRequest + startIndex: + type: integer + example: 1 + count: + type: integer + example: 10 + filter: + type: string + example: displayName eq loginRole + RoleSearchResponseObjectV2: + type: object + properties: + totalResults: + type: integer + example: 1 + startIndex: + type: integer + example: 1 + itemsPerPage: + type: integer + example: 3 + schemas: + type: array + items: + type: string + example: urn:ietf:params:scim:api:messages:2.0:ListResponse + Resources: + type: array + items: + $ref: '#/components/schemas/RoleObV2' + RoleObV2: + type: object + properties: + displayName: + type: string + example: loginRole + meta: + type: object + properties: + location: + type: string + example: https://api.asgardeo.io/t/{root-organization-name}/o/scim2/Roles/4645709c-ea8c-4495-8590-e1fa0efe3de0 + id: + type: string + example: 4645709c-ea8c-4495-8590-e1fa0efe3de0 + audience: + type: object + properties: + value: + type: string + example: 3645709f-ea8d-5595-7690-e1fa0efe3df9 + display: + type: string + example: My Org + type: + type: string + example: organization + RoleGetResponseObjectV2: + type: object + properties: + displayName: + type: string + example: loginRole + meta: + type: object + properties: + location: + type: string + example: https://api.asgardeo.io/t/{root-organization-name}/o/scim2/Roles/4645709c-ea8c-4495-8590-e1fa0efe3de0 + resourceType: + type: string + example: Role + schemas: + type: array + items: + type: string + example: urn:ietf:params:scim:schemas:extension:2.0:Role + id: + type: string + example: 4645709c-ea8c-4495-8590-e1fa0efe3de0 + audience: + type: object + properties: + value: + type: string + example: 3645709f-ea8d-5595-7690-e1fa0efe3df9 + display: + type: string + example: My Org + type: + type: string + example: organization + enum: + - application + - organization + users: + type: array + items: + type: object + properties: + $ref: + type: string + example: https://api.asgardeo.io/t/{root-organization-name}/o/scim2/Users/3a12bae9-4386-44be-befd-caf349297f45 + display: + type: string + example: kim + value: + type: string + example: 008bba85-451d-414b-87de-c03b5a1f4217 + groups: + type: array + items: + type: object + properties: + $ref: + type: string + example: https://api.asgardeo.io/t/{root-organization-name}/o/scim2/Groups/7bac6a86-1f21-4937-9fb1-5be4a93ef469 + display: + type: string + example: DEFAULT/manager + value: + type: string + example: 7bac6a86-1f21-4937-9fb1-5be4a93ef469 + permissions: + type: array + items: + type: object + properties: + value: + type: string + example: internal_login + display: + type: string + example: Internal Login + associatedApplications: + type: array + example: + - value: 9bbc6a86-1f21-4937-9fb1-5be4a93ef499 + display: XY Web Application + - value: 67bc6a86-1f21-4937-9fb1-5be4a93ef488 + display: XY Mobile Application + items: + type: object + properties: + value: + type: string + display: + type: string + RolePutRequestObjectV2: + type: object + properties: + displayName: + type: string + example: loginRole + audience: + type: object + properties: + value: + type: string + example: 3645709f-ea8d-5595-7690-e1fa0efe3df9 + display: + type: string + example: My Org + type: + type: string + example: organization + users: + type: array + items: + type: object + properties: {} + example: + value: 409ca90b-2ba6-4474-9a45-2cf7376e6e43 + groups: + type: array + items: + type: object + properties: {} + example: + value: 7bac6a86-1f21-4937-9fb1-5be4a93ef469 + permissions: + type: array + items: + type: object + properties: + value: + type: string + example: internal_login + display: + type: string + example: Internal Login + associatedApplications: + type: array + example: + - value: 9bbc6a86-1f21-4937-9fb1-5be4a93ef499 + display: XY Web Application + - value: 67bc6a86-1f21-4937-9fb1-5be4a93ef488 + display: XY Mobile Application + items: + type: object + properties: + value: + type: string + display: + type: string + RolePutResponseObjectV2: + type: object + properties: + displayName: + type: string + example: loginRole + meta: + type: object + properties: + location: + type: string + example: https://api.asgardeo.io/t/{root-organization-name}/o/scim2/Roles/4645709c-ea8c-4495-8590-e1fa0efe3de0 + resourceType: + type: string + example: Role + schemas: + type: array + items: + type: string + example: urn:ietf:params:scim:schemas:extension:2.0:Role + id: + type: string + example: 4645709c-ea8c-4495-8590-e1fa0efe3de0 + audience: + type: object + properties: + value: + type: string + example: 3645709f-ea8d-5595-7690-e1fa0efe3df9 + display: + type: string + example: My Org + type: + type: string + example: organization + enum: + - application + - organization + PatchRoleOperationRequestObjectV2: + type: object + properties: + schemas: + type: array + items: + type: string + example: urn:ietf:params:scim:api:messages:2.0:PatchOp + Operations: + type: array + example: + - op: add + path: groups + value: + - value: 7bac6a86-1f21-4937-9fb1-5be4a93ef469 + - op: add + path: users + value: + - value: 9cac6a86-1f21-4937-9fb1-5be4a93ef349 + - op: remove + path: "users[value eq 0565f472-28fe-4d93-83ad-096c66ed4a47]" + - op: remove + path: "groups[value eq 9065f445-265e-4rfg3-83ad-666c66ed4a55]" + items: + $ref: '#/components/schemas/RolePatchOperationobjV2' + RolePatchOperationobjV2: + type: object + properties: + op: + type: string + enum: + - add + - remove + - replace + path: + type: string + value: + type: array + items: + type: object + properties: + value: + type: string + PatchRoleOperationResponseObjectV2: + type: object + properties: + displayName: + type: string + example: loginRole + meta: + type: object + properties: + location: + type: string + example: https://api.asgardeo.io/t/{root-organization-name}/o/scim2/Roles/4645709c-ea8c-4495-8590-e1fa0efe3de0 + resourceType: + type: string + example: Role + schemas: + type: object + properties: {} + example: + - urn:ietf:params:scim:schemas:extension:2.0:Role + id: + type: string + example: 4645709c-ea8c-4495-8590-e1fa0efe3de0 + audience: + type: object + properties: + value: + type: string + example: 3645709f-ea8d-5595-7690-e1fa0efe3df9 + display: + type: string + example: My Org + type: + type: string + example: organization + enum: + - application + - organization + ErrorInvalidInput: + required: + - detail + - status + type: object + properties: + status: + type: string + example: "400" + schemas: + type: string + example: urn:ietf:params:scim:api:messages:2.0:Error + scimType: + type: string + example: invalidSyntax + detail: + type: string + example: "Request is unparsable, syntactically incorrect, or violates schema." + ErrorUnauthorized: + required: + - status + type: object + properties: + status: + type: string + example: "401" + schemas: + type: string + example: urn:ietf:params:scim:api:messages:2.0:Error + scimType: + type: string + example: Unauthorized + ErrorNotAcceptable: + required: + - status + type: object + properties: + status: + type: string + example: "406" + schemas: + type: string + example: urn:ietf:params:scim:api:messages:2.0:Error + scimType: + type: string + example: Not Acceptable + ErrorForbidden: + required: + - status + type: object + properties: + status: + type: string + example: "403" + schemas: + type: string + example: urn:ietf:params:scim:api:messages:2.0:Error + scimType: + type: string + example: Forbidden + ErrorNoRoleAvailable: + required: + - detail + - status + type: object + properties: + status: + type: string + example: "404" + schemas: + type: array + items: + type: string + example: urn:ietf:params:scim:api:messages:2.0:Error + detail: + type: string + example: Role not found in the system. + RoleSearchErrorResponseObject: + required: + - itemsPerPage + - schemas + - startIndex + - totalResults + type: object + properties: + totalResults: + type: integer + example: 0 + startIndex: + type: integer + example: 1 + itemsPerPage: + type: integer + example: 0 + schemas: + type: array + items: + type: object + example: urn:ietf:params:scim:api:messages:2.0:ListResponse + securitySchemes: + OAuth2: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: https://api.asgardeo.io/t/{root-organization-name}/oauth/authorize + tokenUrl: https://api.asgardeo.io/t/{root-organization-name}/oauth/token + scopes: + read: Grants read access + write: Grants write access + admin: Grants read and write access to administrative information + description: "**Authorization code OAuth flow** + **Organization Switch**" diff --git a/en/asgardeo/docs/apis/restapis/roles.yaml b/en/asgardeo/docs/apis/restapis/roles.yaml index c68760ccc4..9f11b8e9d3 100644 --- a/en/asgardeo/docs/apis/restapis/roles.yaml +++ b/en/asgardeo/docs/apis/restapis/roles.yaml @@ -3,7 +3,7 @@ info: version: "v2" title: Asgardeo - SCIM 2.0 Roles API description: | - "This is the RESTful API for SCIM 2.0 Roles API in WSO2 Asgardeo. + "This is the RESTful API for SCIM 2.0 Roles API in Asgardeo. This API allows creating, deleting, listing, roles and updating role name, permissions, users and groups of the roles. \n To access the SCIM 2.0 Roles APIs in Asgardeo, you need to first [get an access token](https://wso2.com/asgardeo/docs/apis/authentication/#get-an-access-token) from your organization." servers: diff --git a/en/asgardeo/mkdocs.yml b/en/asgardeo/mkdocs.yml index 919ce8b7b3..f573dc461c 100644 --- a/en/asgardeo/mkdocs.yml +++ b/en/asgardeo/mkdocs.yml @@ -335,6 +335,7 @@ nav: - Get access for organization APIs: apis/organization-apis/authentication.md - User management API: apis/organization-apis/org-user-mgt.md - Group management API: apis/organization-apis/org-group-mgt.md + - Role management API: apis/organization-apis/org-role-mgt.md - Application management API: apis/organization-apis/org-application-management.md - Identity provider management API: apis/organization-apis/org-idp.md - Organization management API: apis/organization-apis/org-management.md