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 authentication

edit

Workplace Search APIs support multiple methods of authentication.

For simplicity, the examples from this page use admin auth tokens.

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"
  ]
}