🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
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. You need a valid API key to send or update your data, search your index, or do anything else with Algolia’s API.

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

Predefined API keys

Algolia comes with a set of predefined API keys, the most important 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 lets you search your data. It works on all your Algolia application indices and is safe to use in your production frontend code.

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.

Risks of API key exposure

When using Algolia, your search-only API key is exposed and third parties could use it to:

  • Scrape everything from your indices
  • Flood your account with search requests

To mitigate these risks:

Define and secure access

API keys give you a secure way to manage access to your Algolia account. They let you:

  • Connect to your app.
  • Define permissions once connected. You can have search-only API keys to search your data or indexing keys to add or delete records and manage indices.

Define 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, 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.

Main and secured API keys

When generating API keys, you can create:

  • Long-lasting main API keys
  • Temporary, virtual, secured API keys.

Main API keys

Main API keys should be long-lasting and central to your solution.

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 are derived 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 restrict searches to 1,000 records or less (more restrictions). But it can’t lower the restrictions.

Secured API keys are virtual, which means they aren’t stored anywhere, and you can’t find them on the Algolia dashboard. Generate them as needed for circumstances like granting temporary access or giving users access to a subset of data.

Here are some common uses for secured API keys:

Create and manage your 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.

If base API key restrictions are updated, the updates are inherited by its derived secured API keys.

Revoke an API key

Revoking an API key makes it unusable.

If an API key is leaked or misused, it’s crucial to revoke it as soon as possible. You should also update your apps to use a new API key so they don’t stop working.

Main API keys

Revoke an API key by deleting it in the dashboard or with the deleteApiKey method. Deleting a main API key also deletes 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 used to generate it.

To make the API key automatically expire, set the validUntil parameter.

Restore an API key

If you delete an API key or it expires, you can restore it and its associated restrictions.

Restoring a deleted API key resets its expiry 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.

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. If you need thousands of API keys, you can create as many secured API keys as you want.

Next
Security best practices
Did you find this page helpful?