Custom sources document permissions API reference

edit

Custom sources document permissions API reference

edit

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

In this API reference

edit

Custom sources document permissions API overview

edit
POST http://localhost:3002/api/ws/v1/sources/[ID]/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.

id

required

Unique ID 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

edit

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
edit
POST /api/ws/v1/sources/[ID]/permissions

Create a set of permissions or overwrite existing permissions.

curl -X POST http://localhost:3002/api/ws/v1/sources/[ID]/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
edit
POST /api/ws/v1/sources/[ID]/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/[ID]/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

edit

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
edit
POST /api/ws/v1/sources/[ID]/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/[ID]/permissions/[USER_NAME] \
-H "Authorization: Bearer [AUTH_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "permissions": []
}'
{
  "user": "[USER_NAME]",
  "permissions": []
}
Removing a single permission
edit
POST /api/ws/v1/sources/[ID]/permissions/[USER_NAME]/remove

Remove one or more permission for a given user.

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

edit

List permissions for one or all users, paginated.

Listing all permissions

edit
GET /api/ws/v1/sources/[ID]/permissions

List all permissions for all users.

curl -X GET http://localhost:3002/api/ws/v1/sources/[ID]/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/[ID]/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
edit
GET /api/ws/v1/sources/[ID]/permissions/[USER_NAME]

List permissions for a user.

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