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

Authentication

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

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:

Credentials view

Generating New API Keys

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

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.
curl -X GET 'https://[HOST_IDENTIFIER].api.swiftype.com/api/as/v1/engines/[ENGINE]/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [API_KEY]' \
...
endpoint accessSearch endpoint only.
writeThis key can not perform write operations.
readThis key can only read resources such as documents from the Search endpoint
Engine accessCan access specific Engines or all Engines. Defaults to all Engines.

Private API Key Permissions

curl -X POST 'https://[HOST_IDENTIFIER].api.swiftype.com/api/as/v1/engines/[ENGINE]/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [API_KEY]' \
...
endpoint accessAll, except for the Credentials endpoint.
writeCan create, update or destroy resources such as documents.
readCan read resources such as documents.
Engine accessCan access specific Engines or all Engines. Defaults to all Engines.

Private Admin Key Permissions

curl -X PUT 'https://[HOST_IDENTIFIER].api.swiftype.com/api/as/v1/credentials' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [API_KEY]' \
...
endpoint accessCredentials endpoint only.
writeCan create, update, or destroy credential resources relating to the various API Keys.
readCan read credential resources such as the name, key and scope of an API Key.
Engine accessApplies to your account and does not interact with Engines.

URL Parameters

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://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search?auth_token=search-soaewu2ye6uc45dr8mcd54v8&query=example-query"

Example - A GET request to complete a basic search with the Public Search Key using URL parameters.
No Java example available, showing cURL
curl -X GET "https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search?auth_token=search-soaewu2ye6uc45dr8mcd54v8&query=example-query"

Example - A GET request to complete a basic search with the Public Search Key using URL parameters.
No Node example available, showing cURL
curl -X GET "https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search?auth_token=search-soaewu2ye6uc45dr8mcd54v8&query=example-query"

Example - A GET request to complete a basic search with the Public Search Key using URL parameters.
No Ruby example available, showing cURL
curl -X GET "https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search?auth_token=search-soaewu2ye6uc45dr8mcd54v8&query=example-query"

Example - A GET request to complete a basic search with the Public Search Key using URL parameters.
No Python example available, showing cURL
curl -X GET "https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search?auth_token=search-soaewu2ye6uc45dr8mcd54v8&query=example-query"

Example - A GET request to complete a basic search with the Public Search Key using URL parameters.
No Javascript example available, showing cURL
curl -X GET "https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search?auth_token=search-soaewu2ye6uc45dr8mcd54v8&query=example-query"

Signed Search Keys

Signed Search keys have restrict and augment search options through read-only permissions and alter search requests.

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

But they can't overwrite filters.

Instead, filters are used to add filters to the search request to restrict possible results.

Signed Search Keys should only be created with an existing Private API key with read access.

When to Use Signed Search Keys

Signed search Keys are meant to keep your private API read only keys secret and restrict what a user can search over.

For example...

search_fieldsA people management software system wants to search over first_name and last_name but not social_security_number.
They might set this to {"first_name": {}, "last_name": {}}
result_fieldsA dating app wants to make sure only first_name and hobbies are accessible but not home_location and phone_number.
They might set this to {"first_name": {}, "hobbies": {}}
filtersA store that only wants to show available products might set this to {"status": "available"}
facetsA search interface that wants to prevent a user from aggregating data might set this to {} or null
Example - Creating a Signed Search Key that will only return the name field and filter results to only "available" cars.
No cURL example available, showing Node
const SwiftypeAppSearchClient = require('swiftype-app-search-node')

const readOnlyApiKey = 'private-xxxxxxxxxxxxxxxxxxxx'
const apiKeyName = 'private-key'
const enforcedOptions = {
  result_fields: { title: { raw: {} } },
  filters: { world_heritage_site: 'true' }
}

const signedSearchKey = SwiftypeAppSearchClient.createSignedSearchKey(readOnlyApiKey, apiKeyName, enforcedOptions)

const client = new SwiftypeAppSearchClient('host-2376rb', signedSearchKey)
client.search('national-parks-demo', 'everglade')

Example - Creating a Signed Search Key that will only return the name field and filter results to only "available" cars.
import com.swiftype.appsearch.Client;

String readOnlyApiKey = "private-xxxxxxxxxxxxxxxxxxxx"; String apiKeyName = "private-key";

Map<String, Object> title = new HashMap<>(); title.put("raw", Collections.emptyMap()) Map<String, Object> resultFields = new HashMap<>(); resultFields.put("title", title); Map<String, String> filters = new HashMap<>(); filters.put("world_heritage_site", "true"); Map<String, Object> enforcedOptions = new HashMap<>(); enforcedOptions.put("result_fields", resultFields); enforcedOptions.put("filters", filters);

String signedSearchKey = Client.createSignedSearchKey(readOnlyApiKey, apiKeyName, enforcedOptions);

Client client = new Client("host-2376rb", signedSearchKey); Map<String, Object> response = client.search("national-parks-demo", "everglade");

Example - Creating a Signed Search Key that will only return the name field and filter results to only "available" cars.
const SwiftypeAppSearchClient = require('swiftype-app-search-node')

const readOnlyApiKey = 'private-xxxxxxxxxxxxxxxxxxxx' const apiKeyName = 'private-key' const enforcedOptions = { result_fields: { title: { raw: {} } }, filters: { world_heritage_site: 'true' } }

const signedSearchKey = SwiftypeAppSearchClient.createSignedSearchKey(readOnlyApiKey, apiKeyName, enforcedOptions)

const client = new SwiftypeAppSearchClient('host-2376rb', signedSearchKey) client.search('national-parks-demo', 'everglade')

Example - Creating a Signed Search Key that will only return the name field and filter results to only "available" cars.
require 'swiftype-app-search'

read_only_api_key = 'private-xxxxxxxxxxxxxxxxxxxx' api_key_name = 'private-key' enforced_options = { result_fields: { title: { raw: {} } }, filters: { world_heritage_site: 'true' } }

signed_search_key = SwiftypeAppSearch::Client.create_signed_search_key(read_only_api_key, api_key_name, enforced_options)

client = SwiftypeAppSearch::Client.new(host_identifier: 'host-2376rb', api_key: signed_search_key) client.search('national-parks-demo', 'everglade')

Example - Creating a Signed Search Key that will only return the name field and filter results to only "available" cars.
from swiftype_app_search import Client

read_only_api_key = 'private-xxxxxxxxxxxxxxxxxxxx' api_key_name = 'private-key' enforced_options = { 'result_fields': { 'title': { 'raw': {} } }, 'filters': { 'world_heritage_site': 'true' } }

signed_search_key = Client.create_signed_search_key( read_only_api_key, api_key_name, enforced_options)

client = Client('host-2376rb', signed_search_key) client.search('national-parks-demo', 'everglade')

Example - Creating a Signed Search Key that will only return the name field and filter results to only "available" cars.
No Javascript example available, showing Node
const SwiftypeAppSearchClient = require('swiftype-app-search-node')

const readOnlyApiKey = 'private-xxxxxxxxxxxxxxxxxxxx' const apiKeyName = 'private-key' const enforcedOptions = { result_fields: { title: { raw: {} } }, filters: { world_heritage_site: 'true' } }

const signedSearchKey = SwiftypeAppSearchClient.createSignedSearchKey(readOnlyApiKey, apiKeyName, enforcedOptions)

const client = new SwiftypeAppSearchClient('host-2376rb', signedSearchKey) client.search('national-parks-demo', 'everglade')

What's Next?

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


Stuck? Looking for help? Contact support or check out the App Search community forum!