External Identities API Referenceedit
Refer to the Document access strategies for content sources for the conceptual walkthrough related to this API reference.
In this API referenceedit
External Identities API Overviewedit
An external identity is a mapping from external to internal users. They are bound to a content source. You will need to set up external identities for all users if you are connecting a content source with permissions enabled.
|
required |
Unique key for a Custom API source, provided upon creation of a Custom API Source. |
|
required |
Must be included in HTTP authorization headers. |
|
required |
The |
|
required |
The username or identifier for this user at the external source. For example for Google Drive this field is the e-mail used. |
Add an external identityedit
POST /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities
Adds a new external identity.
curl -X POST http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities \ -H "Authorization: Bearer [ACCESS_TOKEN]" \ -H "Content-Type: application/json" \ -d '{ "user": "john.doe", "source_user_id": "john.doe@example.com" }'
{ "source_user_id": "john.doe@example.com", "user": "john.doe" }
Show an external identityedit
GET /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities/[USER]
Retrieves an external identity.
curl -X GET http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities/john%2Edoe \ -H "Authorization: Bearer [ACCESS_TOKEN]"
{ "source_user_id": "john.doe@example.com", "user": "john.doe" }
The user should be URL encoded.
List all external identitiesedit
GET /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities
Retrieves all external identities.
curl -X GET http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities -H "Authorization: Bearer [ACCESS_TOKEN]"
{ "meta": { "page": { "current": 1, "total_pages": 1, "total_results": 1, "size": 25 } }, "results": [ { "source_user_id": "john.doe@example.com", "user": "john.doe" } ] }
This endpoint can be paginated with current
and size
query paramters.
Update an external identityedit
PUT /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities/[USER]
Updates an external identity.
curl -X PUT http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities/john%2Edoe \ -H "Authorization: Bearer [ACCESS_TOKEN]" \ -H "Content-Type: application/json" \ -d '{ "source_user_id": "john.doe2@example.com" }'
{ "source_user_id": "john.doe2@example.com", "user": "john.doe" }
Remove an external identityedit
DELETE /api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities/[USER]
Deletes an external identity.
Deleting an external identity in Enterprise Search 7.8.0 does not remove the permissions granted to the linked Workplace Search user. To prevent the user from searching the corresponding content source, an admin must stop sharing the content source with the Workplace Search user. The forthcoming Enterprise Search 7.8.1 release fixes this issue.
curl -X DELETE http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities/john%2Edoe \ -H "Authorization: Bearer [ACCESS_TOKEN]"
"ok"