Filtering users using the REST API

Introduction

This document explains how to filter users using the .filter endpoint: api/rest/v2/users/.filter. The filtering capabilities include:

  • Filtering on user properties: userName, displayName, groups, organization, externalId and active
  • Filter on user claims

For more details on the filter operators, refer to https://tools.ietf.org/html/rfc7644#section-3.4.2.

Filtering users by claims

Syntax:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type <operator> "claim_type" and value <operator> "claim_value")]]

Examples

The following examples explain how to filter users based on their claims through the REST API.

Example 1. Users assigned at least one role

The following query finds all users who have been assigned at least one role in your system. It can be helpful for auditing purposes, such as identifying users with permissions to access the REST API and the Admin interface:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and value pr)]]

To find all users who have not been assigned a role:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and value eq "")]]

Example 2. Users with a specific role

The following query finds all users with a specific role in your system, such as users with the "Administrator" role:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and value co "Administrator")]]

Example 3. Users with roles matching a specific pattern

The following query finds all users with permission to make changes to at least one resource type in Identify:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and value co "Contributor")]]

Example 4. Users with at least one of specific roles

The following query finds all users who have either the "Administrator" or "Observer" role:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and (value eq "Administrator" or value eq "Observer"))]]

Example 5. Chaining filters with other user attributes

You can also apply additional filters on other user attributes. For example, the following query finds all users with the "Observer" role who belong to the "ITDepartment" organization:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "urn:identify:rest-api:role" and value co "Observer")]] and urn:scim:schemas:extension:enterprise:1.0[organization eq "ITDepartment"]

Filtering users by the userName property

Syntax:

userName <operator> "<user_Name>"

Example:

The following query finds all users whose userName ends with "@gmail.com".

userName ew "@gmail.com"

Filtering users by the displayName property

Syntax:

displayName <operator> "<display_Name>"

Example:

The following query finds all users whose displayName contains "John".

displayName co "John"

Filtering users by the active property

Syntax:

active <operator> "<true_or_false>"

Example:

The following query finds all users who is inactive.

active eq "false"

Filtering users by the organization property

Syntax:

urn:scim:schemas:extension:enterprise:1.0[organization <operator> "<organization_name>"]

Example:

The following query finds all users who are part of "Organization 01".

urn:scim:schemas:extension:enterprise:1.0[organization eq "Organization 01"]

Filtering users by the group property

Filtering users by group is used to retrieve users associated with a specific group, identified by its display name and Id. This filter can be applied using just the display name, just the group Id, or by combining both.

Syntax (by display name):

groups[(display <operator> "<group_display_name>")]

Syntax (by group Id):

groups[(value <operator> "<group_id>")]

Syntax (by combining both):

groups[(display <operator> "<group_display_name>" and value <operator> "<group_id>")]

Examples:

  • Filter by display name:

    groups[(display eq "Group1")]

    This example retrieves users in the group named "Group1" using only the display name.

  • Filter by group Id:

    groups[(value eq "36d21035-9092-46ee-a962-fa3c7c5dad45")]

    This example retrieves the users in the group with ID "36d21035-9092-46ee-a962-fa3c7c5dad45".

  • Filter by combining both display name and group Id:

    groups[(display eq "Group1" and value eq "36d21035-9092-46ee-a962-fa3c7c5dad45")]

    This example retrieves users that match both the display name "Group1" and the group Id "36d21035-9092-46ee-a962-fa3c7c5dad45".

Filtering users by the ExternalId property

Syntax:

externalId <operator> "<external_id>"

Example:

externalId sw "4f0bb799-eb33-4c23-80c9-b06e3da388a5"

This example returns users whose externalId starts with 4f0bb799-eb33-4c23-80c9-b06e3da388a5.