Custom Sources Document Permissions API Reference

» »

« Custom Sources Indexing API Reference External Identities 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:

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

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:

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

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

« Custom Sources Indexing API Reference External Identities API Reference »