search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Understanding Authentication

API authentication ensures secure and authorized interactions with your account's engines. You can create different API keys based on their purpose, by controlling the scope and purpose of every key.

Every request made via the API needs to be authenticated and authorized using three (3) items:

  • an Account Host Key which identifies your account for all API requests
  • an Engine Slug which identifies the dataset to interact with, and
  • an API Key which authenticates you against both the engine and the account, with Read and/or Write permissions
Example - A typical API request with authentication
curl -X POST 'https://#{ACCOUNT_HOST_KEY}{ENGINE_SLUG}/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer #{API_KEY}' \
-d '[

Retrieving your API keys

Your API credentials are located in the API Keys area of the dashboard:

API Keys - Locate your Account Host Key and API keys
Credentials view

Generating a new API key

Upon engine creation, two keys are automatically created for you: a Private API key used for your internal application purposes, and a Publishable Search Key used for issuing search requests from any public client. To create Publishable Search Key, or a standard API key scoped to a limited set of engines, click the Create a Key button from the API Keys area:

API Keys - Creating a private indexing key
Creating an API Key

Once created, your new key is ready to be used within the scope for which it was originally created.

API and Account Host Key Reference

Account Host Key Alphanumeric key prefixed with host-, available in the App Search dashboard
Engine Slug Name of the engine, included as part of the request path
Private API Key Alphanumeric key with read/write privileges, prefixed with api-, available in the dashboard
Publishable Search Key Alphanumeric key with write privileges only, prefixed with search-, available in the dashboard.
Publishable Search Keys are also responsible for recording Search Analytics data for your engine.