Searching with the SCIM API

The Authentication Service SCIM API allows you to search for different entities within your tenant, such as Users, Groups, Roles and more.

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:

https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/ENTITY_TYPE/.search (POST)

Where ENTITY_TYPE can be:

Users
Groups
Device
Credential
Event
Authenticator
Provision (Device provisioning request, invitation to setup HID Approve)

Available Filters

All Authentication Service Search endpoints allow you to filter the rows in the result. To do so, use the filter parameter. All the available filters are described below. 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:

eq	equals
co	contains
ew	ends with
sw	starts with
pr	present (not null, not empty)
gt	Greater then
lt	Lesser than

Users

username	eq, co, ew, sw, pr
externalid	eq, co, ew, sw, pr
groups.value	eq
role	eq, co, ew, sw, pr
userType	eq
Any user attribute	eq

Note:

The user attributes can be searched using the following notation:

filter:"urn:hid:scim:api:idp:2.0:UserAttribute:attributes.name eq FIRSTNAME and urn:hid:scim:api:idp:2.0:UserAttribute:attributes.value eq John"

Groups

id	eq
externalid	eq
displayName	eq

Device

id	eq
externalId	eq, co, sw, ew
type	eq
status.status	eq
status.expiryDate	eq, gt, lt
status.startDate	eq
owner.value	eq

Credential

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

Event

type	eq, co, ew, sw
meta.created	lt,gt
directUserExtId	eq
indirectUserExtId	eq
authenticationType	eq
resourceUris	eq
eventId	eq
correlationId	eq
Status	eq
Verify	eq true

Authenticator

owner.value	eq
id	eq

Provision

deviceType (mandatory)	eq
status.status	eq
owner.value	eq

All Authentication Service Search endpoints allow you to paginate your search. When searching, use the startIndex and count parameters to control the size of the page, the result will contain a totalResults attribute to allow you to compute the number of pages.

A paginated search request:

POST http://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Users/.search HTTP/1.1
Content-Type: application/scim+json

{
   "filter" : "groups.value eq UG_ROOT",
   "startIndex": 0,
   "count": 100
}

The response:

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 16,
   "resources": [ (...) ]
}

Important:

The maximum number of rows returned per request is 100, even if you specify a higher count parameter. This means that for lists that are bigger than 100 elements, it is mandatory for you to paginate.

Sorting

In order to sort, use the sortBy and sortOrder parameters:

POST https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Users/.search 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":0,
   "count":100
}

Reduce the number of Attributes in the result

For the Users, Groups and Event endpoints, it is possible to limit the number of attributes retrieved per row. In order to do this, simply list the excluded attributes in the excludedAttributes parameter. Here we remove the authenticators, the devices, the attributes, roles and name from each User detail row:

{
   "filter" : "groups.value eq UG_ROOT",
   "startIndex": 0,
   "count": 100,
   "excludedAttributes": [
   	"urn:hid:scim:api:idp:2.0:UserAuthenticator", 
   	"urn:hid:scim:api:idp:2.0:UserDevice", 
   	"urn:hid:scim:api:idp:2.0:UserAttribute",
   	"roles",
   	"name"
   ]
}