- App Search Guide: other versions:
- Installation
- Getting started
- Authentication
- Limits
- Users and access
- Guides
- Adaptive relevance events logs reference
- Analytics Tags
- Crawl web content
- Crawl a private network using a web crawler on Elastic Cloud
- Curations
- Elasticsearch search
- Elasticsearch index engines (technical preview)
- Create Elasticsearch index engines
- Facets
- Hierarchical Facets
- Indexing Documents
- Language Optimization
- Log settings
- Meta Engines
- Precision tuning (beta)
- Query Suggestions
- Search UI
- Relevance Tuning
- Result Settings
- Result Suggestions
- Role based access control (RBAC)
- Sanitization, Raw or Snippet
- Search
- Synonyms
- View web crawler events logs
- Web crawler
- Web crawler FAQ
- Web crawler reference
- Web crawler events logs reference
- API Reference
- Adaptive relevance API reference (beta)
- Analytics APIs
- Analytics clicks API
- Analytics counts API
- Analytics queries API
- API logs API
- Click API
- Credentials API
- Curations API reference
- Documents API
- Elasticsearch search API
- Engines API
- Log settings API
- Multi search API
- Query suggestion API
- Schema API
- Search API
- Search API boosts
- Search API facets
- Search API filters
- Search API group
- Search API precision (beta)
- Search API result fields
- Search API search fields
- Search API sort
- Search API analytics tags
- Search settings API
- Search Explain API (beta)
- Source engines API
- Synonyms API
- Web crawler API reference
- API Clients
- Configuration
- Troubleshooting
Authentication
editAuthentication
editYou can access App Search APIs using any of the following:
Basic authentication (username & password)
editApp 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
editApp 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
editAPI 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
editAPI 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 and Web Crawler User agent. 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 and Web Crawler User agent endpoints. 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
editYou 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
editWe 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
editcurl -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
editcurl -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
editcurl -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
editA 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
editSigned 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...
|
A people management software system wants to search over |
|
A dating app wants to make sure only |
|
Adds filters to the search requests instead of restricting them. A store that only wants to show available products might set this to |
|
A search interface that wants to prevent a user from aggregating data might set this to |
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?
editNow that the different methods of authentication are clear to you, it’s a good time to jump into the API:
On this page