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 »

›

Authentication

edit

Authentication

edit

The App Search API requires credentials for authentication.

Your credentials include your Host Identifier and your API Key:

Host Identifier: A unique string that represents your account. Required as part of the API endpoint.
API Keys: There are four different types. Can be created, scoped and destroyed.

There are various API Keys, public or private, broad scope or narrow scope, that you can apply depending on your needs.

Using the right key and keeping your keys under management will ensure that your Engines and account remain secure.

Key Types

edit

API Keys come in four different types:

Public Search Key The default API reading key has read-only search access to the Search endpoint. You can reveal this key to the public. Prefixed with search-.
Private API Key: The default API access key can read and write against all available API endpoints except for Credentials. You should keep this key secret. Prefixed with private-.
Private Admin Key: A special account management key that is used to request against the Credentials endpoint. You should keep this key very secret. Prefixed with admin-.
Signed Search Key: A more restrictive public key to query the Search endpoint resources. It is a JSON Web Token signed using a read only Private API Key by the HMAC-SHA256 algorithm.

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:

Generating New API Keys

edit

You can generate new keys in the Credentials dashboard menu:

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:

The Host Identifier is placed within the API Endpoint URI, [HOST_IDENTIFIER].
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 'https://[instance id].ent-search.[region].[provider].cloud.es.io/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 'https://[instance id].ent-search.[region].[provider].cloud.es.io/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 'https://[instance id].ent-search.[region].[provider].cloud.es.io/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 "https://[instance id].ent-search.[region].[provider].cloud.es.io/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 »