Guides / Security

API keys

On this page

API keys are necessary to work with Algolia. They give code-level access to your account, data, and index settings. Whether you’re sending or updating your data, searching your index, or doing anything else with Algolia’s API, you must use a valid API key.

Blog How an API key provides security
API keys vs JWT authorization
Inspect Algolia requests in browser developer tools

Predefined API keys

Algolia comes with a set of predefined API keys, the most important ones being the Admin API key and the Search-only API key.

Admin API key

Your Admin API key is your most sensitive key and should remain confidential.

Search-only API key

Algolia provides a search-only API key that allows you to search your data. It works on all the indices of your app and is safe to use in your production frontend code. Nevertheless, you may want to use this key to create more restricted API keys. For example, generate a search API key that limits access to a specific user, index, or a set of indices.

Other API keys

You can only use these APIs if your plan has access to them.

Defining and securing access

API keys give you a secure way for you to manage access to your Algolia account:

  • They let you connect to your app.
  • They let you define permissions once you’re connected. You can have search-only API keys to search your data or indexing keys to add or delete records and manage indices. You can also create all-purpose keys that let you search and index, but avoid doing this outside development.

Defining scope with restrictions

API keys can help you control and limit the scope and behavior of your APIs. For example, exclude some users, group others, limit the duration of a user’s access, and more.

Rights and restrictions

Access control list (ACL)

When creating an API key, you need to grant it an access level that controls actions like searching or updating. The ACL defines each allowed feature for a given API key.

  • Search (search): allowed to perform search operations.
  • Browse Index (browse): allowed to retrieve all index data with the browse endpoint.
  • Add records (addObject): allowed to add or update records in the index.
  • Delete records (deleteObject): allowed to delete an existing record.
  • 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 with the Analytics API.
  • Use recommendation API (recommendation): allowed to interact with the Recommendation API.
  • Use usage API (usage): allowed to retrieve data with the Usage API.
  • Access logs (logs): allowed to query the logs.
  • Get unretrievable attributes (seeUnretrievableAttributes): allowed to retrieve unretrievableAttributes for all operations that return records.

API key restrictions

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

  • Indices: the indices that are accessible.
  • Rate limit: limit the number of allowed API calls per hour.
  • Records retrieved: limit the number of retrieved records.
  • Validity: set an expiration time.
  • HTTP referrers: authorize HTTP referrers.
  • Query parameters: enforce specific query parameters.
  • Description: add a description to a particular key.
Guide API key restrictions

Main and virtual (secured) API keys

When generating API keys, you have two options:

  • Create main keys stored on your Algolia account. Your main API keys are usually long-lasting and central to your solution.
  • Create temporary, virtual keys. These are called secured API keys.

Main API keys

When creating a main API key, you must define all the rights and restrictions. You can create, view, and manage these from the dashboard or with the API. They’re usually long-lasting and central to your solution, but you should rotate them for security purposes.

Secured API keys

Secured API keys always derive from one of your main API keys. They inherit the rights and restrictions of their base API keys, which they can’t override. It means you can’t generate a secured API key with fewer restrictions than its base API key. For example, if a base key restricts a search to 1,000 records, a derived secured API key can keep that same restriction or limit it even more, but never less.

Secured API keys are virtual, which means they aren’t stored anywhere, and you can’t find them on the Algolia dashboard. You generate them on the fly, usually for particular circumstances like granting temporary access or giving a user access to a subset of data.

Here are some common uses for secured API keys:

Creating and managing API keys

You can create, view, and manage your main API keys from the dashboard and the API (using the addApiKey method).

You can’t see secured API keys on the Algolia dashboard and can only create them with the generateSecuredApiKey method.

API reference Add api key
Generate secured api key

If you update the restrictions on a base API key, the restrictions are applied to its derived secured API keys.

Revoking an API key

Revoking an API key makes it unusable. It’s crucial to revoke any compromised key, for example, a leaked write API key or a search API key being abused. However, remember to update your apps to avoid breaking them when the key they use becomes invalid.

Your main API keys

Revoke an API key by deleting it from the dashboard, or through the API, with the deleteApiKey method. When deleting a main API key, you’re also deleting all derived secured API keys. You can’t restore secured API keys, even if you restore the main key later.

Secured API keys

To revoke a secured API key, revoke the base API key you used to generate it.

Setting the validUntil parameter is recommended so the key automatically expires after some time. It avoids having to delete the base key.

API reference Delete api key

Restoring an API key

If you accidentally delete an API key, or if one of your API keys expires and you want to get it back, you can restore it along with its associated rights.

Restoring a deleted API key resets its expiration date (validUntil) to 0 (so that it doesn’t expire).

Algolia stores up to 1,000 deleted API keys. Above that point, Algolia permanently deletes the oldest API keys, and you can’t restore them.

Guide How to restore an API key

Team members

API keys belong to particular users within your app. With this in mind, here are a couple of best practices for assigning and handling API keys:

  • If you’re working with a team, link your Algolia account to a company email address, such as search@yourcompany.com. Don’t use the email address of a specific team member.
  • In production, use the API keys of the Algolia app owner. When doing this, you never have to change or rotate your production keys whenever you need to suspend a team member’s account.

Number of keys

The more keys you create, the more keys you need to manage. To avoid unmanageability and unauthorized use, create as many keys as you need, but no more. Make sure you revoke keys when you no longer need them.

You can create up to 5,000 API keys, but you should keep your count below this limit. If you need thousands of API keys, use inherited, secured API keys, which are unlimited.

Next
Security best practices
Did you find this page helpful?