Searching with the SCIM API

The ActivID Appliance 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:

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 Appliance 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

Note: The filter attribute must be used to reduce the number of records returned.
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

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

Requires 'type' to be specified in the filter

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

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.

Copy

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.

Note:

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"
}