Custom Sources Document Permissions API Reference

This is a technical API reference. Refer to the Document permissions for Custom Sources guide for a conceptual walkthrough.

In this API reference

Custom Sources Document Permissions API Overview

POST http://localhost:3002/api/ws/v1/sources/[KEY]/permissions

user

required

The [USER_NAME] is placed into the request URL. Username might reflect an Elasticsearch user: example.mcname, or whatever convention you’ve chosen to use.

key

required

Unique key for a Custom API source, provided upon creation of a Custom API Source.

auth_token

required

Must be included in HTTP authorization headers.

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.

Adding Permissions

Add new permissions to a user.

There are two options:

  1. Add Permissions in Bulk: Create a new set of permissions or over-write all existing permissions.
  2. Add a Single Permission: Add one or more new permissions atop existing permissions.
Adding Permissions in Bulk
POST /api/ws/v1/sources/[KEY]/permissions

Create a set of permissions or overwrite existing permissions.

curl -X POST http://localhost:3002/api/ws/v1/sources/[KEY]/permissions/[USER_NAME] \
-H "Authorization: Bearer [AUTH_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
 "permissions": ["permission1", "permission2", "permission3"]
}'
{
 "user": "[USER_NAME]",
 "permissions": [
   "permission1",
   "permission2",
   "permission3"
 ]
}
Adding a Single Permission
POST /api/ws/v1/sources/[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/[KEY]/permissions/[USER_NAME]/add \
-H "Authorization: Bearer [AUTH_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission4"]
}'
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission1",
    "permission2",
    "permission3",
    "permission4"
  ]
}

Removing 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 a Single Permission: Remove one or more permission from an existing set of permissions.
Removing All Permissions
POST /api/ws/v1/sources/[KEY]/permissions

Batch remove all permissions from a user. Provide an empty array to permissions to clear all values.

curl -X POST http://localhost:3002/api/ws/v1/sources/[KEY]/permissions/[USER_NAME] \
-H "Authorization: Bearer [AUTH_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": []
}'
{
  "user": "[USER_NAME]",
  "permissions": []
}
Removing a Single Permission
POST /api/ws/v1/sources/[KEY]/permissions/[USER_NAME]/remove

Remove one or more permission for a given user.

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

Listing Permissions

List permissions for one or all users, paginated.

Listing All Permissions

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

List all permissions for all users.

curl -X GET http://localhost:3002/api/ws/v1/sources/[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"
  ]
}]

Pagination can be provided:

curl -X POST http://localhost:3002/api/ws/v1/sources/[KEY]/permissions/[USER_NAME]/remove \
-H "Authorization: Bearer [AUTH_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": ["permission1"]
}'
{
  "user": "[USER_NAME]",
  "permissions": [
    "permission2",
    "permission3",
    "permission4"
  ]
}
Listing Permissions for a User
GET /api/ws/v1/sources/[KEY]/permissions/[USER_NAME]

List permissions for a user.

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