IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Getting started Limits »
Elastic Docs ›

Authentication

edit

Authentication

edit

You can access App Search APIs using any of the following:

Basic authentication (username & password)

edit

App Search API endpoints support the Basic authentication scheme for HTTP. Use this scheme to authenticate each request using the username and password for your App Search or Elasticsearch user.

Most API clients support this scheme directly. For example, curl provides the -u and --user arguments to include your username and password with each request:

curl \
--request 'GET' \
--url '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/[ENGINE]/documents'
--user 'shay_banon:123456'

If your client does not support this scheme directly, include an Authorization: Basic header with each request. Refer to RFC 7617.

Elasticsearch tokens

edit

App Search API endpoints support tokens created by the Elasticsearch get token API. Use the Bearer authentication scheme for HTTP. For example:

curl \
--request 'GET' \
--url '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/[ENGINE]/documents'
--header 'Authorization: Bearer [TOKEN]'

App Search API keys

edit

API keys allow authenticated users to delegate some or all of their access to an API client, such as a search UI or another application integrating with App Search.

The following sections describe API keys in greater detail.

Key types

edit

API Keys come in four different types:

A Public Search Key and a Private API Key are generated when you create a new account.

By default, they can access all Engines. If you do not want to use the default keys, feel free to delete them.

You can find your default keys, edit and create new keys within the Credentials menu:

Credentials view

Generating new API keys

edit

You can generate new keys in the Credentials dashboard menu:

Creating an API key

Or you can generate the following keys using the Credentials API endpoint:

  • Public Search Keys
  • Private API Keys
  • Private Admin Keys

Authenticating your requests

edit

We can demonstrate API calls through a cURL request for each key type:

  • API Keys are included alongside each request as a Bearer token, [API_KEY]
  • Engine is needed to ensure the request goes to the correct Engine, if applicable: [ENGINE].

Each key has a different set of default permissions. You can also pass keys within URL Parameters.

A 401 response will be returned when an API Key is used to access an endpoint without the correct permissions.

Public search key permissions
edit
curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/[ENGINE]/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [API_KEY]' \
...

endpoint access

Search endpoint only.

write

This key can not perform write operations.

read

This key can only read resources such as documents from the Search endpoint

Engine access

Can access specific Engines or all Engines. Defaults to all Engines.
Private API key permissions
edit
curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/[ENGINE]/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [API_KEY]' \
...

endpoint access

All, except for the Credentials endpoint.

write

Can create, update or destroy resources such as documents.

read

Can read resources such as documents.

Engine access

Can access specific Engines or all Engines. Defaults to all Engines.
Private admin key permissions
edit
curl -X PUT '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [API_KEY]' \
...

endpoint access

Credentials endpoint only.

write

Can create, update, or destroy credential resources relating to the various API Keys.

read

Can read credential resources such as the name, key and scope of an API Key.

Engine access

Applies to your account and does not interact with Engines.
URL parameters
edit

A key can also be passed within URL parameters.

Example - A GET request to complete a basic search with the Public Search Key using URL parameters.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search?auth_token=search-soaewu2ye6uc45dr8mcd54v8&query=example-query'

Signed search keys

edit

Signed search keys keep your read only Private API Keys secret and restrict what a user can search over.

They can be used to restrict top-level search options, like search_fields, result_fields, and so on.

For example...

search_fields

A people management software system wants to search over first_name and last_name but not social_security_number. They can set the key to only search: {"first_name": {}, "last_name": {}}

result_fields

A dating app wants to make sure only first_name and hobbies are accessible but not home_location and phone_number. They can set the key to only search: {"first_name": {}, "hobbies": {}}

filters

Adds filters to the search requests instead of restricting them. A store that only wants to show available products might set this to {"status": "available"}

facets

A search interface that wants to prevent a user from aggregating data might set this to {} or null

Note that signed search keys do not work with query suggestions.

Signed search keys are created using one of our clients. They require an existing Private API key with read access.

For links to client documentation, see Programming language clients in the Enterprise Search documentation.

What’s next?

edit

Now that the different methods of authentication are clear to you, it’s a good time to jump into the API:

« Getting started Limits »