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.

  1. Perform a Search API POST request to retrieve the index and uniqueId values required in the Index API request. You need your organization ID for this call.

    Sample request

    POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
    
    Content-Type: application/json
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************

    Payload

    {
      ...
      "maximumAge": 0,
      ...
    }
    Notes

    In this example:

    • The maximumAge query parameter is set to 0 to ensure that the index property of the query response body gets populated with a meaningful value (otherwise, you could get cache as an index value).

    • No other query parameters are specified. However, if you want to retrieve the effective permissions of an item in particular, you’ll likely want to specify additional query parameters to ensure that the desired item appears in the results set of the query response body.

    Successful response - 200 OK

    {
      ...
      "index": "mycoveocloudv2organizationg8tp8wu3-izwss88l42vevui09ruyzce948-Indexer-1-ru5fb3w85yo3p3gfc2jo5oxigi",
      ...
      "results": [
        {
          ...
          "uniqueId": "42.18734$http://example.com/my-secured-item.html",
          ...
        },
        ...
      ],
      ...
    }
  2. Use the Get the permission model for a document Index API operation to retrieve the effective permissions of the target item.

    Sample request

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

    In the request path, replace:

    • <MyOrganizationId> with your actual organization ID.

    • <MyIndexId> with the index value retrieved in the previous step.

    • <MyDocumentId> with the uniqueId value retrieved in the previous step.

      Important

      You must URL-encode the <MyDocumentId> value twice. Otherwise you’ll get a 404 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"
      }

      Example

      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 are ALL, ALLOWED, and DENIED.

      Default value is ALL.

    • 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 are UNKNOWN, UP_TO_DATE, NOT_UPDATED, OUT_OF_DATE, IN_ERROR, and DISABLED. 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 is 0.

      Sample value: 5

    • perPage (unsigned integer): The maximum number of permissions to retrieve per page. Value must be in range [1-1000]. Default value is 100.

      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).

    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
    }