> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API key restrictions

> Use API keys to control access and restrict the scope and behavior of your Algolia app.

export const SearchRequest = () => <Tooltip tip="A search request is a single HTTP call to the Algolia Search API that can run one or more search operations. It can include multiple queries, for example, when querying several indices at once.">
    search request
  </Tooltip>;

export const SearchQuery = () => <Tooltip tip="The text users enter into a search box. In the Search API, this corresponds to the query parameter. A search query is often used with filters, facets, and other parameters, but these aren't part of the query text itself.">
    search query
  </Tooltip>;

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

export const ApplicationID = () => <Tooltip tip="A unique alphanumeric string that identifies an Algolia application." cta="Application ID (dashboard)" href="https://dashboard.algolia.com/account/api-keys">
    application ID
  </Tooltip>;

export const Application = () => <Tooltip tip="An Algolia application is a self-contained environment with its own indices, configuration, and API keys. Applications don't share data or settings with each other.">
    application
  </Tooltip>;

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 <SearchQuery /> 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 />.

<Note>
  The [list](/doc/rest-api/search/get-dictionary-languages),
  [search](/doc/rest-api/search/search-dictionary-entries),
  and [retrieve](/doc/rest-api/search/get-dictionary-settings) 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.
</Note>

## 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](/doc/guides/scaling/infrastructure/classic/servers-clusters).
For example,
with a per-IP limit of 100,
each IP address can make up to 300 search 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:

* IP address or [`userToken`](/doc/api-reference/api-parameters/userToken)
* The API key used for the search or to create a [secured API key](/doc/guides/security/api-keys#secured-api-keys)
* The Algolia <ApplicationID />

For example, if you enforce rate limits on two `userToken`s 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`](/doc/libraries/sdk/v1/methods/add-api-key) or [`updateApiKey`](/doc/libraries/sdk/v1/methods/update-api-key) method to specify `maxQueriesPerIPPerHour`) or the dashboard:

1. Go to your dashboard's [**API Keys**](https://dashboard.algolia.com/account/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 <SearchRequest />.
The default value is `0` (unlimited, but [technically up to 1,000 records](/doc/api-reference/api-parameters/length)).
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](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/*`.

<Check>
  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](/doc/guides/security/security-best-practices#http-referrer-restrictions).
</Check>

## 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**](https://dashboard.algolia.com/account/api-keys/) section.
2. [Create a new API key](/doc/guides/security/api-keys#create-and-manage-your-api-keys) 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](/doc/api-reference/search-api-parameters) as in a Search API request.