Searching with the SCIM API

The HID Authentication Service SCIM API allows you to search for different entities within your tenant, such as Users, Audit Records, and Devices.

All the search endpoints follow the same standard pattern and can be used in the same way.

They can be reached through the following URL pattern:

Copy

Search entity

POST https://[base-server-url]/scim/{tenant}/v2/ENTITY_TYPE/.search

Where ENTITY_TYPE can be:

Audit Records
Users
Authenticator
Credential
Device
Device provision (to set up HID Approve for push-based authentication)
Groups
Organization
Tokens Vault

Best Practices for Searching

The recommended best practice is to optimize the API calls and facilitate data analysis by returning only the data you need (and exclude the data you don't).

First retrieve the target data from the server, filtered and organized according to your requirements, and then analyze the results on the client side.

The same guidelines can be applied when using the GET method by including/excluding attributes (see Optimizing the API Calls).

Using Search Filters

All HID Authentication Service Search endpoints allow you to filter the rows in the result.

All the available filters are described below per endpoint.

You can use the and operator between filters and use parentheses between conditions.

Character chains can be surrounded by escaped double quotes:

"filter" : "groups.value eq \"UG_ROOT\""

The operators that can be used with filters are:

Filter	Description
eq	equals
co	contains
ew	ends with
sw	starts with
pr	present (not null, not empty)
gt	greater then
lt	less than

Audit Records

Note: The filter attribute must be used to reduce the number of records returned.

SCIM Attribute	Operators supported	Case-sensitive	Tokenized	Wildcard
actingUserId.id	eq	Yes	Yes	No
actingUserId.immutableId	eq	Yes	Yes	No
actingUserId.session.authenticationMethod	eq, co, sw, ew	Yes	No	Yes
action.actionName	eq, co, sw, ew	Yes	No	Yes
action.actionParameters.CHC	eq, co, sw, ew Filters for the channel in the action parameters of the audit record	Yes	No	Yes
action.actionParameters.COI	eq, co, sw, ew Mapped to AuditRecordSearchCriteria.batchCorrelationId and filters for the correlation ID returned in the response (for example, the correlation ID returned for bulk user import)	Yes	No	Yes
action.actionParameters.DSN	eq Filters for the device serial number in the action parameters of the audit record The exact value should be used	Yes	Yes	No
action.actionParameters.text1...text10	eq, co, sw, ew Filters for custom action parameters	No	No	Yes
correlationId	eq, co, sw, ew Mapped to AuditRecordSearchCriteria.correlationId and filters for the X-Correlation_id header value.	Yes	No	Yes
created	gt/lt (date of creation, timestamp)	No	No	No
id	eq, co, sw, ew	Yes	No	Yes
result	eq RESPONSE_SUCCESS or RESPONSE_FAILURE Filters for successful or failed authentications	Yes	No	Only * is supported
return_value.response	eq SUCCESS or FAILURE Filters for the successful or failed response in the returned value	Yes	No	Only * is supported
targetUserId.id	eq	Yes	Yes	No
targetUserId.immutableId	eq	Yes	Yes	No
targetUserId.session.authenticationMethod	eq, co, sw, ew	Yes	No	Yes

Search parameters:

Parameter	Description	Operators supported
tokenized	Defines if the records should be tokenized to protect PII in the audit data	eq true or false
verify	Defines if the integrity check should be performed on the records	eq true or false

Users

SCIM Attribute	Operators supported
id	eq
username	eq, co, ew, sw, pr
externalid	eq, co, ew, sw, pr
displayname	eq, co, ew, sw, pr
emails	eq, co, ew, sw, pr
emails.value	eq, co, ew, sw, pr
name.familyname	eq, co, ew, sw, pr
name.givenname	eq, co, ew, sw, pr
phonenumbers	eq, co, ew, sw, pr
phonenumbers.value	eq, co, ew, sw, pr
title	eq, co, ew, sw, pr
groups.value	eq
role	eq, co, ew, sw, pr
userType	eq
userRepositoryId	eq

Authenticator

SCIM Attribute	Operators supported
owner.value	eq
id	eq

Credential

SCIM Attribute	Operators supported
type	eq
attributes.value	eq, co, sw, ew
externalid	eq
id	eq
status.expiryDate	eq, gt, lt
status.startDate	eq
status.status	eq
owner.value	eq

Device

SCIM Attribute	Operators supported	Comments
id	eq
externalId	eq, co, sw, ew
type	eq
status.status	eq	Requires 'type' to be specified in the filter
status.expiryDate	eq, gt, lt
status.startDate	eq	Requires 'type' to be specified in the filter
owner.value	eq

Device Provision

SCIM Attribute	Operators supported
deviceType (mandatory)	eq
status.status	eq
owner.value	eq

Groups

SCIM Attribute	Operators supported
id	eq
externalid	eq
displayName	eq
groupType	eq

Organization

SCIM Attribute	Operators supported
type	eq
externalid	eq
id	eq

Tokens Vault

SCIM Attribute	Operators supported	Description
ownerId	eq	User ID of the token owner
ownerExtId	eq	User external ID of the token owner
token	eq	Unique token value (same as a GET Token Value in Searching with the SCIM API)
value	eq	Token’s original (clear) value

Using Pagination

The endpoints that allow the pagination of search results are:

The following attributes can be used for a paginated search:

count can be used to limit the size of the search results
startIndex specifies the index of the first result returned (where 0 will returned the same paginated result as 1)

The result will contain a totalResults attribute to allow you to compute the number of pages.

Important:

The maximum number of rows returned per request is 100, even if you specify a higher count value. Therefore, for lists that are longer than 100 elements, it is mandatory for you to paginate the results.

Copy

Sample Audit Records search request with pagination

POST https://[base-server-url]/scim/{tenant}/v2/AuditRecords/.search
{
    "filter": "created gt 2022-11-27T12:00:00Z and verify eq true",
    "count": 10,
    "startIndex": 1,
    "sortBy": "created",
    "sortOrder": "ascending"
}

Sorting the Search Results

The endpoints that allow the sorting of search results are:

The search results can be sorted using:

sortBy - one of the supported filters
sortOrder - either ascending or descending (or asc or desc)

Copy

Sample User search request with sorted results

POST https://[base-server-url]/scim/{tenant}/v2/Users/.search?api-version=7 HTTP/1.1
Authorization: Bearer PIn9gwAAAW+lGUwYedd6o22q9vQ3hvUTiJW0qJtL
Content-Type: "application/scim+json"
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "filter": "externalId eq \"655817402088574941876708488070484658763453311419\"",
    "sortBy": "id",
    "sortOrder": "descending",
    "startIndex": 1,
    "count": 100
}

Note: Sorting the User search results is available with API version 7 and later.