API Reference / API Methods / API keys / Update API Key

Feb. 26, 2019

Update API Key

Required API Key: Admin

Method signature

$client->updateApiKey(string apiKey)

$client->updateApiKey(string apiKey, [
  // All the following parameters are optional
  'acl'                     => array,
  'validity'                => integer,
  'maxQueriesPerIPPerHour'  => integer,
  'maxHitsPerQuery'         => integer,
  'indexes'                 => array,
  'referers'                => array,
  'queryParameters'         => string,
  'description'             => string,
])

Algolia.update_api_key(
  String apiKey,
  {
    acl: Array,
    validity: Integer,
    maxQueriesPerIPPerHour: Integer,
    maxHitsPerQuery: Integer,
    indexes: Array,
    referers: Array,
    queryParameters: String,
    description: String
  }
)

client.updateApiKey(string apiKey, array acl, {
  validity: integer,
  maxQueriesPerIPPerHour: integer,
  maxHitsPerQuery: integer,
  indexes: array,
  referers: array,
  queryParameters: string,
  description: string
}, callback);

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

This method is not available in mobile API clients
as it is useful only for backend implementations.

If you want to use a secured API key in a mobile use case,
you should generate the secured API key from your backend with
one of our backend API clients.

suspend fun ClientSearch.updateAPIKey(
    apiKey: APIKey,
    params: APIKeyParams,
    requestOptions: RequestOptions? = null
): RevisionAPIKey

This method is not available in mobile API clients
as it is useful only for backend implementations.

If you want to use a secured API key in a mobile use case,
you should generate the secured API key from your backend with
one of our backend API clients.

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

res = index.UpdateApiKey(String apiKey, params);

client.updateApiKey(
  new ApiKey()
    .setValue(String 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.UpdateAPIKey(
  string apiKey,
  []string acl,
  []interface{}{
    "validity": int,
    "maxQueriesPerIPPerHour": int,
    "maxHitsPerQuery": int,
    "indexes": []string,
    "referers": []string,
    "queryParameters": string,
    "description": string
  }
)

update key apiKey with ApiKey(
  acl = Some(List<String>),
  maxHitsPerQuery = Some(int),
  maxQueriesPerIPPerHour = Some(int),
  validity = Some(int),
  indexes = Some(List<String>),
  referers = Some(List<String>),
  queryParameters = Some(String),
  description = Some(String)
)

See code examples

About this method

Update the permissions of an existing API Key.

Examples

Update the permissions of an existing key

Copy

// Update an existing API key that is valid for 300 seconds
$res = $client->updateApiKey('myAPIKey', [
  'acl' => ['search']
  'validity' => 300
]);

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

// Update an existing 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 = $index->updateApiKey('myAPIKey', [
  'acl' => ['search'],
  'validity' => 300,
  'maxQueriesPerIPPerHour' => 100,
  'maxHitsPerQuery' => 20
]);

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

# Update an existing API key that is valid for 300 seconds
res = Algolia.update_api_key('myAPIKey', ['search'], 300)
puts res['key']
# Update an existing 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'
res = index.update_api_key('myAPIKey', ['search'], 300, 100, 20, ['my_index1', 'my_index2'])
puts res['key']

// Update an existing API key that is valid for 300 seconds
client.updateApiKey(
  'myAPIKey',
  ['search'], {
    validity: 300
  }, (err, content) => {
    console.log(`Key:${content.key}`);
  }
);

// Update an 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
index.updateApiKey(
  'myAPIKey',
  ['search'], {
    validity: 300,
    maxQueriesPerIPPerHour: 100,
    maxHitsPerQuery: 20
  }, (err, content) => {
    if (err) throw err;

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

# Update an existing API key that is valid for 300 seconds
res = client.update_api_key('myAPIKey', {
    'validity': 300,
})

print('key=%s' % res['key'])

# Update an existing 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.update_api_key('myAPIKey', {
    'validity': 300,
    'maxQueriesPerIPPerHour': 100,
    'maxHitsPerQuery': 20,
})

print('key=%s' % res['key'])

// Update an existing API key that is valid for 300 seconds
ApiKey apiKeyToUpdate = new ApiKey
{
    Value = "myAPIKey",
    MaxHitsPerQuery = 0,
    MaxQueriesPerIPPerHour = 0,
    Validity = 300
};

var res = client.UpdateApiKey(apiKeyToUpdate);

// Asynchronous
var res = await client.UpdateApiKeyAsync(apiKeyToUpdate);

// Update an existing 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 apiKeyToUpdate = new ApiKey
{
    Value = "myAPIKey",
    Acl = new List<string> { "search" },
    Indexes = new List<string> { "dev_*" },
    MaxHitsPerQuery = 20,
    MaxQueriesPerIPPerHour = 100,
    Validity = 300
};

var res = index.UpdateApiKey(apiKeyToUpdate);

// Asynchronous
var res = await index.UpdateApiKeyAsync(apiKeyToUpdate);

// Creates a new API key that is valid for 300 seconds

ApiKey apiKey = new ApiKey()
    .setValue("myApiKey")
    .setAcl(Collections.singletonList("search"))
    .setValidity(300);

client.updateApiKey(apiKey);

// Async 
client.updateApiKeyAsync(apiKey);

// Update a 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 apiKey = new ApiKey()
    .setValue("myApiKey")
    .setAcl(Arrays.asList("search"))
    .setValidity(300L)
    .setMaxQueriesPerIPPerHour(200)
    .setMaxHitsPerQuery(20);

client.updateApiKey(apiKey);

// Async
client.updateApiKeyAsync(apiKey);

// Update an existing 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 := []interface{}{
  "acl":                    []string{"search"},
  "indexes":                []string{"myIndex"},
  "validity":               300,
  "maxQueriesPerIPPerHour": 100,
  "maxHitsPerQuery":        20,
}

res, err := client.UpdateAPIKey("f420238212c54dcfad07ea0aa6d5c45f", params)
fmt.Println(res.Key)

// Creates a new API key that is valid for 300 seconds
client.execute {
  update key "myAPIKey" `with` ApiKey(
      acl = Some(Seq(Acl.search)),
      maxHitsPerQuery = Some(0)),
      maxQueriesPerIPPerHour = Some(0),
      validity = Some(300)
  )
}

// Update a index specific API key valid for 300 seconds,
// with a rate limit of 100 calls per hour per IP and a

val apiKey = ApiKey(
  acl = Some(Seq(Acl.search)),
  maxHitsPerQuery = Some(100)),
  maxQueriesPerIPPerHour = Some(100),
  validity = Some(300)
)

client.execute {
  update key "myAPIKey" `with` apiKey from "myIndex"
}

// Update an existing 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
val apiKey = APIKeyParams(
    ACLs = listOf(ACL.Search),
    indices = listOf(IndexName("dev_*")),
    maxHitsPerQuery = 20,
    maxQueriesPerIPPerHour = 100,
    validity = 300
)

client.updateAPIKey(APIKey("myAPIKey"), apiKey)

Parameters

`apiKey`	type: string default: no default Required API Key to update
`acl`	type: list default: no default Optional Set of permissions associated to the key. The possible acls are: `search`: Allows search. `browse`: Allows retrieval of all index contents via the browse API. `addObject`: Allows adding/updating an object in the index. (Copying/moving indices are also allowed with this permission.) `deleteObject`: Allows deleting an existing object. `deleteIndex`: Allows deleting index content. `settings`: allows getting index settings. `editSettings`: Allows changing index settings. `analytics`: Allows retrieval of analytics through the analytics API. `listIndexes`: Allows listing all accessible indices. `logs`: Allows getting the logs. `seeUnretrievableAttributes`: Disables the unretrievableAttributes feature for all operations returning records.
`validity`	type: list default: no expiration date Optional A Unix timestamp used to define the expiration date of the API key.
`maxHitsPerQuery`	type: list 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: list 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: key value mapping 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”
`description`	type: string default: "" Optional Specify a description to describe where the key is used.

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",
  "updatedAt": "2017-12-16T22:21:31.871Z"
}

`key`	string The updated key.
`updatedAt`	string The date at which the key was updated.

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

iOS

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

iOS InstantSearch

Android InstantSearch

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Magento 1

Magento 2

WordPress

Shopify

Update API Key

About this method

Examples

Update the permissions of an existing key

Parameters

Response

JSON format

Did you find this page helpful?

On this page