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:

Add All Permissions: Create a new set of permissions or over-write all existing permissions.
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:

Remove All Permissions: Clear all permissions for a given user. Restores an empty array.
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"
  ]
}

« Custom sources API