IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Custom sources indexing API reference External Identities API Reference »

› ›

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:

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 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:

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

« Custom sources indexing API reference External Identities API Reference »