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 has access to all indices. You can also target groups of indices by matching a prefix or a suffix using the * character.

For example:

• dev_* restricts access to all indices starting with dev_
• *_dev restricts access to all indices ending with _dev
• *_dev_* restricts access to all indices containing _dev_
• products restricts access to the index called products

Rate limit

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 userToken
• 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.

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.

You can target referrers by matching a prefix or a suffix using the * wildcard:

• https://algolia.com/* restricts access to all referrers starting with https://algolia.com.
• *.algolia.com restricts access to all referrers ending with .algolia.com.
• To allow access for the full algolia.com domain, you can use *algolia.com/*.

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 Referer and 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.

Query parameters

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.