External Identities API Reference
editExternal Identities API Reference
editRefer to the Document access strategies for content sources for the conceptual walkthrough related to this API reference.
In this API reference
editAPI Authentication
editWorkplace Search APIs support multiple methods of authentication.
For simplicity, the examples from this page use admin auth tokens.
External Identities API Overview
editAn external identity is a mapping from external to internal users.
Each mapping you create is bound to a single content source, represented by [CONTENT_SOURCE_ID]
. This means that you will need to create an object for each content source, and then map the third-party user to the Workplace Search user. Furthermore: you will need to set up external identities for all users if you are connecting a content source with permissions enabled.
|
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 |
|
required |
The username or identifier for this user at the external source. See the guides for each source’s user IDS: |
Add an external identity
editPOST /api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities
Adds a new external identity per content source.
curl -X POST http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_ID]/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" }
If the same user
is present in multiple authentication realms configured for Enterprise Search,
they will all be mapped to source_user_id
.
Show an external identity
editGET /api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities/[USER]
Retrieves an external identity for a content source.
curl -X GET http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_ID]/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 identities
editGET /api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities
Retrieves all external identities for a content source.
curl -X GET http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_ID]/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 identity
editPUT /api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities/[USER]
Updates an external identity.
curl -X PUT http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_ID]/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 identity
editDELETE /api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities/[USER]
Deletes an external identity for a content source.
curl -X DELETE http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities/john%2Edoe \ -H "Authorization: Bearer [ACCESS_TOKEN]"
"ok"