Skip to main content
API keys can help you control and limit the scope and behavior of your APIs. For example, you can exclude some users, group others, and put limits on the duration of a user’s access. 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 a time limit.
  • HTTP referrers: allow specific referrers.
  • Query parameters: enforce specific query parameters.
  • Description: add a description to a particular key.

​
Indices

You can specify a list of indices that an API key can access. When unspecified, the key can access all indices. You can also specify groups of indices by matching a prefix or a suffix with a wildcard (*) character. For example:
  • dev_* restricts access to indices starting with dev_
  • *_dev restricts access to indices ending with _dev
  • *_dev_* restricts access to indices containing dev
  • products restricts access to the products index.
The list, search, and retrieve dictionary methods are exempt from this restriction because dictionaries are managed at the Algolia application level, across all indices, rather than at the API-key level.

​
Rate limit

You can limit the number of API calls per hour per IP address. The default setting is 0, meaning there is no rate limit. This helps protect you from malicious scripts or bots trying to extract data from your index. Rate limits apply to each of the three servers in a cluster. For example, with a per-IP limit of 100, each IP address can make up to 300 requests. If an IP address exceeds the combined per-server limit during the past hour, Algolia returns a 429 (Too Many Requests) HTTP status code. Rate limits apply based on a combination of: For example, if you enforce rate limits on two userTokens with two secured API keys, each combination is subject to its own rate limit.

​
How to rate-limit an API key

You can rate limit a key using the API (with the addApiKey or updateApiKey method to specify maxQueriesPerIPPerHour) or the dashboard:
  1. Go to your dashboard’s API Keys section.
  2. Click All API Keys.
  3. Create a new API Key or select an existing one to update.
  4. Enter a value for Max API calls/IP/hour.
  5. Click Create or Update.

​
Number of retrieved records

You can limit the number of records an API key can retrieve per search request. The default value is 0 (unlimited, but technically up to 1,000 records). As with rate limiting, this parameter can protect you from malicious scripts or bots.

​
Validity

You can set the validity duration of a key (in seconds). Short-lived API keys are useful to grant temporary access to your data, for example, during demos. The default value is 0 (never expires).

​
HTTP referrers

You can define a list of referrers authorized to query the API with a given key. If unspecified or empty, it defaults to any referrer. Specify referrers with the wildcard (*) character. For example:
  • https://algolia.com/* restricts access to referrers starting with https://algolia.com.
  • *.algolia.com restricts access to referrers ending with .algolia.com.
  • To allow access to the full algolia.com domain, use *algolia.com/*.
Like all HTTP headers, referrers can be spoofed, so you shouldn’t rely on them to secure your data. For more information, see HTTP referrers restrictions.

​
Query parameter restrictions

You can apply predefined query parameters to an API key. When using this key, the parameters apply to all queries, regardless of the user’s query. This ensures access to a specific subset of your data and enforces consistent query settings.

​
How to enter query parameters

  1. Go to your dashboard’s API keys section.
  2. Create a new API key or edit an existing one.
  3. In the Query Parameters field, enter the parameters as a single URL query string. For example: filters=type:book AND author:Rowling&hitsPerPage=10&facets=category&numericFilters=price>20
    • Join parameters with &.
    • Don’t wrap the string in {} or [].
    • Use the same parameter names as in a Search API request.
⌘I