Icon security white

API Keys

Last updated 01 August 2017

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 restricted. 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 setup 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 API endpoints.

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/*

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. Generate 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 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.

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.

It’s important to only use search-only API keys to generate secured API keys, NOT your admin API key.

Specific Restrictions

Even though restrictions from the parent API key will be transferred to the secured one, 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.
  • 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 almost all of the search parameters available when generating a secured API key. As an example, filters is often used to restrict access to only a subset of your data. It’s useful when all user data are grouped in one index but you want to make sure that each user can only search through his or her own records.

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.

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 (write API key leaked, search API key is being abused, …etc.), 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 for regular API keys.

What’s next

Continue building your Algolia knowledge with these concepts:

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

© Algolia - Privacy Policy