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

For the App Search API to respond to requests, you must include a pair of credentials in order to authenticate. Your credentials include your Host Identifier and your API Key:

  • The Host Identifier is a fixed value that represents your account. It will be included in your API Endpoint along with each request.

  • API Keys come in four different types and can be created, scoped and destroyed. They provide safe, regulated access to your Engines and administrative tools.

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 while you enjoy all that App Search can offer you.

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 best explain how API calls are assembled by demonstrating 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].

Depending on how you are using the API, you will need to use the right type of key in the right context. 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 read-only permissions and alter search requests by restricting or augmenting search options. It can be used to overwrite any top-level search options (e.g. query, search_fields, etc.) except filters. Instead, filters is used to add filters to the search request to restrict possible results. Signed Search Keys should only be created by 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. Some examples are:

search_fieldsA people management software system and want to enforce that users can only search over first_name and last_name but not social_security_number might set this to {"first_name": {}, "last_name": {}}
result_fieldsA dating app that wants to make sure only first_name and hobbies are accessible so a bad user cannot retrieve home_location and phone_number might set this to {"first_name": {}, "hobbies": {}}
filtersA store that only wants to show products that are available might set this to {"status": "available"}
facetsA search interface that wants 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, you are ready to start making API requests. It might be most useful to first check-out Indexing Documents. After that, you can explore the Search Guide to learn the fundamentals of search and how to differentiate between the Public Search Key and the Private Admin Key. Or, explore the Credentials API Reference to learn how to manage credentials with the Private Admin Key.


Stuck? Looking for help? Contact Support!