Users ​

SCIM Users refer to individual entities that have access to a system or application. SCIM provides a standardized way to manage these users across various systems. This includes creating, reading, updating, and deleting user resources through a RESTful API. The user resources are represented as JSON objects, and include information such as the user's name, email address, and other relevant attributes. The SCIM protocol helps to simplify user management and promotes interoperability among different systems.

List Users ​

The SCIM list users endpoint is used to retrieve a list of all users in the system. It is accessed through a RESTful API using the HTTP GET method and the URL /users. The response will be a JSON object containing an array of user resources, each of which includes information such as the user's name, email address, and other attributes. The endpoint may also support pagination and filtering to limit the number of results returned.

Pagination is possible by leveraging query parameters size and startIndex. For example with the following request.

List Users Including Groups ​

SCIM allows for the retrieval of attributes only when they are explicitly requested. You can use the attributes parameter to define which attributes you want to be returned. Generally, the groups attribute is only returned if it is specifically requested.

Find User ​

In SCIM, filters are used to refine the list of resources returned by a SCIM service provider. They can be used in 'List' or 'Search' requests to limit the results based on specific attributes or conditions.

Here are some of the filter options you can use in SCIM:

• Attribute Filter: You can filter resources based on their attributes. For example, userName eq "john" would return only the users whose userName is "john".

• Comparison Operators: SCIM supports several comparison operators such as eq (equals), ne (not equals), co (contains), sw (starts with), ew (ends with), gt (greater than), lt (less than), ge (greater than or equal to), and le (less than or equal to).

• Logical Operators: SCIM also supports logical operators like and and or to combine multiple conditions. For example, userName eq "john" and title co "manager" would return users named "john" who also have "manager" in their title.

• Grouping: You can group conditions using parentheses. For example, (userName eq "john" or userName eq "jane") and title co "manager" would return users named either "john" or "jane" who have "manager" in their title.

• Complex Attributes: SCIM allows filtering on complex attributes as well. For example, emails[type eq "work" and value co "@example.com"] would return users whose work email contains "@example.com".

Remember to properly encode the filter query when using it in a URL.

The following example finds all users who are a member of a certain group.

Get User ​

The SCIM endpoint for retrieving a known user resource is typically accessed through a RESTful API using the HTTP GET method. The URL for this endpoint is usually in the format /users/{id}, where {id} is replaced with the unique identifier of the user resource you wish to retrieve.

For example, if you wanted to retrieve the user resource with an id of 1, you would send a GET request to /users/1.

The response from this endpoint will be a JSON object containing the user resource's information, such as their name, email address, and other attributes.

Create User ​

To create a new user, you would send a POST request to /users with a JSON object in the request body containing the new user's information. This information might include attributes such as the user's name, email address, and other relevant details.

The server will respond with a JSON object representing the newly created user resource, including its unique identifier.

Create User (alternative) ​

Note that the above example doesn't explicitly define what attributes belong to the user schema and what attributes are so called common attributes, such as externalId.
In some cases, especially when using multiple schemas, it is preferable to explicitly specify the schema like in the example below.

Update Attribute ​

To update a specific attribute of a user, you can use the HTTP PATCH method. This allows you to modify only certain attributes of a user resource without needing to send the entire resource in your request.

The URL for this endpoint is in the format /users/{id}, where {id} is replaced with the unique identifier of the user resource you wish to update.

In the request body, you would include a JSON object that specifies the attribute you want to update and its new value.

Replace ​

The SCIM protocol provides a PUT operation to replace an existing user resource. This operation allows you to replace all attributes of a user resource with a new set of attributes.

In the request body, you would include a JSON object that specifies the new attributes for the user. This JSON object should include all attributes of the user resource, even those that are not changing, because the PUT operation replaces the entire user resource.

Delete ​

Delete users by sending an DELETE request to the endpoint /users/{id}.

Note that a succesful deletion request will return no content, and therefore the HTTP status code 204.

Cursor Pagination ​

Some databases do not support index pagination, which leverages startIndex for navigation to the next page. Additionally, for performance reasons, this is not the most optimal way to navigate through a large dataset. To address this, a new specification is being developed: Cursor-based Pagination of SCIM Resources.

SCIM Playground supports cursor navigation.

First, start by issuing a regular request to retrieve resources such as Users or Groups. However, ensure to send an empty cursor query parameter. By sending this parameter, the SCIM server is instructed to use cursor pagination and return nextCursor.

Note that the response now contains nextCursor.

Try to use it in the following request.

Note that this response includes previousCursor. This allows navigating back to the previous page.