API key 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.

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.

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.

Rate limit

You can set a maximum number of API calls per hour for each IP address. The default setting is 0, meaning there is no rate limit. This helps protect your system from external attempts to crawl your entire index with bulk querying.

When using a rate-limited API key, if the number of API calls from an IP address exceeds the limit during the past hour Algolia returns a 429 (Too Many Requests) HTTP status code.

Rate limits are applied based on a combination of:

• IP address or userToken
• The API key used for the search or to create a secured API key
• The Algolia application ID.

For example, if you enforce rate limits on two userTokens with two secured API keys, each combination of userToken and secured API key will have 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

Beyond rate limiting, you can limit the maximum number of hits an API key can retrieve in one call. The default value is 0 (unlimited, but technically up to 1,000 hits). As with rate limiting, this parameter can protect you from external attempts to crawl your entire index by bulk querying.

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 parameters

When generating an API key, you can use any set of search parameters.

For example, filters will restrict access to a subset of your data. All search parameters are available for this purpose, letting you define granular levels of API access.