search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Document Permissions, API Reference

Checkout the Document Permissions Guide for a conceptual walkthrough.


Add, remove, and list Custom API Source document level permissions for a user.

Permissions must match those given to the _allow_permissions or _deny_permissions fields within a document.

Deny permissions take precedence.

content_source_key
required
Unique key for a Custom API source, provided upon creation of a Custom API Source.
access_token
required
Must be included in HTTP authorization headers.
user
required
The [USER_NAME] can be placed into the request URL or in the request user field in the request body. You need to include a username, but where you put it is up to you. Username might reflect an Elasticsearch user: example.mcname, or whatever convention you've chosen to use.
permissions
required
The permissions array can accept any grouping of string values. The values must match those in the _allow_permissions and/or _deny_permissions field of a document. For example, if permission1 is given to _deny_permissions, then any user with permission1 assigned will be unable to access the document. Read the Document Permissions Guide to learn more.

Add Permissions

Add new permissions to a user.

There are two options:

  1. Add All Permissions: Create a new set of permissions or over-write all existing permissions.
  2. Add One Permissions: Add one or more new permissions atop existing permissions.

Add All Permissions

Create a set of permissions or overwrite existing permissions.

POST /api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions
Example - A POST to create a brand new set of permissions. Overwrites existing.
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": "[USER_NAME]"
  "permissions": ["permission1", "permission2", "permission3"]
}'
Example Response
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3"
  ]
}

Example - A POST to create a brand new set of permissions. Overwrites existing.
No Java example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": "[USER_NAME]"
  "permissions": ["permission1", "permission2", "permission3"]
}'
Example Response
No Java example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3"
  ]
}

Example - A POST to create a brand new set of permissions. Overwrites existing.
No Node example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": "[USER_NAME]"
  "permissions": ["permission1", "permission2", "permission3"]
}'
Example Response
No Node example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3"
  ]
}

Example - A POST to create a brand new set of permissions. Overwrites existing.
No Ruby example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": "[USER_NAME]"
  "permissions": ["permission1", "permission2", "permission3"]
}'
Example Response
No Ruby example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3"
  ]
}

Example - A POST to create a brand new set of permissions. Overwrites existing.
No Python example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": "[USER_NAME]"
  "permissions": ["permission1", "permission2", "permission3"]
}'
Example Response
No Python example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3"
  ]
}

Example - A POST to create a brand new set of permissions. Overwrites existing.
No Javascript example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": "[USER_NAME]"
  "permissions": ["permission1", "permission2", "permission3"]
}'
Example Response
No Javascript example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3"
  ]
}

Add One Permission

Add one or more permission for a given user.

Permissions are added atop the existing.

POST /api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]
Example - A POST request to add a new permission to the existing set of permissions.
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/add \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission4"]
}'
Example Response
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A POST request to add a new permission to the existing set of permissions.
No Java example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/add \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission4"]
}'
Example Response
No Java example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A POST request to add a new permission to the existing set of permissions.
No Node example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/add \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission4"]
}'
Example Response
No Node example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A POST request to add a new permission to the existing set of permissions.
No Ruby example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/add \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission4"]
}'
Example Response
No Ruby example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A POST request to add a new permission to the existing set of permissions.
No Python example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/add \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission4"]
}'
Example Response
No Python example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A POST request to add a new permission to the existing set of permissions.
No Javascript example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/add \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission4"]
}'
Example Response
No Javascript example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3",
    "permission4"
  ]
}

Remove Permissions

Remove permissions from a user.

There are two options:

  1. Remove All Permissions: Clear all permissions for a given user. Restores an empty array.
  2. Remove One Permission: Remove one or more permission from an existing set of permissions.

Remove All Permissions

Batch remove all permissions from a user.

Pass [USER_NAME] to the user field in the request body and an empty array to permissions to clear all values.

POST /api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions
Example - A POST request to remove all existing permissions.
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": [USER_NAME],
  "permissions": []
}'
Example Response
{
  "user": "[USER_NAME]",
  "permissions": []
}

Example - A POST request to remove all existing permissions.
No Java example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": [USER_NAME],
  "permissions": []
}'
Example Response
No Java example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": []
}

Example - A POST request to remove all existing permissions.
No Node example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": [USER_NAME],
  "permissions": []
}'
Example Response
No Node example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": []
}

Example - A POST request to remove all existing permissions.
No Ruby example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": [USER_NAME],
  "permissions": []
}'
Example Response
No Ruby example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": []
}

Example - A POST request to remove all existing permissions.
No Python example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": [USER_NAME],
  "permissions": []
}'
Example Response
No Python example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": []
}

Example - A POST request to remove all existing permissions.
No Javascript example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": [USER_NAME],
  "permissions": []
}'
Example Response
No Javascript example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": []
}

Remove One Permissions

Remove one or more permission for a given user.

POST /api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/remove
Example - A POST request to remove one permission from an existing set of permissions.
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/remove \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission1"]
}'
Example Response
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A POST request to remove one permission from an existing set of permissions.
No Java example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/remove \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission1"]
}'
Example Response
No Java example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A POST request to remove one permission from an existing set of permissions.
No Node example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/remove \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission1"]
}'
Example Response
No Node example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A POST request to remove one permission from an existing set of permissions.
No Ruby example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/remove \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission1"]
}'
Example Response
No Ruby example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A POST request to remove one permission from an existing set of permissions.
No Python example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/remove \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission1"]
}'
Example Response
No Python example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A POST request to remove one permission from an existing set of permissions.
No Javascript example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/remove \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission1"]
}'
Example Response
No Javascript example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

List Permissions

List permissions for one or all users, paginated.

List All Permissions

GET /api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions
page
optional
Provide the current page and define the size of each page.
Example - A paginated GET request to list all permissions for all users.
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "page": {
    "current":1,
    "size":25
  }
}'
Example Response
{
  "user": "user1",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ],
  "user": "user2",
  "permissions": [
    "permission2",
    "permission4"
  ]
}

Example - A paginated GET request to list all permissions for all users.
No Java example available, showing cURL
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "page": {
    "current":1,
    "size":25
  }
}'
Example Response
No Java example available, showing cURL
{
  "user": "user1",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ],
  "user": "user2",
  "permissions": [
    "permission2",
    "permission4"
  ]
}

Example - A paginated GET request to list all permissions for all users.
No Node example available, showing cURL
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "page": {
    "current":1,
    "size":25
  }
}'
Example Response
No Node example available, showing cURL
{
  "user": "user1",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ],
  "user": "user2",
  "permissions": [
    "permission2",
    "permission4"
  ]
}

Example - A paginated GET request to list all permissions for all users.
No Ruby example available, showing cURL
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "page": {
    "current":1,
    "size":25
  }
}'
Example Response
No Ruby example available, showing cURL
{
  "user": "user1",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ],
  "user": "user2",
  "permissions": [
    "permission2",
    "permission4"
  ]
}

Example - A paginated GET request to list all permissions for all users.
No Python example available, showing cURL
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "page": {
    "current":1,
    "size":25
  }
}'
Example Response
No Python example available, showing cURL
{
  "user": "user1",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ],
  "user": "user2",
  "permissions": [
    "permission2",
    "permission4"
  ]
}

Example - A paginated GET request to list all permissions for all users.
No Javascript example available, showing cURL
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "page": {
    "current":1,
    "size":25
  }
}'
Example Response
No Javascript example available, showing cURL
{
  "user": "user1",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ],
  "user": "user2",
  "permissions": [
    "permission2",
    "permission4"
  ]
}

List One Permission

GET /api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]
Example - A GET request to list the permissions for one user.
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME] \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json"
Example Response
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A GET request to list the permissions for one user.
No Java example available, showing cURL
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME] \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json"
Example Response
No Java example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A GET request to list the permissions for one user.
No Node example available, showing cURL
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME] \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json"
Example Response
No Node example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A GET request to list the permissions for one user.
No Ruby example available, showing cURL
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME] \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json"
Example Response
No Ruby example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A GET request to list the permissions for one user.
No Python example available, showing cURL
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME] \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json"
Example Response
No Python example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

Example - A GET request to list the permissions for one user.
No Javascript example available, showing cURL
curl -X Get http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME] \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json"
Example Response
No Javascript example available, showing cURL
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}


Enjoying the beta? Something broken? Lost? Please send us your feedback or visit the Enterprise Search community.