API Keys

API keys are necessary to work with Algolia. They give you 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 need to use a valid API key.

Predefined API keys

Algolia comes with a set of predefined API keys.

Admin API key

Your Admin API key is your most sensitive key, and should remain confidential. It provides full control of all your indices and data. You should only use your Admin API to generate other, more limited API keys for searching and performing indexing operations. You should never share it with anyone, including the Algolia support team.

You must never use your Admin API key in any application. Its role is to generate other, more limited keys to use for searching and performing indexing operations.

Search-only API key

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

Monitoring API key

The Monitoring API key lets you access the Monitoring API. Note that you can only use this API if your plan has access to it.

Usage API key

The Usage API key lets you access the Usage API. Note that you can only use this API if your plan has access to it.

Analytics API key

The Analytics API key lets you access the Analytics API. Note that you can only use this API if your plan has access to it.

Defining and securing access

Defining basic rights

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

• They let you connect to your application.
• 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 both search and index, but you should avoid doing this except for development purposes.

Defining scope with restrictions

API keys can help you control and limit the scope and behavior of your APIs. For example, you can exclude some users, group others, put limits on 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 a 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: which indices 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.

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’re starting from zero, and 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 never 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 use cases for Secured API keys:

• Many users: when you need to generate an API key per user for an indefinite number of users.
• Mobile: you should never hard code API keys in your mobile application. Instead, you should generate a Secured API key from your back end with only the necessary authorization.

Creating and managing API keys

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

You can’t see your Secured API keys on the Algolia dashboard, and you can only create them by using the generateSecuredApiKey method.

If you update the restrictions on a base API key, it automatically updates the restrictions on its derived Secured API keys as well.

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, a search API key being abused. However, keep in mind that you need to update your applications to avoid breaking them when the key they use becomes invalid.

Your main API keys

You can 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 never restore Secured API keys, even if you later restore the main key.

Secured API keys

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

Therefore, you should always set the validUntil parameter, so the key automatically expires after some time. It avoids having to delete the base key.

Restoring 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, it automatically restores the validity limit to 0, meaning the key is unlimited.

Keep in mind that 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.

Best practices

Team members

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

• If you are working with a team, you should 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, you should use the API keys of your Algolia application owner. When doing this, you never have to change or rotate your production keys whenever you need to suspend the account of a team member.

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 5000 API keys, but you should aim to keep your count well below this limit. If you need thousands of API keys, you should use inherited, Secured API keys, which are unlimited.