API key restrictions
On this page
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.
You can specify a list of indices that an API key can access. When unspecified, the key has access to all indices. You can also target groups of indices by matching a prefix or a suffix using the
dev_*restricts access to all indices starting with dev_
*_devrestricts access to all indices ending with _dev
*_dev_*restricts access to all indices containing _dev_
productsrestricts access to the index called products
You can define the maximum number of API calls allowed per hour and per IP address. The default value is
0 (no rate limit). This parameter can protect you from external attempts to crawl your entire index by bulk querying.
When using a rate-limited API key, if the number of API calls from an IP address has reached the limit during the past hour, the engine returns a
429 (Too Many Requests) HTTP code.
Rate limits apply to a combination of:
- IP address or
- The API key used for the search or used to create a secured API key
- The Algolia application ID
For instance, two
userToken restrictions enforced by two secured API keys will have two different rate limits (one for each
userToken/secured API key combination).
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.
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).
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.
You can target referrers by matching a prefix or a suffix using the
https://algolia.com/*restricts access to all referrers starting with https://algolia.com.
*.algolia.comrestricts access to all referrers ending with .algolia.com.
- To allow access for the full algolia.com domain, you can use
Like all HTTP headers, referrers can be spoofed, so you shouldn’t rely on them to secure your data. Please read the best practices using HTTP referrers.
Some browsers intentionally remove the
Origin headers from third-party requests. If you’re using a search API key with restrictions on the referrer, this will prevent users from searching on these browsers.
You can use any set of search parameters when generating an API key. For example, you can use
filters to restrict access to a subset of your data. All search parameters are available for this purpose, letting you define granular levels of API access.