Add API Key | JavaScript API Client V3 (Deprecated)

This version of the JavaScript API client has been deprecated in favor of the latest version of the JavaScript API client.

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);

See code examples

About this method

Add a new API Key with specific permissions/restrictions.

Examples

Create API Key

Copy

Copy
// 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();

Copy
// Creates a new API key that can only perform search actions
client.addApiKey(['search'], (err, content) => {
  if (err) throw err;

  console.log(`Key:${content['key']}`);
});

Copy
// Creates a new API key that can only perform search actions
var res = client.AddApiKey(new ApiKey
{
  Acl = new List<string> { "search" }
});

// To make sure the key is added
res.wait();

// Asynchronous
var res = await client.AddApiKeyAsync(new ApiKey
{
  Acl = new List<string> { "search" }
});

// To make sure the key is added
res.wait();

Copy
// Creates a new API key that can only perform search actions
ApiKey apiKey = new ApiKey().setAcl(Collections.singletonList("search")));

// Sync version
AddApiKeyResponse res = client.addApiKey(apiKey);

// To make sure the key is added
res.waiTask();

// Async version
client.addApiKeyAsync(apiKey);

Copy
// 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
acl := []string{"search"}
params := []interface{}{
  "validity":               300,
  "maxQueriesPerIPPerHour": 100,
  "maxHitsPerQuery":        20,
}

res, err := index.AddAPIKey(acl, params)
fmt.Println(res.Key)

Create API Key with advanced restrictions

Copy

Copy
// 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";

Copy
# Creates a new index specific API key:
#  - valid for 300 seconds
#  - rate limit of 100 calls per hour per IP
#  - maximum of 20 hits
#  - valid on 'my_index1' and 'my_index2'

params = {
  acl: ['search'],
  validity: 300,
  maxQueriesPerIPPerHour: 100,
  maxHitsPerQuery: 20,
  indexes: ['my_index1', 'my_index2'],
  referers: ['algolia.com/*'],
  queryParameters: 'ignorePlurals=false&restrictSources=192.168.1.0/24',
  description: 'Limited search only API key for algolia.com'
}

res = client.add_api_key(params)
puts res['key']

Copy
client.addApiKey(['search'], {
  validity: 300,
  maxQueriesPerIPPerHour: 100,
  maxHitsPerQuery: 20,
  indexes: ['dev_*'],
  referers: ['algolia.com/*'],
  queryParameters: 'ignorePlurals=false&restrictSources=192.168.1.0/24',
  description: 'Limited search only API key for algolia.com'
}, (err, content) => {
  if (err) throw err;

  console.log(`Key:${content['key']}`);
});

Copy
# 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

params = {
    'acl': ['search'],
    'validity': 300,
    'maxQueriesPerIPPerHour': 100,
    'maxHitsPerQuery': 20,
    'indexes': ['dev_*'],
    'referers': ['algolia.com/*'],
    'queryParameters': 'ignorePlurals=false&restrictSources=192.168.1.0/24',
    'description': 'Limited search only API key for algolia.com'
}

res = client.add_api_key(['search'], params)
print(res["key"])

Copy
// 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

ApiKey param = new ApiKey
{
    Acl = new List<string> { "search" },
    Description = "Limited search only API key for algolia.com",
    Indexes = new List<string> { "dev_*" },
    MaxHitsPerQuery = 20,
    MaxQueriesPerIPPerHour = 100,
    QueryParameters = "ignorePlurals=false&restrictSources=192.168.1.0/24",
    Referers = new List<string> { "algolia.com/*" },
    Validity = 300,
};

var res = index.AddApiKey(param);

// Asynchronous
var res = await index.AddApiKeyAsync(param);

Copy
// Creates a new API key that is valid for 300 seconds
ApiKey apiKey = new ApiKey()
  .setAcl(Collections.singletonList("search"))
  .setMaxHitsPerQuery(20)
  .setMaxQueriesPerIPPerHour(100)
  .setValidity(300L)
  .setIndexes(Collections.singletonList("myIndex"))
  .setReferers(Collections.singletonList("algolia.com/*"))
  .setQueryParameters("ignorePlurals=false&restrictSources=192.168.1.0/24")
  .setDescription("Limited search only API key for algolia.com");

// Sync version
AddApiKeyResponse res = client.addApiKey(apiKey);

// To make sure the key is added
res.waiTask();

// Async version
client.addApiKeyAsync(apiKey);

Copy
// 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
acl := []string{"search"}
params := []interface{}{
  "indexes":                "myIndex",
  "validity":               300,
  "maxQueriesPerIPPerHour": 100,
  "maxHitsPerQuery":        20,
  "queryParameters":       "ignorePlurals=false&restrictSources=192.168.1.0/24",
}

res, err := client.AddAPIKey(acl, params)
fmt.Println(res.Key)

Copy
// Creates a new API key that is valid for 300 seconds
val apiKey = ApiKey(
  acl = Some(Seq(Acl.search)),
  maxHitsPerQuery = Some(20)),
  maxQueriesPerIPPerHour = Some(100),
  validity = Some(300),
  indexes = Some(Seq("myIndex")),
  referers = Some(Seq("algolia.com/*")),
  queryParameters = Some(Seq("ignorePlurals=false&restrictSources=192.168.1.0/24")),
  description = Some("Limited search only API key for algolia.com")
)

client.execute {
  add key apiKey
}

Copy
val params = APIKeyParams(
    ACLs = listOf(ACL.Search),
    description = "Limited search only API key for algolia.com",
    indices = listOf(IndexName("dev_*")),
    maxHitsPerQuery = 20,
    maxQueriesPerIPPerHour = 100,
    query = Query(
        typoTolerance = TypoTolerance.Strict,
        ignorePlurals = IgnorePlurals.False
    ),
    referers = listOf("algolia.com/*"),
    validity = 300
)
client.apply {
    val response = client.addAPIKey(params, restrictSources = "169.254.0.0/16").wait()

    client.deleteAPIKey(response.apiKey)
}

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

Copy

        {
  "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?