Custom sources document permissions API reference
editCustom sources document permissions API reference
editThis 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
- 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 authentication
editWorkplace Search APIs support multiple methods of authentication.
For simplicity, the examples from this page use admin auth tokens.
Custom sources document permissions API overview
editPOST 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 permissions
editAdd 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
editPOST /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
editPOST /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
editRemove 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
editPOST /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
editPOST /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
editList permissions for one or all users, paginated.
Listing all permissions
editGET /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
editGET /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" ] }