List security identities

This is for:

In this article

Sample request

The listSecurityIdentities Security Cache API call lets you list the security identities in your organization.

You can apply a name and/or type filter to get only the desired identities. However, we recommend using this feature through the Security Identities (platform-ca | platform-eu | platform-au) page of the Administration Console for a smoother experience.

Request template

POST https://platform.cloud.coveo.com/rest/organizations/<MyOrganizationId>/securitycache/entities/list HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

In the request path, replace <MyOrganizationId> with the ID of your Coveo organization.

Optionally, you may include any of the following parameters in the query string:

page (unsigned integer): The 0-based index number of the page of identities to retrieve. Default value is 0.
perPage (unsigned integer): The maximum number of identities to retrieve per page. Default value is 100.

Specifying only an organization ID will return a list of all the security identities in this organization. If you want to narrow down the list to the identities matching certain criteria only, include the target optional parameters, as described below.

Payload

{
  "filterTerm": "<IdentityName>", 
  "filteringMode": "PREFIX|SUBSTRING", 
  "identityTypes": [
    "USER|GROUP|VIRTUAL_GROUP" 
  ],
  "providerIds": [
    "<MySecurityProviderId>" 
  ],
  "extractPreciseTotalCount": false 
}

	To list the identities whose name matches a phrase, under `filterTerm`, replace `<IdentityName>` with the desired phrase.
	Under `FilteringMode`, specify `PREFIX` to get only the identities whose name starts with the desired phrase, or `SUBSTRING` to get the identities whose name contains the desired phrase, regardless of its location. The default option is `SUBSTRING`.
	To list the identities of a certain type, in the `identityTypes` array, specify `USER`, `GROUP`, and/or `VIRTUAL_GROUP`.
	To list the identities associated to specific security identity providers, in the `providerIds` array, list the names of the desired providers.
	To get the exact count of identities matching your `"filteringMode": "SUBSTRING"` criterion and the corresponding number of pages in the list, set `extractPreciseTotalCount` to `true`. The default option is `false`, which yields an approximate identities count and number of pages for greater efficiency in organizations with a large number of identities. With the `"filteringMode": "PREFIX"` criterion, the number of identities and pages is always exact.

The body of a successful response (200 OK) contains a paginated list of security identities matching your criteria, along with the number of matches and the number of pages in the list.

Sample request

You want to find the user and group security identities whose name contains wick in the Email Security Provider.

Request template

POST https://platform.cloud.coveo.com/rest/organizations/mycoveoorganizationg8tp8wu3/securitycache/entities/list?page=0&perPage=2 HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "filterTerm": "Wick",
  "filteringMode": "SUBSTRING",
  "identityTypes": [
    "USER", "GROUP"
  ]
}

Successful response - 200 OK:

{
  "items": [
    {
      "infos": [],
      "name": "johnwick@example.com",
      "type": "User",
      "provider": "Email Security Provider",
      "state": "UP_TO_DATE",
      "lastUpdateDate": 1681302804000,
      "lastUpdateResult": "SUCCESS",
      "lastUpdateErrorDetail": ""
    },
    {
      "infos": [],
      "name": "friends-of-wick@example.com",
      "type": "Group",
      "provider": "Email Security Provider",
      "state": "UP_TO_DATE",
      "lastUpdateDate": 1681302804000,
      "lastUpdateResult": "SUCCESS",
      "lastUpdateErrorDetail": ""
    }
  ],
  "totalEntries": 6,
  "totalPages": 3
}

In the sample request, we asked for two entries per page. In the response, there are therefore six entries and three pages. However, since by default an approximate count is returned, there may actually be more than six entries matching the request parameters.