Api clients / JavaScript / V3 / Methods

Add API Key | JavaScript API Client V3 (Deprecated)

Deprecated content
This documentation is for a deprecated version of JavaScript API client. Some features and settings may be missing or their usage may have changed. Refer to the documentation for the latest version of JavaScript API client for up-to-date information.
Required API Key: Admin
Method signature
client.addApiKey(array acl, {
  validity: integer,
  maxQueriesPerIPPerHour: integer,
  maxHitsPerQuery: integer,
  indexes: array,
  referers: array,
  queryParameters: string,
  description: string
}, callback);

About this method

Add a new API Key with specific permissions/restrictions.

Examples

Create API Key

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

// To make sure the key is added
$res->wait();

Create API Key with advanced restrictions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Creates a new index specific API key valid for 300 seconds
// with a rate limit of 100 calls per hour per IP and a maximum of 20 hits

$res = $client->addApiKey(['search'], [
  'indexes'                => ['dev_*'],
  'referers'               => ['algolia.com/*'],
  'queryParameters'        => 'ignorePlurals=false&restrictSources=192.168.1.0/24',
  'description'            => 'Limited search only API key for algolia.com',
  'validity'               => 300, // 300 seconds
  'maxQueriesPerIPPerHour' => 100,
  'maxHitsPerQuery'        => 20,
]);

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

Parameters

acl
type: list
default: no default
Required

Set of permissions associated with the key.

The possible ACLs are:

  • search: Allows search.
  • browse: Allows retrieval of all index contents via the browse method.
  • addObject: Allows adding and updating an object in the index, and to copy and move indices.
  • deleteObject: Allows deleting objects.
  • deleteIndex: Allows deleting index content.
  • settings: Allows read access to index settings.
  • editSettings: Allows write access to index settings.
  • analytics: Allows retrieval of analytics through the analytics API.
  • listIndexes: Allows listing all accessible indices.
  • logs: Allows access to the logs.
  • seeUnretrievableAttributes: Allows access to see all attributes, even attributes set as unretrievableAttributes.
  • usage: Allows access to the usage API, which tells you about your application usage (record count, operations, etc.).
  • recommendation: Allows access to all features related to personalization.
validity
type: integer
default: no expiration date
Optional

A Unix timestamp used to define the expiration date of the API key.

maxHitsPerQuery
type: integer
default: 0 (unlimited)
Optional

Specify the maximum number of hits this API key can retrieve in one call. This parameter can be used to protect you from attempts at retrieving your entire index contents by massively querying the index.

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

Specify the maximum number of API calls allowed from an IP address per hour. Each time an API call is performed with this key, a check is performed. If the IP at the source of the call did more than this number of calls in the last hour, a 429 code is returned.

This parameter can be used to protect you from attempts at retrieving your entire index contents by massively querying the index.

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 referers)
Optional

Specify the list of referers. You can target all referers starting with a prefix, ending with a suffix using the ‘*’ character. For example, “https://algolia.com/*” matches all referers starting with “https://algolia.com/” and “*.algolia.com” matches all referers ending with “.algolia.com”. If you want to allow the domain algolia.com you can use “*algolia.com/*”.

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&ignorePlurals=false&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.

Response

In this section we document the JSON response returned by the API. Each language will encapsulate this response inside objects specific to the language and/or the implementation. So the actual type in your language might differ from what is documented.

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?