Searching with the SCIM API
The ActivID AS 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:
Where ENTITY_TYPE can be:
-
Device provision (to set up HID Approve for push-based authentication)
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 ActivID AS 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 Events
| SCIM Attribute | Operators supported | Description |
|---|---|---|
|
type |
eq, co, ew, sw |
Action name (for example, primaryAuthenticateDevice) |
|
meta.created |
lt,gt |
meta data |
|
directUserExtId |
eq |
Direct user's external Id used for this event (for example, spl-contractor) |
|
indirectUserExtId |
eq |
Indirect user's external Id used for this event (for example, spl-contractor) |
|
authenticationType |
eq |
Authentication policy (for example, AT_EMPPWD) |
|
resourceUris |
eq |
Only works for users |
|
eventId |
eq |
Action name (for example, indirectPrimaryAuthenticateUP) |
|
correlationId |
eq |
Correlation ID for the event |
|
status |
eq |
Can be RESPONSE_SUCCESS or RESPONSE_FAILURE |
|
verify |
eq true |
Used to verify the audit. |
Users
| SCIM Attribute | Operators supported |
|---|---|
|
username |
eq, co, ew, sw, pr |
|
externalid |
eq, co, ew, sw, pr |
|
displayname |
eq, co, ew, sw, pr |
|
groups.value |
eq |
|
role |
eq, co, ew, sw, pr |
|
userType |
eq |
|
userRepositoryId |
eq |
|
Other supported attributes |
eq |
Authenticator
| SCIM Attribute | Operators supported |
|---|---|
|
owner.value |
eq |
|
id |
eq |
Credential
| SCIM Attribute | Operators supported |
|---|---|
|
type |
eq |
|
externalid |
eq |
|
id |
eq |
|
status.expiryDate |
eq, gt, lt |
|
status.status |
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 |
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 |
Excluding Attributes
For the Users, Groups and Event endpoints, it is possible to limit the number of attributes retrieved per row. Simply list the excluded attributes in the excludedAttributes parameter.
Sample User search request excluding authenticators, devices, attributes, roles and name from each User detail row
{
"filter" : "groups.value eq UG_ROOT",
"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"
]
}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.
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.
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"
}
