View the Effective Permissions of an Item
View the Effective Permissions of an Item
You can use the Index API to programmatically retrieve the effective permissions of any given item in the index of a Coveo organization. To do so, you need:
-
The unique identifier of the target Coveo organization (see Retrieve the organization ID).
-
The unique identifier of the index which contains the item.
-
The
uniqueId
property value of the item.
-
Use the Search API to execute a query to retrieve the index ID and item ID.
POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer **********-****-****-****-************
Payload
{ ... "maximumAge": 0, ... }
Successful response - 200 OK
{ ... "index": "mycoveocloudv2organizationg8tp8wu3-izwss88l42vevui09ruyzce948-Indexer-1-ru5fb3w85yo3p3gfc2jo5oxigi", ... "results": [ { ... "uniqueId": "42.18734$http://example.com/my-secured-item.html", ... }, ... ], ... }
In this example:
-
The
maximumAge
query parameter is set to0
to ensure that theindex
property of the query response body gets populated with a meaningful value (otherwise, you could getcache
as anindex
value). -
No other query parameters are specified. However, if you want to retrieve the effective permissions of an item in particular, you will likely want to specificy additional query parameters to ensure that the desired item appears in the
results
set of the query response body.
-
-
Use the Get the permission model for a document Index API operation to retrieve the effective permissions of the target item.
GET https://platform.cloud.coveo.com/rest/organizations/<MyOrganizationId>/indexes/<MyIndexId>/documents/<MyDocumentId>/permissions/effective HTTP/1.1 Authorization: Bearer <MyAccessToken>
In the request path, replace:
-
<MyOrganizationId>
with the actual ID of the target Coveo organization (see Retrieve the organization ID). -
<MyIndexId>
with theindex
value retrieved in the previous step. -
<MyDocumentId>
with theuniqueId
value retrieved in the previous step.You must URL-encode the
<MyDocumentId>
value twice. Otherwise you will get a404 Not Found
status with a response body similar to:{ "message": "No resource found at the provided URI.", "errorCode": "INVALID_URI", "requestId": "448e106d-180f-4214-a6d6-2ac75c011599" }
You have the following
uniqueId
:42.31537$file://movies/the-shining.txt
You encode it once:
42.31537%24file%3A%2F%2Fmovies%2Fthe-shining.txt
And then you encode it a second time:
42.31537%2524file%253A%252F%252Fmovies%252Fthe-shining.txt
The
uniqueId
is now ready to be used to substitute<MyDocumentId>
in the request path.
Optionally, you may include any of the following parameters in the query string:
-
from
(string): The earliest update time, in standard W3C date and time format, a permission may have to be retrieved.Sample value:
2018-5-21T19:57:09.714Z
-
to
(string): The latest update time, in standard W3C date and time format, a permission may have to be retrieved.Sample value:
2018-5-22T19:57:09.714Z
-
includeEntities
(string): The type of permissions to be retrieved. Allowed values areALL
,ALLOWED
, andDENIED
. Default value isALL
. -
states
(list of comma-separated strings): The permission states to allow in the response. Only permissions whose state corresponds to the specified values may be retrieved. Allowed values areUNKNOWN
,UP_TO_DATE
,NOT_UPDATED
,OUT_OF_DATE
,IN_ERROR
, andDISABLED
. By default, permissions of any state will be included in the response.Sample value:
UNKNOWN, UP_TO_DATE
-
page
(unsigned integer): The 0-based index number of the page of permissions to retrieve. Default value is0
.Sample value:
5
-
perPage
(unsigned integer): The maximum number of permissions to retrieve per page. Value must be in range[1-1000]
. Default value is100
.Sample value:
50
In the
Authorization
HTTP header, replace:-
<MyAccessToken>
with an access token that grants the Content - Security identities - View privileges in the target Coveo organization (see Create an API key).
GET https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/indexes/mycoveocloudv2organizationg8tp8wu3-ihrwht4l42vevui09ruyzce948-Indexer-1-ru3454sdg4sfd3p3gfc2jo5oxigi/documents/42.31537%2524file%253A%252F%252Fmovies%252Fthe-shining.txt/permissions HTTP/1.1 Authorization: Bearer **********-****-****-****-************
Successful response - 200 OK
{ "items": [ { "allowed": true, "identityType": "USER", "identity": "pjfry@example.com", "securityProvider": "Email Security Provider", "additionalInfo": {}, "lastUpdateDate": 1534874324000, "lastUpdateResult": "SUCCESS", "lastUpdateErrorDetail": "", "state": "UP_TO_DATE" }, { "allowed": true, "identityType": "USER", "identity": "tleela@example.com", "securityProvider": "Email Security Provider", "additionalInfo": {}, "lastUpdateDate": 1534874329000, "lastUpdateResult": "SUCCESS", "lastUpdateErrorDetail": "", "state": "UP_TO_DATE" }, { "allowed": false, "identityType": "USER", "identity": "jzoidberg@example.com", "securityProvider": "Email Security Provider", "additionalInfo": {}, "lastUpdateDate": 1534878913000, "lastUpdateResult": "SUCCESS", "lastUpdateErrorDetail": "", "state": "UP_TO_DATE" }, { "allowed": true, "identityType": "USER", "identity": "pjfry@example.com", "securityProvider": "Movie Security Identity Provider", "additionalInfo": {}, "lastUpdateDate": 1534874256000, "lastUpdateResult": "SUCCESS", "lastUpdateErrorDetail": "", "state": "UP_TO_DATE" }, { "allowed": true, "identityType": "USER", "identity": "tleela@example.com", "securityProvider": "Movie Security Identity Provider", "additionalInfo": {}, "lastUpdateDate": 1534874274000, "lastUpdateResult": "SUCCESS", "lastUpdateErrorDetail": "", "state": "UP_TO_DATE" }, { "allowed": false, "identityType": "USER", "identity": "jzoidberg@example.com", "securityProvider": "Movie Security Identity Provider", "additionalInfo": {}, "lastUpdateDate": 1534878913000, "lastUpdateResult": "SUCCESS", "lastUpdateErrorDetail": "", "state": "UP_TO_DATE" } ], "anonymousAllowed": false, "totalPages": 1, "totalEntries": 6 }
-