API Key Restrictions

API Keys can help you control and limit the scope and behavior of your APIs. We call this restrictions. For example, you can exclude some users, group others, put limits on the duration of a user’s access, and other such restrictions.

Concretely, every key can have one or more of the following restrictions:

• Indices: Define which indices can be accessed.
• Rate limit: limit the number of API calls allowed.
• Records Retrieved: Limit the number of records retrieved.
• Validity Set an expiration time.
• HTTP Referers: Authorize HTTP referers.
• Query Parameters: Enforce specific query parameters.
• Description: Add a description to a particular key.

Let’s look at these restrictions in more detail.

Indices

With API keys you can specify a list of targeted indices. If not indicated or empty, the access level will default to all indices. You can target indices by matching a prefix or a suffix using the * character.

A few examples:

• dev_* will restrict access to all indices starting with dev_
• *_dev will restrict access to all indices ending with _dev
• *_dev_* will restrict access to all indices with dev in the middle of their name
• products will restrict access to the index with an exact match on the name 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.

Each time an API call is performed with a rate-limited API key, there will be a verification step: if the number of API calls from this IP address has reached the limit during the past hour, a 403 HTTP code will be returned.

Number of Records Retrieved

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, which is technically 1000). Just like rate limiting, this parameter can protect you from external attempts to crawl your entire index by bulk querying.

Validity

It’s possible to set the number of seconds that a key will remain valid. Temporary API keys can be used to grant temporary access to your data. The default value is 0 (no expiration).

HTTP Referers

You can define a list of referers authorized to call the API with a key. If not specified or empty, it will default to any referer. Referers can be targeted by matching a prefix or a suffix using the * character.

A few examples:

• https://algolia.com/* will restrict access to all referers starting with https://algolia.com
• *.algolia.com will restrict access to all referers ending with .algolia.com
• If you want to allow access for the full domain algolia.com, you can use *algolia.com/*

Like all HTTP headers, referers can be spoofed, so you should not rely on them to secure your data. Please read our best practices using HTTP Referers.

Query Parameters

Algolia lets you include a list of search parameters. This parameter uses the URL encoded string format, e.g. param1=X&param2=Y.

You can use any set of search parameters to generate a Secured API key. For example, filters is often used to restrict access to a subset of your data, restrictIndices limits access to a subset of indices, and so on. All search parameters are available for this purpose, letting you define granular levels of API access.

Description

Although not a restriction, you can add a description to your API keys to remember the purpose of the key.