Add API Key | Ruby API Client V1 (Deprecated)
client.add_api_key( { acl: Array, validity: Integer, maxQueriesPerIPPerHour: Integer, maxHitsPerQuery: Integer, indexes: Array, referers: Array, queryParameters: String, description: String } )
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:
|
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 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, This also works with |
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: 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., 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: |
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 request options to send along with the request. |
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. |