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

API Keys

API keys are used to keep your account's engines secure. API keys can be restricted from doing certain actions on certain engines depending on their permissions.

Retrieving your API keys

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

Credentials view

Generating a new API key

Two keys are automatically created for your account. One is a Private API key and the other is a Publishable API Key. These have Access to All Engines by default. If you require more customization or granularity, more keys can be created here.

Creating an API Key

Types of API Keys

Account Host KeyAlphanumeric key prefixed with host-. This key is unique to your account and is used as part of all API request urls.
Private API KeyAlphanumeric key with read/write privileges, prefixed with api-. These should be kept private, as they may be able to delete data or expose sensitive data.
Publishable API KeyAlphanumeric key with read privileges only, prefixed with search-. To be used as a publicly visible key to query your engine's data.
Signed Search KeyA JSON Web Token signed with a private read-only key using the HMAC-SHA256 algorithm. To be used as a restrictive, publicly accessible key to query your engine's data.

Private API Key Permissions

writeCan create or update documents in an engine
Can delete an engine
readCan access the documents of an engine
Access All EnginesCan excercise read/write permissions across all engines
Needed with write permissions to create an Engine
An API key can have read or write access, but not to the engine you are performing API requests against. This will cause requests to return a 401 response.
The key that was used to sign a signed search key needs to exist for the signed search key to authenticate correctly.

Signed Search Keys

Signed search keys API keys only have read permissions and alter search requests by restricting or augmenting search options. It can completely overwrite all 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 with the id of and the 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.
from swiftype_app_search import Client

read_only_api_key = 'api-3958sdlfjadsf'
enforced_options = {
    'result_fields': {
        'name': {}
    },
    'filters': {
        'status': 'available'
    }
}
signed_search_key = Client.create_signed_search_key(read_only_api_key, 5, enforced_options)

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 = 'api-3958sdlfjadsf'
enforced_options = {
  :result_fields => {
    :name => {}
  },
  :filters => {
    :status => 'available'
  }
}
signed_search_key = SwiftypeAppSearch::Client.create_signed_search_key(read_only_api_key, 5, enforced_options)

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 = 'api-3958sdlfjadsf'
const enforcedOptions = {
  result_fields: {
    name: {}
  },
  filters: {
    status: 'available'
  }
}
const token = SwiftypeAppSearchClient.createSignedSearchKey(readOnlyApiKey, 5, enforcedOptions)

Example - Creating a signed search key that will only return the name field and filter results to only "available" cars.
import com.swiftype.appsearch.JWT;

String readOnlyApiKey = "api-3958sdlfjadsf"
String signedKey = Jwt.sign(
  readOnlyApiKey,
  "{\"typ\":\"JWT\",\"alg\":\"HS256\"}",
  "{\"result_fields\":{\"name\":{}},\"filters\":{\"status\":\"available\"},\"api_key_id\":5}"
);