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