IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Custom Sources Document Permissions API Reference Search API Reference »

› ›

External Identities API Reference

edit

External Identities API Reference

edit

Refer to the Document access strategies for content sources for the conceptual walkthrough related to this API reference.

In this API reference

edit

External Identities API Overview

edit

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.

`content_source_key`	required	Unique key for a Custom API source, provided upon creation of a Custom API Source.
`access_token`	required	Must be included in HTTP authorization headers.
`user`	required	The `[USER_NAME]` can be placed into the request URL or in the request `user` field in the request body. You need to include a username, but where you put it is up to you. Username might reflect an Elasticsearch user: `example.mcname`, or whatever convention you’ve chosen to use.
`source_user_id`	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 identity

edit

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 identity

edit

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 identities

edit

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 identity

edit

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 identity

edit

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"

« Custom Sources Document Permissions API Reference Search API Reference »