Document permissions API

Checkout the Document level permissions 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 for Custom Sources 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

POST /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions

Create a set of permissions or overwrite existing permissions.

A POST to create a brand new set of permissions. Overwrites existing.

 ----
 curl -X POST http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions \
 -H "Authorization: Bearer [ACCESS_TOKEN]" \
 -H "Content-Type: application/json" \
 -d '{
   "user": "[USER_NAME]"
   "permissions": ["permission1", "permission2", "permission3"]
 }'
----
 ----
 {
   "user": "[USER_NAME]",
   "permissions": [
     "permission1",
     "permission2",
     "permission3"
   ]
 }
----

Add One Permission

POST /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]

Add one or more permission for a given user.

Permissions are added atop the existing.

curl -X POST http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/add \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission4"]
}'
{
  "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

POST /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/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.

curl -X POST http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "user": [USER_NAME],
  "permissions": []
}'
{
  "user": "[USER_NAME]",
  "permissions": []
}

Remove One Permissions

POST /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/remove

Remove one or more permission for a given user.

curl -X POST http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/remove \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission1"]
}'
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

List Permissions

List permissions for one or all users, paginated.

List All Permissions

GET /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions

List all permissions for all users.

curl -X Get http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "page": {
    "current":1,
    "size":25
  }
}'
{
  "user": "user1",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ],
  "user": "user2",
  "permissions": [
    "permission2",
    "permission4"
  ]
}

Optional pagination.

curl -X POST http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]/remove \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission1"]
}'
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}

List One Permission

GET /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME]

List permissions for a user.

curl -X Get http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/permissions/[USER_NAME] \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json"
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}