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 authentication
- Custom sources document permissions API overview
- Adding permissions
- Adding permissions in bulk
- Adding a single permission
- Removing permissions
- Removing all permissions
- Removing a single permission
- Listing permissions
- Listing all permissions
- Listing permissions for a user
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
|
required |
The |
|
required |
Unique ID for a Custom API source, provided upon creation of a Custom API Source. |
|
required |
Must be included in HTTP authorization headers. |
|
required |
The permissions array can accept any grouping of string values. The values must match those in the |
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" ] }