API Authentication Reference

Workplace Search APIs support multiple authentication methods:

Each admin user has an access token that acts like a private API key. Access tokens are unique to every admin user. Access tokens must be used as bearer in the authorization header for every API call.

curl -X POST http://localhost:3002/api/ws/v1/sources/[ID]/documents/bulk_create \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '
  ...
'

To locate the access token for the logged-in admin user, navigate to the Details area of an existing Content Source that uses document-level permissions, such as Custom API Sources:

Figure 131. Retrieving an API Access Token

Workplace Search APIs support basic authentication headers to authenticate users. Consult your HTTP client’s documentation for its support of the basic authentication scheme. For example, cURL provides the -u and --user arguments to provide a username and password for each request.

curl -X POST http://localhost:3002/api/ws/v1/search \
-u "[USERNAME]:[PASSWORD]" \
-H "Content-Type: application/json" \
-d '{
  "query": "denali"
}'

Workplace Search APIs support Elasticsearch tokens generated by the Elasticsearch Token Service.

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "query": "denali"
}'

The Search API and the Analytics Events API support user access tokens generated by the Workplace Search OAuth Service. The token is acquired via an OAuth authorization flow. User access tokens are meant to be used for Custom Search Experiences.

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "query": "denali"
}'