SCIM Groups API
List groups
When requesting all groups without paging information, only the first page is returned using the pagesize defined in the Service configuration.
GET /scim/v2/Groups
Response
Status: 200 OK
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 2,
"itemsPerPage": 100,
"startIndex": 1,
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "g169900985708201772",
"externalId": "1749F773-8F2F-441D-BE43-B43F576CD92C",
"displayName": "IT Administrators",
"members": [
{
"$ref": "<service-provider-endpoint>/scim/v2/users/u5248814714833144549",
"type": "User",
"value": "u5248814714833144549"
}
],
"meta": {
"created": "2023-10-03T07:50:28.4517972Z",
"lastModified": "2023-10-03T08:27:54.8152883Z",
"location": "<service-provider-endpoint>/scim/v2/groups/g169900985708201772",
"resourceType": "Group"
}
},
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "g4824062250562640119",
"externalId": "230B5087-51D8-415A-AE4B-2BC38D6AFACC",
"displayName": "Accounting",
"members": [],
"meta": {
"created": "2023-10-03T08:29:02.9839497Z",
"lastModified": "2023-10-03T08:29:02.9840026Z",
"location": "<service-provider-endpoint>/scim/v2/groups/g4824062250562640119",
"resourceType": "Group"
}
}
]
}
Pagination
The SCIM Groups API supports pagination as defined in RFC 7644.
Example:
GET /scim/v2/Groups?startIndex=5&count=20
Filtering
The SCIM Groups API supports filtering as defined in RFC 7644.
Filtering is only supported on displayName
with operator eq
. This is the most important filter for a SCIM client, in order to be able to link groups in the SCIM client with groups in the SCIM Service Provider (The Identity Hub).
Example:
GET /scim/v2/Groups?filter=displayName eq "IT Administrators"
Get a single group
GET /scim/v2/Groups/:id
Response
Status: 200 OK
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "g169900985708201772",
"externalId": "1749F773-8F2F-441D-BE43-B43F576CD92C",
"displayName": "IT Administrators",
"members": [],
"meta": {
"created": "2023-10-03T07:50:28.4517972Z",
"lastModified": "2023-10-03T07:50:28.4594203Z",
"location": "<service-provider-endpoint>/scim/v2/groups/g169900985708201772",
"resourceType": "Group"
}
}
Create an empty group
POST /scim/v2/Groups
Body
{
"externalId":"1749F773-8F2F-441D-BE43-B43F576CD92C",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "IT Administrators",
"members":[]
}
Response
Status: 201 Created
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "g169900985708201772",
"externalId": "1749F773-8F2F-441D-BE43-B43F576CD92C",
"displayName": "IT Administrators",
"members": [],
"meta": {
"created": "2023-10-03T07:50:28.4517972Z",
"lastModified": "2023-10-03T07:50:28.4594203Z",
"location": "<service-provider-endpoint>/scim/v2/groups/g169900985708201772",
"resourceType": "Group"
}
}
Modify a group
The Identity Hub supports both PUT
and PATCH
methods to modify SCIM resources. In both cases, The Identity Hub will only update the fields that are provided. To clear a field the client must provide the field with the appropriate empty value. When using the PUT
method, the members
will be replaced by the members supplied in the update call, if present.
PUT /scim/v2/Groups/:id
When using the PATCH
method, in combination with the add
operation, the members in the update call will be added to the existing list of members. Similarly, the replace
and remove
operation will respectively replace and remove members from the list.
PATCH /scim/v2/Groups/:id
Add a member to a group (PATCH)
PATCH /scim/v2/Groups/:id
Body
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"operations": [
{
"op": "add",
"path": "members",
"value": [
{
"displayName": "Johnn Doe",
"value": "u5248814714833144549"
}
]
}
]
}
Response
Status: 200 OK
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "g169900985708201772",
"externalId": "1749F773-8F2F-441D-BE43-B43F576CD92C",
"displayName": "IT Administrators",
"members": [
{
"<existing-members>": "..."
},
{
"$ref": "<service-provider-endpoint>/scim/v2/users/u5248814714833144549",
"type": "User",
"value": "u5248814714833144549"
}
],
"meta": {
"created": "2023-10-03T07:50:28.4517972Z",
"lastModified": "2023-10-03T08:00:37.289026Z",
"location": "<service-provider-endpoint>/scim/v2/groups/g169900985708201772",
"resourceType": "Group"
}
}
Remove a member from a group (PATCH)
PATCH /scim/v2/Groups/:id
Body
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"operations": [
{
"op": "remove",
"path": "members[value eq 'u5248814714833144549']",
}
]
}
Response
Status: 200 OK
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "g169900985708201772",
"externalId": "1749F773-8F2F-441D-BE43-B43F576CD92C",
"displayName": "IT Administrators",
"members": [
{
"<remaining-members>": "..."
},
],
"meta": {
"created": "2023-10-03T07:50:28.4517972Z",
"lastModified": "2023-10-03T08:22:50.4657407Z",
"location": "<service-provider-endpoint>/scim/v2/groups/g169900985708201772",
"resourceType": "Group"
}
}
Delete a group
When deleting a group, membership will be removed from all the users that were previously a member of this group before finally deleting the group.
DELETE /scim/v2/Groups/:id
Response
Status: 204 No Content