External Identities API Reference | Workplace Search Guide [7.11]

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 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.

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.

`content_source_id`	required	Unique ID 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. See the guides for each source’s user IDS: Atlassian User IDs Box User IDs Google User IDs Microsoft User IDs

Add an external identityedit

POST /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"
}

Show an external identityedit

GET /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 identitiesedit

GET /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 identityedit

PUT /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 identityedit

DELETE /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"

« Custom sources document permissions API reference Search API Reference »