05 Oct 2018

API Keys

Overview

While API keys have several purposes, their basic purpose is to allow Algolia’s API to identify requests and know which level of authorization is tied to each key.

Note that your Admin API key is very sensitive: it should never be shared with anyone and must remain confidential.

Default API Keys

When creating your Algolia account, you’ll notice there are 3 different API keys by default:

Admin API Key

Your admin API key is the most sensitive key: it provides full control of all your indices and data. The admin API key should always be kept secure. Do NOT release it to anybody or do NOT use it in any application, and always create a new key that will be more restrictive. This API key should almost exclusively be used to generate other - more limited - API Keys that will then be used to search and perform indexing operations.

Search-only API Key

The search-only API key allows you to search on all indices. This key is safe to use in front-end code and in production. Nevertheless, you may want to create search API keys restricted to specific indices or with certain rate limits applied.

Monitoring API Key

The monitoring API key is used specifically for accessing the Monitoring API.

API Key Restrictions

You can set up authorizations and restrictions with a great level of precision when creating API keys. It’s common to combine these rules to make it very hard to use a public API key to crawl your data.

ACL

The ACL defines each feature that will be allowed for the given API key.

  • Search (search): allowed to perform search operations.
  • Browse Index (browse): allowed to retrieve all index contents via the browse API.
  • Add records (addObject): allowed to add/update an object in the index.
  • Delete records (deleteObject): allowed to delete an existing object.
  • List indices (listIndexes): allowed to get a list of all existing indices.
  • Delete index (deleteIndex): allowed to delete an index.
  • Get index settings (settings): allowed to read all index settings.
  • Set index settings (editSettings): allowed to update all index settings.
  • Use analytics API (analytics): allowed to retrieve data through the analytics API.
  • Access logs (logs): allowed to query the logs.

Indices

Algolia allows you to specify the list of targeted indices. If not indicated or empty, the access level will default to all indices. You can target indices by matching a prefix or a suffix using the * character. A few examples:

  • dev_* will restrict acccess to all indices starting with dev_
  • *_dev will restrict access to all indices ending with _dev
  • products will restrict access to the index with an exact match on the name products

Rate Limit

Additonally, you can define the maximum number of API calls allowed per hour and per IP address. The default value is 0 (no rate limit). This parameter can be used to protect you from attempts at crawling your entire index by bulk querying.

Each time an API call is performed with a rate-limited API key, there will be a verification step: if the number of API calls from this IP address has reached the limit during the past hour, a 403 HTTP code will be returned.

Number of Records Retrieved

Even beyond rate limiting, you can limit the maximum number of hits an API key can retrieve in one call. The default value is 0 (unlimited, which is technically 1000). Just like rate limiting, this parameter can be used to protect you from attempts at crawling your entire index by bulk querying.

Validity

It’s also possible to indicate the number of seconds for which a key will be valid. Ephemeral API keys can be used to grant temporary access to your data. The default value is 0 (no expiration). However, we recommend using the Secured API key feature with time restriction instead since it can take a few seconds to have the new key propagated on all Algolia machines.

HTTP Referers

You can define a list of referers authorized to call the API with a key. If not specified or empty, it will default to any referer. Referers can be targeted by matching a prefix or a suffix using the * character. A few examples:

  • https://algolia.com/* will restrict access to all referers starting with https://algolia.com
  • *.algolia.com will restrict access to all referers ending with .algolia.com
  • If you want to allow access for the full domain algolia.com, you can use *algolia.com/*

Like all HTTP headers, Referers can be spoofed, so you should not rely on it to secure your data. Please read our best practices using HTTP Referers.

Query Parameters

Finally, Algolia allows you to include a list of enforced search parameters. This parameter uses the URL string format, e.g. param1=X&param2=Y. However, we recommend using Secured API keys for strictly enforcing restrictions, as it’s a more secure and future-proof solution.

Description

In order to remember the purpose of the key, you can also specify a short name or description.

Generating API Keys

API keys can be created from the dashboard or through the API. Generating different API keys is a great way to fine-tune the restriction levels for your indices. This is very useful when you have several developers on your team, several apps interacting with Algolia, or very different types of users who have access to search.

As a quick example, consider a case where all the possible restrictions listed above are needed, with a search ACL. In a real implementation, you would most likely only need just a few of these options, or would use a Secured API key for more advanced features.

var params = {
  validity: 300,
  maxQueriesPerIPPerHour: 100,
  maxHitsPerQuery: 20,
  indexes: ['dev_*'],
  referers: ['algolia.com/*'],
  queryParameters: 'typoTolerance=strict&ignorePlurals=false',
  description: 'Limited search only API key for algolia.com'
};
client.addApiKey(['search'], params);

You can create up to 5000 API keys, but you should aim to keep your count well below this limit. If you need thousands of API keys, we recommend leveraging Secured API keys, as they are unlimited.

Secured API Keys

When you need to restrict the scope of the search key, we recommend using our secured API keys feature. This behavior is particularly useful for restricting access to a subset of your data, oftentimes based off a user’s permissions. It’s also a good way to scale API keys management since you can generate them on the fly without storing them on Algolia. Finally, you can use restricted secured API key to prevent users from querying unauthorized data.

Secured API keys can be created through the API.

A few important notes about secured API keys:

  • They will need to be generated on your back-end using one of our API clients
  • You can generate them on the fly (it won’t perform a request to Algolia)
  • They will not appear in the dashboard since they are generated by you and not sent to Algolia (you can create an unlimited number of these)
  • The search API key you use to generate them needs to be private: it should not be used on your front-end or shared in any manner
  • The secured API key will inherit all restrictions from the search API key used to generate it

Generating Secured API Keys

Either your Search-only API Key or any regular API key with a search ACL can be used as the “parent key” to generate a secured API key. The API client will compute a HMAC SHA-256 hash between the parent key that is used as a secret and the set of query parameters you want to enforce.

Secured API key can be generated from any API key except your admin API key.

Inheritance of restrictions

The generated key will always inherit all the permissions and restrictions of the parent API key.

Inheritance at query time

In your front-end code, you can add parameters but only if they aren’t already set in the secured API key. If you try to override a parameter that already exists in the secured API key, it will be ignored.

Specific Restrictions

On top of permissions and restrictions of the parent API key, some options can be set at the secured-key level to have more flexibility:

  • validUntil: This parameter is useful for creating ephemeral API keys. You can specify a date until which the key will be usable. The date must be a unix timestamp. Although you can set a validity on the parent API key, it isn’t as flexible since you can’t dynamically update regular keys on the fly like you can with Secured API keys.
  • restrictIndices: This parameter is used to restrict the query to only be valid for one or several indices. While it’s possible to set this parameter on the parent API key, it’s not as flexible or scalable in case you create one index per customer and want to generate keys dynamically. If this parameter is not specified, or if its value is empty, all indices can be accessed with respect to the constraints of the parent API key.
  • restrictSources: This parameter allows you to restrict the API key to only be valid for one IPv4 network. The source is a network in decimal notation with the netmask length, e.g. 192.168.1.0/24. If you want to restrict for one specific IP, use the following notation: 192.168.1.1/32.
  • userToken: This parameter allows you to apply the rate limit on a user token instead of the user IP. This is useful for authenticated users who could potentially share the same IP address (home, office or public networks).

All other API key options can be set on the parent key and will be inherited by the Secured API key. If you update the restrictions on the parent API key, it will automatically update them for the existing Secured API keys as well.

Search parameters

You can use any set of search parameters to generate a Secured API key. For example, filters is often used to restrict access to a subset of your data; restrictIndices limits access to a subset of indices, and so on. All search parameters are available for this purpose, letting you define many granular levels of API access. See example that follows.

Example

Here’s a quick example of how to generate the key from your back-end:

var searchOnlyApiKey = 'BIEV2YG99YSHTKQXQM';
var params = {
  hitsPerPage: 20,
  filters: '_tags:user_42 AND available = 1',
  validUntil: currentTimestamp + 3600,
  restrictIndices: 'index1,index2',
  userToken: 'user_42',
  restrictSources: '192.168.1.0/24'
};
var publicKey = client.generateSecuredApiKey(searchOnlyApiKey, params);

Secured API keys cannot be created from the dashboard. They have to be created at the API level.

Revoking a secured API key

To revoke a secured API key you need to revoke the parent key. Note that when revoking the parent key it will revoke all the keys that have beeen generated from it.

Because of this we recommend that you always set validUntil so the key auto expires after a period of time. This avoids having to delete the parent key.

Using Secured API Keys

A quick example of a front-end using a Secured API key:

var apiKey = fetchSecuredApiKeyFromBackend('user_42');
var client = algoliasearch('APP_ID', apiKey);
var index = client.initIndex('index1');
index.search('something', callback);

Secured API keys are strongly recommended for certain use cases:

  • SaaS: one API key per user is recommended for securely handling search in SaaS applications.
  • Mobile: you should never hard-code the API key in your mobile application. Instead, it’s recommended to fetch the API key from your back-end with only the necessary authorization. A secured API key is therefore a good choice for a scalable implementation.

Revoke an API Key

Revoking an API key will instantly make it unusable. It’s important to revoke a key in a case where it may have been compromised (a write-API key leaked, a search-API key is being abused, …), but keep in mind that you need to plan updates for your application accordingly to avoid breaking it when the key becomes invalid.

Regular API Key

You can revoke an API key by deleting it from the dashboard, or through the API:

// Delete any key with the client
client.deleteApiKey('7f2615414bc619352459e09895d2ebda');

// Delete an index-specific key
index.deleteApiKey('9b9335cb7235d43f75b5398c36faabcd');

Secured API Key

To revoke a secured API key, you have to revoke the “parent” API key that was used to generate it, as described above.

Having one API Key per User

One usage of secured API keys is to allow users to see only part of an index even when this index contains the data of all users. In that case, you can tag all records with their associated user_id in order to add a user_id=42 filter when generating the Secured API Key, in order to retrieve only those records a user is tagged in.

Try these tutorials

If you want to get started implementing secured API keys, we have a tutorial you might find helpful:

© Algolia - Privacy Policy