Custom sources document permissions API reference | Workplace Search Guide [7.13]

» »

« Custom sources indexing API reference External Identities API Reference »

Custom sources document permissions API referenceedit

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

In this API referenceedit

Custom sources document permissions API authenticationedit

Workplace Search APIs support multiple methods of authentication.

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

Custom sources document permissions API overviewedit

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 permissionsedit

Add new permissions to a user.

There are two options:

Add Permissions in Bulk: Create a new set of permissions or over-write all existing permissions.
Add a Single Permission: Add one or more new permissions atop existing permissions.

Adding permissions in bulkedit

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 permissionedit

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 permissionsedit

Remove permissions from a user.

There are two options:

Remove All Permissions: Clear all permissions for a given user. Restores an empty array.
Remove a Single Permission: Remove one or more permission from an existing set of permissions.

Removing all permissionsedit

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 permissionedit

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 permissionsedit

List permissions for one or all users, paginated.

Listing all permissionsedit

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 useredit

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