Concepts / Security / API keys
Aug. 05, 2019

Quick overview

API keys are required to access our API clients or Rest API methods. They give you code-level access to your account, data, and index settings. Whether you’re pushing or updating your data, searching it, or doing anything else with Algolia’s API, you need to provide a predefined API key.

Main vs. virtual keys

When generating API keys, you have two options:

  • Create main keys, accessible on the dashboard and API methods. Your main API keys are usually long-lasting and usually central to your solution.
  • Create temporary, virtual keys, accessible only by API methods. These are called Secured API keys.

Algolia comes with three pre-defined API keys

Admin API key

Your admin API key is the most sensitive key: it provides full control of all your indices and data. Your admin key should be used to generate other API Keys that will in turn be used to search and perform indexing operations. Any key generated by the Admin key will be more restrictive than the Admin key itself.

Search-only API key

As a convenience, Algolia provides you with a “search only” API key that allows you to immediately search your data. It works on all indices and is safe to use in your front-end code in production. Nevertheless, you may want to use this key to create more application-specific API keys, which have additional restrictions. For example, you can generate a search API key that limits access to only one specific user.

Monitoring API key

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

Every account comes with an admin key, which can never be deleted. Please be aware: your admin API key is very sensitive, it should never be shared with anyone and must remain confidential. It should only be used in your back end for administrative purposes, as discussed below.

Using API keys to secure and define access

Defining basic rights

As stated above: API keys provide a secure way for you to manage access to your Algolia account. They do this in two important ways:

  • They allow you to connect to your application, establishing a right of access, a way in.

  • They define permissions once you’re in. You can have search-only keys, used only for searching your data; or indexing keys that allow you to add or delete records, or manage whole indices. You can also create all-purpose keys that allow you to perform both searching and indexing operations, but we strongly advise against this except for development purposes.

Defining scope with restrictions

API keys do more than secure access. They help you control and limit the scope and behavior of your APIs. In other words, they define restrictions. For example, you can exclude some users, group others, put limits on the duration of a user’s access, and other such restrictions.

Rights and restrictions

Rights (ACL)

Every API key must be defined with a given access level that controls actions like searching or updating. Rights are defined by the 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.
  • Get unretrievable attributes (seeUnretrievableAttributes): allowed to retrieve unretrievableAttributes for all operations returning records.

Restrictions

Restrictions are optional. Every key can have one or more of the following restrictions:

  • Indices: Define which indices you can access.
  • Rate limit: limit the number of API calls allowed.
  • Records Retrieved: Limit the number of records retrieved.
  • Validity: Set a time of validity.
  • HTTP Referers: Authorize HTTP referers.
  • Query Parameters: Enforce specific query parameters.
  • Description: Add a description to a particular key.

Your main and virtual (secured) API keys

When generating your API keys, you always have a choice between creating a permanent or virtual key. We’ll discuss what these options mean, and then guide you to choosing the correct key.

Your main API keys

You main API keys are created without referring to another key. You start from zero and define all of their rights and restrictions. They are usually long-lasting and central to your solution. You can create, view, and manage these from the dashboard or the API.

Secured API keys (virtual)

Secured API keys are always derived from one of your main API keys, using the main key as a base key. Every Secured API key inherits the rights and restrictions of its base API key. Secured API keys are virtual. They are not viewable on the Dashboard, they are accessible only via the API.

Summarizing the differences between main and secured API keys

  • Main API keys are visible and managed on the dashboard.

  • Secured API keys cannot be created or seen on the dashboard. They are virtual, created only via the API. They are not stored anywhere in Algolia, which accounts for why they cannot be seen on the dashboard.

  • Main API keys are usually used to stabilize an application or process. They normally define the outer limit of all rights and restrictions for an application or process. For example, if you have 2 applications, you’ll usually have 2 main API keys.

  • Secured API keys cannot override their base key’s settings. They either have the same level of rights and restrictions, or they are more restrictive. For example, if a base keys restricts (rate limits) a search to 1000 records, its derived secured API key can keep that same restriction or limit it even more (say, 100 records). However, it can never be less restrictive by changing the rate limit to more than 1000.

  • Main API keys are usually long-lasting and central to your solution. There is rarely a reason to delete them.

  • Secured keys are generated on the fly and used for very particular circumstances, like granting temporary access or giving a user access to only a subset of data.

Common use cases for secured API keys

  • Many users: when you want to generate a lot of API keys. For example, one key per user.
  • 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.

How many keys do you need?

You don’t need too many keys. If you’re working with one index and only pushing data and searching, two keys are sufficient: one for indexing and another for searching. However, there are many situations when two keys are not enough:

  • When you have multiple indices.
  • When you have more than one application.
  • When you have multiple search bars.
  • When you’re managing different groups of users.
  • And any other situation where you could benefit from keys with differing rights and/or restrictions.

Keep in mind that the more keys you create, the more you’ll need to keep track of them. To avoid unmanageability and unauthorized use, create as many keys as you need, but no more than that. Make sure you revoke keys when you no longer need them.

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 inherited, secured API keys, as they are unlimited.

Creating and managing keys

How to create API keys

You can create, view, and manage your main API Keys from the dashboard, as well with the API using the Add API Key method.

Secured API keys are not viewable on the Dashboard. You can only create them by using the Generate Secured API key method.

You cannot generate secured API keys from your admin API key or other secured API keys.

Note that if you update the restrictions on the base API key, it will automatically update the restrictions on its Secured API keys as well.

How to 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.

Your main API keys

You can revoke an API key by deleting it from the dashboard, or through the API. Note that by deleting a main API key, all secured API keys derived from it are also deleted and can never be restored, even if you later restore the main key.

Secured API keys

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

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

How to restore an API key

If you deleted an API key by accident, or if one of your API keys expired and you want to get it back, you can restore it along with its associated rights.

When you restore a deleted API key, the validity limit is automatically reset to 0 (unlimited).

Keep in mind that we store up to 1,000 deleted API keys. Above that point, the oldest deleted API keys are permanently deleted and can’t be restored.

Best practices

When assigning API keys to your team members, it is important to remember that API keys are tied to particular users.

With this in mind, here are a couple of best practices for assigning and handling API keys:

  • If you are working with a team, your Algolia account should be linked to a company e-mail address, such as “search@company.com”; it should not be linked to a specific team member’s email.
  • In production, you should use the API keys of your Algolia application owner: if you do this, you never have to change or rotate your production keys in case the account of the linked user has to be suspended.

Did you find this page helpful?