API client / Methods / API keys
Required API Key: Admin
Method signature
$client->addApiKey(array acl, [
  // All the following parameters are optional
  'validity'                => integer,
  'maxQueriesPerIPPerHour'  => integer,
  'maxHitsPerQuery'         => integer,
  'indexes'                 => array,
  'referers'                => array,
  'queryParameters'         => string,
  'description'             => string,
])

About this method

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

You’re currently reading the JavaScript API client v4 documentation. Check the migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

Add a new API Key with specific permissions and restrictions.

Examples

Read the Algolia CLI documentation for more information.

Create new API key

1
2
3
// Create a new API key that can only perform search actions
$res = $client->addApiKey(['search']);
echo 'key: ' . $res['key'] . "\n";

Create new API Key with specific restrictions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Create a new restricted search-only API key
$res = $client->addApiKey(['search'],
  [
    'description'            => 'Restricted search-only API key for algolia.com',
    // Allow searching only in indices with names starting with `dev_*`
    'indexes'                => ['dev_*'],
    // Retrieve up to 20 results per search query
    'maxHitsPerQuery'        => 20,
    // Rate-limit to 100 requests per hour per IP address
    'maxQueriesPerIPPerHour' => 100,
    // Add fixed query parameters to every search request
    'queryParameters'        => 'ignorePlurals=false',
    // Only allow searches from the `algolia.com` domain
    'referers'               => ['algolia.com/*'],
    // This API key expires after 300 seconds (5 minutes)
    'validity'               => 300,
]);

echo 'key=' . $res['key'] . "\n";

Parameters

acl
type: list
default: no default
Required

Set of permissions associated with the key.

The possible access controls are:

  • Search (search): allowed to perform search operations.
  • Browse Index (browse): allowed to retrieve all index data with the browse endpoint.
  • Add records (addObject): allowed to add or update a records in the index.
  • Delete records (deleteObject): allowed to delete an existing record.
  • List indices (listIndexes): allowed to get a list of all existing indices.
  • Delete index (deleteIndex): allowed to delete an index.
  • Get index settings (settings): allowed to read all index settings.
  • Set index settings (editSettings): allowed to update all index settings.
  • Use analytics API (analytics): allowed to retrieve data with the Analytics API.
  • Use recommendation API (recommendation): allowed to interact with the Recommendation API.
  • Use usage API (usage): allowed to retrieve data with the Usage API.
  • Access logs (logs): allowed to query the logs.
  • Get unretrievable attributes (seeUnretrievableAttributes): allowed to retrieve unretrievableAttributes for all operations that return records.
validity
type: integer
default: 0
Optional

How long this API key is valid, in seconds. A value of 0 means the API key doesn’t expire.

This parameter must be a positive integer.

maxHitsPerQuery
type: integer
default: 0 (unlimited)
Optional

Maximum number of hits this API key can retrieve in one query.

You can set this parameter to prevent attempts at retrieving your entire index in a single API call.

This parameter must be a positive integer.

maxQueriesPerIPPerHour
type: integer
default: 0 (no rate limit)
Optional

Maximum number of API calls per hour allowed from an IP address.

You can set this parameter to prevent attempts at retrieving your entire index through making many API calls.

Each time an API call is performed with this key, a check is performed.

If the IP address at the origin of the call made more than maxQueriesPerIPPerHour queries within the last hour, the API returns a 429 (Too Many Requests) status code.

This parameter must be a positive integer.

indexes
type: list
default: [] (all indices)
Optional

Specify the list of targeted indices. You can target all indices starting with a prefix or ending with a suffix using the ‘*’ character. For example, “dev_*” matches all indices starting with “dev_” and “*_dev” matches all indices ending with “_dev”.

referers
type: list
default: [] (all referrers)
Optional

Specify the list of referrers that can perform an operation. You can use the “*” (asterisk) character as a wildcard to match subdomains, or all pages of a website. For example, "https://algolia.com/\*" matches all referrers starting with "https://algolia.com/", and "\*.algolia.com" matches all referrers ending with ".algolia.com". If you want to allow all possible referrers from the algolia.com domain, you can use "\*algolia.com/\*".

This also works with localhost, when you’re developing your site: "\*localhost\*" matches all possible referrers on localhost.

queryParameters
type: string
default: "" (no query parameters)
Optional

Specify the list of query parameters. You can force the query parameters for a query using the url string format.

Example: typoTolerance=strict&ignorePlurals=false

You can also add a restriction on the IPv4 network allowed to use the generated key. This is used for more protection against API key leaking and reuse.

Note that you can only provide a single source, but you can specify a range of IPs (e.g., 192.168.1.0/24).

For security reasons, the creation of the key will fail if the server from which the key is created is not in the restricted network.

Example: typoTolerance=strict&restrictSources=192.168.1.0/24

description
type: string
default: ""
Optional

Specify a description of the API key. Used for informative purposes only. It has impact on the functionality of the API key.

requestOptions
type: key/value mapping
default: No request options
Optional

A mapping of requestOptions to send along with the request.

Response

This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language and/or implementation, the actual type in your language might differ from what’s written here. You can view the response in the logs (using the getLogs method).

JSON format

1
2
3
4
{
  "key": "1eb37de6308abdccf9b760ddacb418b4",
  "createdAt": "2017-12-16T22:21:31.871Z"
}
key
string

The created key.

createdAt
string

The date at which the key has been created.

Did you find this page helpful?