SCIM Users API

List users

When requesting all users without paging information, only the first page is returned using the pagesize defined in the Service configuration.

GET /scim/v2/Users

Response

Status: 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "itemsPerPage": 100,
    "startIndex": 1,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "u5248814714833144549",
            "externalId": "B933E03F-6637-44A5-A2B1-5D6AE30AB4FE",
            "userName": "john.doe",
            "name": {
                "familyName": "Doe",
                "givenName": "John"
            },
            "displayName": "John Doe",
            "active": true,
            "locale": "en-US",
            "emails": [
                {
                    "value": "john.doe@contoso.com"
                }
            ],
            "groups": [
                {
                    "display": "IT Administrators",
                    "$ref": "<service-provider-endpoint>/scim/v2/groups/g169900985708201772",
                    "type": "direct",
                    "value": "g169900985708201772"
                }
            ],
            "phoneNumbers": [
                {
                    "value": "+32 123 11 22 33",
                    "type": "mobile"
                }
            ],
            "roles": [
                {
                    "value": "workflow_manager"
                },
                {
                    "value": "service_manager"
                }
            ],
            "meta": {
                "created": "2023-10-03T07:32:53.5771416Z",
                "lastModified": "2023-10-03T07:32:53.5952172Z",
                "location": "<service-provider-endpoint>/scim/v2/users/u5248814714833144549",
                "resourceType": "User"
            }
        },
        {
            "...": "..."
        }
    ]
}

Pagination

The SCIM Users API supports pagination as defined in RFC 7644.

Example:

GET /scim/v2/Users?startIndex=5&count=20

Filtering

The SCIM Users API supports filtering as defined in RFC 7644.

Filtering is only supported on userName with operator eq. This is the most important filter for a SCIM client, in order to be able to link users in the SCIM client with users in the SCIM Service Provider (The Identity Hub).

Example:

GET /scim/v2/Users?filter=userName eq "john.doe"

Get a single user

GET /scim/v2/Users/:id

Response

Status: 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "u5248814714833144549",
    "externalId": "B933E03F-6637-44A5-A2B1-5D6AE30AB4FE",
    "userName": "john.doe",
    "name": {
        "familyName": "Doe",
        "givenName": "John"
    },
    "displayName": "John Doe",
    "active": true,
    "locale": "en-US",
    "emails": [
        {
            "value": "john.doe@contoso.com"
        }
    ],
    "groups": [],
    "phoneNumbers": [
        {
            "value": "+32 123 11 22 33",
            "type": "mobile"
        }
    ],
    "roles": [
        {
            "value": "workflow_manager"
        },
        {
            "value": "service_manager"
        }
    ],
    "...": "...",
    "meta": {
        "created": "2023-10-03T07:32:53.5771416Z",
        "lastModified": "2023-10-03T07:32:53.5952172Z",
        "location": "<service-provider-endpoint>/scim/v2/users/u5248814714833144549",
        "resourceType": "User"
    }
}

Create a user

POST /scim/v2/Users

Body

{
    "userName": "john.doe",
    "active": true,
    "displayName": "John Doe",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "locale": "en-US",
    "externalId": "B933E03F-6637-44A5-A2B1-5D6AE30AB4FE",
    "name": {
        "familyName": "Doe",
        "givenName": "John"
    },
    "emails": [
        {
            "value": "john.doe@contoso.com"
        }
    ],
    "phoneNumbers": [
        {
            "value": "+32 123 11 22 33",
            "type": "mobile"
        }
    ],
    "roles": [
        { 
            "value": "workflow_manager"
        },
        { 
            "value": "service_manager"
        }
    ],
    "...": "..."
}

Response

Status: 201 Created

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "u5248814714833144549",
    "externalId": "B933E03F-6637-44A5-A2B1-5D6AE30AB4FE",
    "userName": "john.doe",
    "name": {
        "familyName": "Doe",
        "givenName": "John"
    },
    "displayName": "John Doe",
    "active": true,
    "locale": "en-US",
    "emails": [
        {
            "value": "john.doe@contoso.com"
        }
    ],
    "groups": [],
    "phoneNumbers": [
        {
            "value": "+32 123 11 22 33",
            "type": "mobile"
        }
    ],
    "roles": [
        {
            "value": "workflow_manager"
        },
        {
            "value": "service_manager"
        }
    ],
    "...": "...",
    "meta": {
        "created": "2023-10-03T07:32:53.5771416Z",
        "lastModified": "2023-10-03T07:32:53.5952172Z",
        "location": "<service-provider-endpoint>/scim/v2/users/u5248814714833144549",
        "resourceType": "User"
    }
}

Modify a user

The Identity Hub supports both PUT and PATCH methods to modify SCIM resources. In both cases, the service provider will only update the fields that are provided. To clear a field the client must provide the field with the appropriate empty value.

PUT /scim/v2/Users/:id
PATCH /scim/v2/Users/:id

Response

Status: 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "u5248814714833144549",
    "...": "..."
}

Delete a user

The SCIM Users API currently does not support DELETE.