Create secured API Key

Required API Key: no ACL required
Method signature
Client::generateSecuredApiKey(apiKey,
[
  'filters'           => filters,
  'validUntil'        => validUntil,
  'restrictIndices'   => restrictIndices,
  'restrictSources'   => restrictSources,
  'userToken'         => userToken
  // + any searchParameter
])

Method signature
Algolia.generate_secured_api_key(apiKey, {
  'filters': filters,
  'validUntil': validUntil,
  'restrictIndices': restrictIndices,
  'restrictSources': restrictSources,
  'userToken': userToken
  # any searchParameter
})

Method signature
client.generateSecuredApiKey(apiKey, {
  filters: filters,
  validUntil: validUntil,
  restrictIndices: restrictIndices,
  restrictSources: restrictSources,
  userToken: userToken
  // + any searchParameter
})

Method signature
client.generate_secured_api_key(apiKey, {
  'filters': filters,
  'validUntil': validUntil,
  'restrictIndices': restrictIndices,
  'restrictSources': restrictSources,
  'userToken': userToken
  # any searchParameter
})

Method signature
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.

Method signature
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.

Method signature
client.GenerateSecuredApiKey(apiKey,
  new Query()
  .SetFilters(filters)
  .AddCustomParameter("validUntil", validUntil)
  .SetRestrictIndices(restrictIndices)
  .SetRestrictSources(restrictSources)
  .SetUserToken(userToken)
  // any searchParameter
)

Method signature
client.generateSecuredApiKey(apiKey,
  new Query()
  .setFilters(filters)
  .setValidUntil(validUntil)
  .setRestrictIndices(restrictIndices)
  .setRestrictSources(restrictSources)
  .setUserToken(userToken)
  // any searchParameter
)

Method signature
client.GenerateSecuredAPIKey(apiKey, algoliasearch.Map{
  "filters": filters,
  "validUntil": validUntil,
  "restrictIndices": restrictIndices,
  "restrictSources": restrictSources,
  "userToken": userToken,
  // any searchParameter
})

Method signature
client.generateSecuredApiKey(apiKey, Query(
  filters = Some(filters),
  validUntil = Some(validUntil),
  restrictIndices = Some(restrictIndices),
  restrictSources = Some(restrictSources),
  userToken = Some(userToken)
  // any searchParameter
))

About this method

Generate a virtual API Key without any call to the server.

When you need to restrict the scope of a API key, we recommend using the Secured API Key. You can generate a Secured API Key from any API key.

Learn more about secured API keys.

If you’re generating Secured API Keys using the JavaScript client on your frontend, it will result in a security breach since the user is able to modify the filters you’ve set by modifying the code from the browser.

You can define a number of restrictions (valid until, restrict indices, etc.).

If you want to rate-limit a secured API Key, the API key you generate from the secured api key needs to be rate-limited. You can do that via the dashboard or the API using the Add API Key or Update API Key method

Examples

Generate a secured API key containing a filter

<?php
// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX
$public_key = \AlgoliaSearch\Client::generateSecuredApiKey(
  'SearchApiKey',
  [
    'filters' => '_tags:user_42'
  ]
);
# generate a public API key for user 42. Here, records are tagged with:
#  - 'user_XXXX' if they are visible by user XXXX
public_key = Algolia.generate_secured_api_key('YourSearchOnlyApiKey', { filters: '_tags:user_42' })
// Only works in Node

// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX
var public_key = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    filters: '_tags:user_42'
  }
);
# generate a public API key for user 42. Here, records are tagged with:
#  - 'user_XXXX' if they are visible by user XXXX
public_key = client.generate_secured_api_key(
    'YourSearchOnlyApiKey',
    {'filters': '_tags:user_42'}
)
// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX

String publicKey = client.generateSecuredApiKey(
  "SearchOnlyApiKeyKeptPrivate",
  new Query().SetFilters("_tags:user_42")
);
// Sync & Async version

// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX
String publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  new Query()
    .setFilters("_tags:user_42")
);
params := algoliasearch.Map{
  "filters": "_tags:user_42",
}

key, err := algoliasearch.GenerateSecuredAPIKey("YourSearchOnlyApiKey", params)
// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX
val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(filters = Some("_tags:user_42"))
)

Generate a secured API key with an expiration date

<?php
// generate a public API key that is valid for 1 hour:
$validUntil = time() + 3600;
$public_key = \AlgoliaSearch\Client::generateSecuredApiKey(
  'SearchApiKey',
  [
    'validUntil' => $validUntil
  ]
);
# generate a public API key that is valid for 1 hour:
valid_until = Time.now.to_i + 3600
public_key = Algolia.generate_secured_api_key('YourSearchOnlyApiKey', { validUntil: valid_until })
// Only works in Node

// generate a public API key that is valid for 1 hour:
var valid_until = Math.floor(Date.now() / 1000) + 3600
var public_key = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    validUntil: valid_until
  }
);
import time

# generate a public API key that is valid for 1 hour:
valid_until = time.time()  + 3600
public_key = client.generate_secured_api_key(
    'YourSearchOnlyApiKey',
    {'validUntil': valid_until}
)
# generate a public API key that is valid for 1 hour:
string date = (
  DateTime.UtcNow.AddHours(1) - new DateTime(1970, 1, 1, 0, 0, 0, 0)
).TotalSeconds.ToString(CultureInfo.InvariantCulture);

var validUntil = Math.Round(
  Double.Parse(date, CultureInfo.InvariantCulture)
).ToString();

string publicKey = client.GenerateSecuredApiKey(
  "YourSearchOnlyApiKey",
  new Query().AddCustomParameter("validUntil", validUntil)
);
// generate a public API key that is valid for 1 hour:
int validUntil = (int) (System.currentTimeMillis() / 1000 + 3600);

String publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  new Query().setValidUntil(validUntil)
);
// Generate a public API key that is valid for 1 hour

valid_until := time.Now().Unix() + 3600

params := algoliasearch.Map{
  "validUntil": valid_until,
}

key, err := algoliasearch.GenerateSecuredAPIKey("YourSearchOnlyApiKey", params)
val validUntil = System.currentTimeMillis()/1000 + 3600
val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(validUntil = Some(validUntil)
)

Generate a secured API key with indices restriction

<?php
// generate a public API key that is restricted to 'index1' and 'index2':

$public_key = \AlgoliaSearch\Client::generateSecuredApiKey(
  'SearchApiKey',
  [
    'restrictIndices' => 'index1,index2'
  ]
);
# generate a public API key that is restricted to 'index1' and 'index2':
public_key = Algolia.generate_secured_api_key('YourSearchOnlyApiKey', { restrictIndices: 'index1,index2' })
// Only works in Node

// generate a public API key that is restricted to 'index1' and 'index2':

var public_key = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    restrictIndices: 'index1,index2'
  }
);
# generate a public API key that is restricted to 'index1' and 'index2':
public_key = client.generate_secured_api_key(
  'YourSearchOnlyApiKey',
  {'restrictIndices': 'index1,index2'}
)
# generate a public API key that is restricted to "index1" and "index2":

restrictIndices = new List<String>();

restrictIndices.Add("index1");
restrictIndices.Add("index2");

String publicKey = client.GenerateSecuredApiKey(
  "SearchOnlyApiKeyKeptPrivate",
  new Query().SetRestrictIndices(restrictIndices)
);
// generate a public API key that is restricted to "index1" and "index2":

List<String> restrictIndices = new ArrayList<>();
restrictIndices.add("index1");
restrictIndices.add("index2");

String publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  new Query().setRestrictIndices(restrictIndices)
);
// Generate a public API key that is restricted to `index1` and `index2`

params := algoliasearch.Map{
  "restrictIndices": "index1,index2",
}

key, err := algoliasearch.GenerateSecuredAPIKey("YourSearchOnlyApiKey", params)
// generate a public API key that is restricted to 'index1' and 'index2':
val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(restrictIndices = Some(Seq("index1", "index2"))
)

Generate a secured API key with a network restriction

<?php
# generate a public API key that is restricted to '192.168.1.0/24':
$public_key = \AlgoliaSearch\Client::generateSecuredApiKey(
  'SearchApiKey',
  [
    'restrictSources' => '192.168.1.0/24'
  ]
);
# generate a public API key that is restricted to '192.168.1.0/24':
public_key = Algolia.generate_secured_api_key('YourSearchOnlyApiKey', { restrictSources: '192.168.1.0/24' })
// Only works in Node
// generate a public API key that is restricted to '192.168.1.0/24':
var public_key = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    restrictSources: '192.168.1.0/24'
  }
);
# generate a public API key that is restricted to '192.168.1.0/24':
public_key = client.generate_secured_api_key(
    'YourSearchOnlyApiKey',
    {'restrictSources': '192.168.1.0/24'}
)
string publicKey = client.GenerateSecuredApiKey(
  "YourSearchOnlyApiKey",
  new Query().SetRestrictSources("192.168.1.0/24")
);
// Sync & Async version

String publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  new Query()
    .setRestrictSources("192.168.1.0/24")
);
// Generate a public API key that is restricted to `192.168.1.0/24`

params := algoliasearch.Map{
  "restrictSources": "192.168.1.0/24",
}

key, err := algoliasearch.GenerateSecuredAPIKey("YourSearchOnlyApiKey", params)
String publicKey = client.generateSecuredApiKey(
    "YourSearchOnlyApiKey",
    Query(restrictSources = Some("192.168.1.0/24"))
)

Generate a secured API key with a rate limiting applied per user

<?php
// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX

$public_key = $client->generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'filters' => 'user_42',
    'userToken' => 'user_42'
  ]
);
# generate a public API key for user 42. Here, records are tagged with:
#  - 'user_XXXX' if they are visible by user XXXX
public_key = Algolia.generate_secured_api_key('YourSearchOnlyApiKey', { filters: '_tags:user_42', userToken: 'user_42' })
// Only works in Node

// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX
var public_key = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    filters: '_tags:user_42',
    userToken: 'user_42'
  }
);
# generate a public API key for user 42. Here, records are tagged with:
#  - 'user_XXXX' if they are visible by user XXXX
public_key = client.generate_secured_api_key(
    'YourSearchOnlyApiKey',
    {'filters': '_tags:user_42', 'userToken': 'user_42'}
)
// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX

string publicKey = client.GenerateSecuredApiKey(
  "SearchOnlyApiKeyKeptPrivate",
  new Query().SetFilters("_tags:user_42").SetUserToken("42")
);
// Sync & Async version

// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX

String publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  new Query()
    .setFilters("_tags:user_42")
    .setUserToken("42")
);
params := algoliasearch.Map{
  "filters":   "_tags:user_42",
  "userToken": "user_42",
}

key, err := algoliasearch.GenerateSecuredAPIKey("YourSearchOnlyApiKey", params)
// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX
val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(filters = Some("_tags:user_42")), userToken = Some("42")
)

Parameters

apiKey
type: string
Required

API key to generate from.

filters
type: string
Optional
default: ""

Every filter set in the API key will always be applied. On top of that, filters can be applied in the query parameters.

If you set filters in the key groups:admin; and groups:press OR groups:visitors in the searchParameter parameter; this will be equivalent to groups:admin AND (groups:press OR groups:visitors).

validUntil
type: integer
Optional
default: no expiration date

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

restrictIndices
type: list
Optional
default: all indices

List of index names that can be queried.

restrictSources
type: string
Optional
default: no sources description

IPv4 network allowed to use the generated key. This is used for more protection against API key leaking and reuse.

userToken
type: string
Optional
default: no sources description

Specify a user identifier.

This is often used with rate limits. By default, rate limits will only use the IP. This can be an issue when several of your end users are using the same IP. To avoid that, you can set a userToken query parameter when generating the key. When set, a unique user will be identified by his IP + user_token instead of only by his IP. This allows you to restrict a single user to performing a maximum of N API calls per hour, even if he shares his IP with another user.

searchParameter
type: key value mapping
Optional
default: none

A mapping of search parameters that will be forced at query time.

If specified in both the query and the API key filters the following parameters will be combined with an AND:

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

"YTgyMzMwOTkzMjA2Mzk5OWUxNjhjYmIwMGZkNGFmMzk2NDU3ZjMyYTg1NThiZjgxNDRiOTk3ZGE3NDU4YTA3ZWZpbHRlcnM9X3RhZ3MlM0F1c2VyXzQy"
api_key
string

Generated API Key.

Php small white
PHP
Ruby small white
Ruby
Javascript small white
JavaScript
Python small white
Python
Swift small white
iOS
Android small white
Android
Csharp small white
C#
Java small white
Java
Go small white
Go
Scala small white
Scala
Php small white
PHP
Ruby small white
Ruby
Javascript small white
JavaScript
Python small white
Python
Swift small white
iOS
Android small white
Android
Csharp small white
C#
Java small white
Java
Go small white
Go
Scala small white
Scala