API Keys

Normally, requests to the Search Expander API will be sent directly from the end user's browser. These requests are authenticated using a combination of the request's referrer domain and your unique search engine ID. If you wish, you can take a different approach and make these requests via a proxy with a secret API key, and disable direct requests from browsers.

The API key must not be added into client-side code, and can only be used in conjunction with a proxy server. The server endpoint must be specified by the apiUrlTemplate setting in the object passed to sxpr(). (For information on the sxpr() function, see the Integrating Search Expander documentation.)

Your proxy will receive a request data object from the client and add key and domain properties to this object for authentication before forwarding it on to the Search Expander API.

The steps to set this up are:

  1. Create an API key via your Search Expander account dashboard
  2. Set your account to reject requests without an API key
  3. Set up a proxy for processing client requests to the Search Expander API
  4. Specify the proxy endpoint using apiUrlTemplate

Create API key and disable other requests

  • Log in to Search Expander and visit the account settings page at www.searchexpander.com/account/settings.
  • Scroll down to the API Key section and click Create API key.
  • Store the API key somewhere secure.
  • Enable the switch labelled Reject requests without API key.

Set up a proxy

Your proxy server must be set up to:

  • Receive Search Expander API requests
  • Add your API key and search engine domain name to request data
  • Call the Search Expander API and return its response

Below is a PHP example of how the proxy code might be implemented. For the purposes of this example, assume the proxy script is in the PHP file api-proxy.php, located under your search engine page's domain.

// api-proxy.php

/**
 * WARNING: This is simplified code for instructional purposes. It has no security precautions or error handling!
 */

// In this example, the API path will be passed to the proxy in a query string variable named 'sx-api-path':
$api_path = $_GET['sx-api-path'] ?? null;
if (!$api_path) {
    die('No sx-api-path set in query string');
}

// Create SX API request URL:
$api_url = 'https://api.searchexpander.com' . $api_path;

// Get the JSON-encoded POST body sent by the sxpr() JS function:
$request_data = json_decode(file_get_contents('php://input'), true);

// In this example, API key and domain are stored in the environment variables SX_API_KEY and SX_SE_DOMAIN:
$request_data['key'] = $_ENV['SX_API_KEY']; // Add API key to the SX API request data
$request_data['domain'] = $_ENV['SX_SE_DOMAIN']; // Add search engine domain name to the SX API request data

// Prepare cURL request to the SX API:
$ch = curl_init($api_url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request_data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

// Get the JSON response from the SX API:
$response = curl_exec($ch);

// Check for an error:
$error = curl_error($ch);

curl_close($ch);

if ($error) {
    die('There was an error: '.$error);
}

// Output the JSON response from Search Expander:
echo $response;

(Note on PHP: Search Expander uses JSON across the board for its requests and responses, which means you cannot normally read its values directly from the $_POST superglobal.)

Specify your proxy endpoint

The JavaScript function sxpr() needs to know to send API requests to your proxy instead of directly to the Search Expander API. You need to specify a URL template for this purpose. In the above example, the URL template would be:

/api-proxy.php?sx-api-path={path}

The {path} tag will be automatically replaced with the appropriate Search Expander API path when a request is made.

Add this URL template to the sxpr() settings object in the following way:

sxpr({
    se: 'your-search-engine-id',
    apiUrlTemplate: '/api-proxy.php?sx-api-path={path}',
    // ... other settings
});

» Widget Settings