API Keys/security
On this page
You are currently reading the documentation for InstantSearch.js V3. Read our migration guide to learn how to upgrade from V2 to V3. You can still find the V2 documentation here.
Search-Only API Keys on web
Inside your application you can use the search-only API Key. You can include this key directly in your front-end code. It might happen that you need to apply some rate limiting to your API Key. For those cases, you can generate what we call Secured API Keys.
Secured API Keys
Secured API Keys are useful when you want to restrict the search to a set of indices, for example. Those keys need to be generated on the back-end. Otherwise, users can modify the restrictions of the key by modifying the front-end code. There is already a tutorial about how to use Secured API Keys, but this guide will focus on the usage of those keys inside a InstantSearch.js application. We will implement an application that generates a secured API Key on the server, then uses it on the client. The secured API Key will have a restriction on the index. You can find the complete example on GitHub.
Server
Generate the Secured API Key
The first step is to generate our Secured API Key on the server. In this example we are using Express but the concepts could be applied to any server. To generate our key we need the Algolia JavaScript client and a “parent key” that has the search ACL. Most of the time this “parent key” will be the search-only API Key. In this example we restrict our key to the index demo_ecommerce. It means that with this key the front end won’t be able to target a different index. You can apply different kind of restrictions and also apply a set of search parameters.
1
2
3
4
5
6
7
8
9
const algoliasearch = require('algoliasearch');
const client = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');
const securedApiKey = client.generateSecuredApiKey(
'YourSearchOnlyAPIKey',
{
restrictIndices: 'demo_ecommerce',
}
);
Once we have the key we need to pass it down to our client. We have the choice between two different implementations:
- create an endpoint on your server that will send back the API Key. Then on the client before creating the application you need to asynchronously fetch the API key from the server.
- inline the API key in the HTML. Then on the client we can directly create the application by reading the value from the global object.
In this guide we will go for the second option: inline the API Key.
Inline the API Key
For simplicity, in this example we use Parcel. But with Parcel we don’t create the HTML file from scratch, we use the one generated by the CLI. To inject data from the server we can use a placeholder value in the HTML. Note that this step is only useful if you are using an application generated from a CLI. Otherwise you can directly inline the value inside your HTML template.
1
2
3
4
5
6
<!doctype html>
<html lang="en">
<head>
<script>
window.SERVER_DATA = __SERVER_DATA__;
</script>
Once the placeholder is setup we can replace it with the generated API Key.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const path = require('path');
const fs = require('fs');
const util = require('util');
const express = require('express');
const app = express();
const readFileAsync = util.promisify(fs.readFile);
app.get('/', async (_, res) => {
const index = await readFileAsync(
path.join(__dirname, 'dist', 'index.html'),
'utf-8'
);
const indexWithServerData = index.replace(
'__SERVER_DATA__',
JSON.stringify({
ALGOLIA_API_KEY: securedApiKey,
})
);
res.send(indexWithServerData);
});
That’s it for the server! You should now be able to run the server and access your generated API Key from the client with window.SERVER_DATA. Take a look at the next section to learn how to use this key in the InstantSearch.js application.
Client
Retrieve the API Key
Now that we have the API Key on the global object we can retrieve it from our client code and inject it into our searchClient. Don’t forget to clean up the global object otherwise this value will stay in memory.
1
2
3
4
5
6
7
8
9
10
11
const SERVER_DATA = window.SERVER_DATA;
// clean up the global object
delete window.SERVER_DATA;
const searchClient = algoliasearch('YourApplicationID', SERVER_DATA.ALGOLIA_API_KEY)
const search = instantsearch({
indexName: 'demo_ecommerce',
searchClient,
});
That’s it for the client! Your application can now only target the index demo_ecommerce. You can try to target a different one like demo_media but the API will return an error. Don’t forget to take a look at the complete example on GitHub.
XSS - Preventing attacks from within user generated content.
Algolia handles highlighting within the engine. By leveraging this feature, you give your user a way to know how their query matches the results, it is a very important cue.
Technically this means that the engine will surround the matching words with tags. By default, we use simple HTML tags like em and we let the browser render the content as HTML. This leaves a potential security hole, especially in the context of user generated content.
The same problem exists for the snippeting feature.
To fix this, InstantSearch.js will force the use of a known set of tags and will escape all the other HTML tags. This means that if you’ve set a custom tag in the Algolia Dashboard it will be overridden and replaced by mark. If you want to use another one, like for example strong, you need to specify the highlightedTagName props in highlight or snippet.
Usage with templates
You can provide the argument from the templating system.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const search = instantsearch({
indexName: 'instant_search'
searchClient,
});
search.addWidget(
instantsearch.widgets.hits({
container: '#hits',
templates: {
item: `
<article>
<p>Name: {{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}</p>
<p>Description: {{#helpers.snippet}}{ "attribute": "description" }{{/helpers.snippet}}</p>
</article>
`,
},
})
);
Usage with render functions
You can also provide the argument to the highlight and snippet functions from render functions.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
const search = instantsearch({
indexName: 'instant_search'
searchClient,
});
search.addWidget(
instantsearch.widgets.hits({
container: '#hits',
templates: {
item(hit) {
return `
<article>
<p>Name: ${instantsearch.highlight({ attribute: 'name', hit })}</p>
<p>Name: ${instantsearch.snippet({ attribute: 'name', hit })}</p>
</article>
`;
},
},
})
);
