API client / Methods / API keys

Jun. 08, 2023

Add API key

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,
])

client.add_api_key(
  Array acl,
  Hash opts = {
    # All the following parameters are optional
    validity: Integer,
    maxQueriesPerIPPerHour: Integer,
    maxHitsPerQuery: Integer,
    indexes: Array,
    referers: Array,
    queryParameters: String,
    description: String
    # any requestOptions
  }
)

client.addApiKey(array acl, {
  // All the following parameters are optional
  validity: integer,
  maxQueriesPerIPPerHour: integer,
  maxHitsPerQuery: integer,
  indexes: array,
  referers: array,
  queryParameters: string,
  description: string
})

res = client.add_api_key(list acl, {
    'validity': int,
    'maxQueriesPerIPPerHour': int,
    'maxHitsPerQuery': int,
    'indexes': list,
    'referers': list,
    'queryParameters': str,
    'description': str
  }
)

client.addAPIKey(
  with parameters: APIKeyParameters,
  requestOptions: RequestOptions? = nil,
  completion: Result<APIKeyCreation> -> Void
)

struct APIKeyParameters {
    var ACLs: [ACL],
    var validity: TimeInterval?,
    var maxHitsPerQuery: Int?,
    var maxQueriesPerIPPerHour: Int?,
    var indices: [IndexName]?,
    var referers: [String]?,
    var query: Query?, // add any queryParameters
    var description: String?,
    var restrictSources: String?,
}

suspend fun ClientSearch.addAPIKey(
    params: APIKeyParams,
    restrictSources: String? = null,
    requestOptions: RequestOptions? = null
): CreationAPIKey

data class APIKeyParams(
    val ACLs: List<ACL>? = null,
    val indices: List<IndexName>? = null,
    val description: String? = null,
    val maxHitsPerQuery: Int? = null,
    val maxQueriesPerIPPerHour: Int? = null,
    val validity: Long? = null,
    val query: Query? = null,
    val referers: List<String>? = null
)

ApiKey params = new ApiKey
{
    Acl = List<String>,

    // All the following parameters are optional
    Description = String,
    Indexes = List<String>,
    MaxHitsPerQuery = String,
    MaxQueriesPerIPPerHour = String,
    QueryParameters = String,
    Referers = List<String>,
    Validity = long
};

var res = index.AddApiKey(param);

client.addApiKey(
  new ApiKey()
  .setAcl(List<String> acl)
  .setMaxHitsPerQuery(int maxHitsPerQuery)
  .setMaxQueriesPerIPPerHour(int maxQueriesPerIPPerHour)
  .setValidity(int validity)
  .setIndexes(List<String> indexes)
  .setReferers(List<String> referers)
  .setQueryParameters(String queryParameters)
  .setDescription(String description)
);

client.AddAPIKey(
  key: Key,
  options: __[]interface{}
)

add key ApiKey(
  acl = Some(acl),
  maxHitsPerQuery = Some(maxHitsPerQuery),
  maxQueriesPerIPPerHour = Some(maxQueriesPerIPPerHour),
  validity = Some(validity),
  indexes = Some(indexes),
  referers = Some(referers),
  queryParameters = Some(queryParameters),
  description = Some(description)
)

See code examples

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.

About this method

Add a new API Key with specific permissions and restrictions.

Examples

Read the Algolia CLI documentation for more information.

Create new API key

Copy

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

1
2
3
4
5
6
7
8
// Create a new API key that can only perform search actions
let params = APIKeyParameters(ACLs: [.search])

client.addAPIKey(with: params) { result in
  if case .success(let apiKeyCreation) = result {
    print(apiKeyCreation.key)
  }
}

1
2
3
4
5
6
7
// Create a new API key that can only perform search actions
val params = APIKeyParams(
    ACLs = listOf(ACL.Search)
)
client.apply {
    val response = addAPIKey(params)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Create a new API key that can only perform search actions
var res = client.AddApiKey(new ApiKey
{
  Acl = new List<string> { "search" }
});

// Wait until the key is added
res.wait();

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

1
2
3
4
5
6
7
8
// Create a new API key that can only perform search actions
ApiKey apiKey = new ApiKey().setAcl(Collections.singletonList("search")));

// Synchronous
AddApiKeyResponse res = client.addApiKey(apiKey);

// Asynchronous
client.addApiKeyAsync(apiKey);

1
2
3
4
5
6
7
8
9
10
11
12
// Create a new API key that can only perform search actions
key := search.Key {
  ACL: []string{"search"},
}

res, err := client.AddAPIKey(key)

if err != nil {
  panic(err)
}

fmt.Println(res.Key)

Create new API Key with specific restrictions

Copy

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Create a new restricted search-only API key
opts = {
  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,
}

acl = ['search']
res = client.add_api_key(acl, opts)
puts res.raw_response[:key]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Create a new restricted search-only API key
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,
}).then(({ key }) => {
  console.log(key);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Create a new restricted search-only API key
params = {
    '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,
}

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

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

client.addAPIKey(with: params) { result in
  if case .success(let response) = result {
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Create a new restricted search-only API key
val params = APIKeyParams(
    ACLs = listOf(ACL.Search),
    description = "Restricted search only API key for algolia.com",
    // Allow searching only in indices with names starting with `dev_*`
    indices = listOf(IndexName("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
    query = Query(
        ignorePlurals = IgnorePlurals.False
    ),
    // Only allow searches from the `algolia.com` domain
    referers = listOf("algolia.com/*"),
    // This API key expires after 300 seconds (5 minutes)
    validity = 300
)
client.apply {
    val response = client.addAPIKey(params).wait()

    client.deleteAPIKey(response.apiKey)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Create a new restricted search-only API key
ApiKey param = new ApiKey
{
    Acl = new List<string> { "search" },
    Description = "Restricted search-only API key for algolia.com",
    // Allow searching only in indices with names starting with `dev_*`
    Indexes = new List<string> { "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 = new List<string> { "algolia.com/*" },
    // This API key expires after 300 seconds (5 minutes)
    Validity = 300,
};

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Create a new restricted search-only API key
ApiKey apiKey = new ApiKey()
  // Allow only search
  .setAcl(Collections.singletonList("search"))
  .setDescription("Restricted search-only API key for algolia.com");
  // Allow searching only in indices with names starting with `dev_*`
  .setIndexes(Collections.singletonList("dev_*"))
  // Retrieve up to 20 results per search query
  .setMaxHitsPerQuery(20)
  // Rate-limit to 100 requests per hour per IP address
  .setMaxQueriesPerIPPerHour(100)
  // Add fixed query parameters to every search request
  .setQueryParameters("ignorePlurals=false")
  // Only allow searches from the `algolia.com` domain
  .setReferers(Collections.singletonList("algolia.com/*"))
  // This API key expires after 300 seconds (5 minutes)
  .setValidity(300L)

AddApiKeyResponse res = client.addApiKey(apiKey);
// Asynchronous:
// client.addApiKeyAsync(apiKey);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Create a new restricted search-only API key
key := search.Key {
  ACL: []string{"search"},
  Description: "Restricted search-only API key for algolia.com",
  // Allow searching only in indices with names starting with `dev_*`
  Indexes: []string{"dev_*"},
  // Retrieve up to 20 results per search query
  MaxHitsPerQuery: 20,
  // Rate-limit to 100 requests per hour per IP address
  MaxQueriesPerIPPerHour: 100,
  // Only allow searches from the `algolia.com` domain
  Referers: []string{"algolia.com/*"}
  // This API key expires after 300 seconds (5 minutes)
  Validity: 300
}
// Add fixed query parameters to every search request
// add import: `github.com/algolia/algoliasearch-client-go/v3/algolia/opt`
key.SetQueryParameters(opt.IgnorePlurals(false))

res, err := client.AddAPIKey(key)

if err != nil {
  panic(err)
)

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

client.execute {
  add key apiKey
}

1
2
3
4
5
6
algolia apikey create \
               --acl "search" \
               --description "Restricted search-only API key for algolia.com" \
               --indices "dev_*" \
               --referers "algolia.com/*" \
               --validity 300

Parameters

Parameter	Description
`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 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. Each API client encapsulates this response inside objects specific to the programming language, so that the actual response might be different. You can view the response by using the getLogs method. Don’t rely on the order of attributes in the response, as JSON doesn’t guarantee the ordering of keys in objects.

JSON format

Copy

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

        

Field	Description
`key`	string The created key.
`createdAt`	string The date at which the key has been created.

Did you find this page helpful?