Api clients / JavaScript / V3 / Methods

Jan. 09, 2023

Create Secured 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: no ACL required

Method signature

client.generateSecuredApiKey(string apiKey, {
  filters: string,
  validUntil: integer,
  restrictIndices: array,
  restrictSources: string,
  userToken: string
  // + any searchParameter
})

See code examples

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

Copy

Copy
// 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\AlgoliaSearch\SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'filters' => '_tags:user_42'
  ]
);

Copy
# 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' })

Copy
// 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
const publicKey = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    filters: '_tags:user_42'
  }
);

Copy
# generate a public API key for user 42. Here, records are tagged with:
#  - 'user_XXXX' if they are visible by user XXXX
from algoliasearch.search_client import SearchClient

public_key = SearchClient.generate_secured_api_key(
    'YourSearchOnlyApiKey',
    {'filters': '_tags:user_42'}
)

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

    SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
  {
      Query = new Query { Filters = "_tags:user_42" },
  };

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

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

SecuredApiKeyRestriction restriction =
new SecuredApiKeyRestriction()
    .setQuery(new Query().setFilters("_tags:user_42"));

String publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  restriction
);

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

Copy
val parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
val restriction = SecuredAPIKeyRestriction(
    query = Query(filters = "_tags:user_42")
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

Generate a secured API key with an expiration date

Copy

Copy
// generate a public API key that is valid for 1 hour:
$validUntil = time() + 3600;
$public_key = \Algolia\AlgoliaSearch\SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'validUntil' => $validUntil
  ]
);

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

Copy
// Only works in Node

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

Copy
import time

from algoliasearch.search_client import SearchClient

# generate a public API key that is valid for 1 hour:
valid_until = int(time.time())  + 3600
public_key = SearchClient.generate_secured_api_key(
    'YourSearchOnlyApiKey',
    {'validUntil': valid_until}
)

Copy
# generate a public API key that is valid for 1 hour:
var date = DateTime.UtcNow.AddHours(1);
SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
    ValidUntil = ((DateTimeOffset)date).ToUnixTimeSeconds()
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

Copy
// generate a public API key that is valid for 1 hour:
int validUntil = (int) (System.currentTimeMillis() / 1000 + 3600);

SecuredApiKeyRestriction restriction =
new SecuredApiKeyRestriction()
    .setQuery(new Query().setValidUntil(validUntil));

String publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  restriction
);

Copy
val validUntil = System.currentTimeMillis()/1000 + 3600
val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(validUntil = Some(validUntil)
)

Copy
val parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
val dayInMilliseconds = 60 * 60 * 24 * 1000
val restriction = SecuredAPIKeyRestriction(
    validUntil = Time.getCurrentTimeMillis() + dayInMilliseconds
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

Generate a secured API key with indices restriction

Copy

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

$public_key = \Algolia\AlgoliaSearch\SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'restrictIndices' => 'index1,index2'
  ]
);

Copy
# generate a public API key that is restricted to 'index1' and 'index2':
public_key = Algolia.generate_secured_api_key('YourSearchOnlyApiKey', { restrictIndices: 'index1,index2' })

Copy
// Only works in Node

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

const publicKey = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    restrictIndices: 'index1,index2'
  }
);

Copy
from algoliasearch.search_client import SearchClient

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

Copy
# generate a public API key that is restricted to "index1" and "index2":
SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
    RestrictIndices = new List<string> { "index1", "index2" }
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

Copy
// generate a public API key that is restricted to "index1" and "index2":
SecuredApiKeyRestriction restriction =
    new SecuredApiKeyRestriction()
        .setRestrictIndices(Arrays.asList("index1", "index2"))

String publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  restriction
);

Copy
// Generate a public API key that is restricted to `index1` and `index2`

key, err := search.GenerateSecuredAPIKey(
    "YourSearchOnlyApiKey",
    opt.RestrictIndices("index1", "index2"),
)

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

Copy
val parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
val restriction = SecuredAPIKeyRestriction(
    restrictIndices = listOf(
        IndexName("index1"),
        IndexName("index2")
    )
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

Generate a secured API key with a network restriction

Copy

Copy
# generate a public API key that is restricted to '192.168.1.0/24':
$public_key = \Algolia\AlgoliaSearch\SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'restrictSources' => '192.168.1.0/24'
  ]
);

Copy
# 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' })

Copy
// Only works in Node
// generate a public API key that is restricted to '192.168.1.0/24':
const publicKey = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    restrictSources: '192.168.1.0/24'
  }
);

Copy
from algoliasearch.search_client import SearchClient

# generate a public API key that is restricted to '192.168.1.0/24':
public_key = SearchClient.generate_secured_api_key(
    'YourSearchOnlyApiKey',
    {'restrictSources': '192.168.1.0/24'}
)

Copy
SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
    RestrictSources = "192.168.1.0/24",
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

Copy
// Sync & Async version

SecuredApiKeyRestriction restriction =
new SecuredApiKeyRestriction()
    .setRestrictSources(Collections.singletonList("192.168.1.0/24"));

String publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  restriction
);

Copy
// Generate a public API key that is restricted to `192.168.1.0/24`

key, err := search.GenerateSecuredAPIKey(
    "YourSearchOnlyApiKey",
    opt.RestrictSources("192.168.1.0/24"),
)

Copy
val parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
val restriction = SecuredAPIKeyRestriction(
    query = Query(filters = "_tags:user_42"),
    userToken = UserToken("42")
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

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

Copy

Copy
// 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\AlgoliaSearch\SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'filters' => 'user_42',
    'userToken' => 'user_42'
  ]
);

Copy
# 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' })

Copy
// 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
const publicKey = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    filters: '_tags:user_42',
    userToken: 'user_42'
  }
);

Copy
from algoliasearch.search_client import SearchClient

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

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

SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
    Query = new Query { Filters = "_tags:user_42" },
    UserToken = "42"
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

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

SecuredApiKeyRestriction restriction =
new SecuredApiKeyRestriction()
    .setQuery(new Query().setFilters("_tags:user_42").setUserToken("42"));

String publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  restriction
);

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

key, err := search.GenerateSecuredAPIKey(
    "YourSearchOnlyApiKey",
    opt.Filters("_tags:user_42"),
    opt.UserToken("user_42"),
)

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

Copy
val parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
val restriction = SecuredAPIKeyRestriction(
    restrictSources = listOf("192.168.1.0/24")
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

Parameters

`apiKey`	type: string Required API key to generate from.
`filters`	type: string default: "" Optional 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 default: no expiration date Optional A Unix timestamp used to define the expiration date of the API key.
`restrictIndices`	type: list default: all indices Optional List of index names that can be queried.
`restrictSources`	type: string default: no restricted sources Optional 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`).
`userToken`	type: string default: users' IP address Optional Specify a unique 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. This allows you to restrict a single user to performing a maximum number of API calls per hour, even if they share their IP with another user.
`searchParameter`	type: key value mapping default: none Optional 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: filters facetFilters optionalFilters numericFilters

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

1
"YTgyMzMwOTkzMjA2Mzk5OWUxNjhjYmIwMGZkNGFmMzk2NDU3ZjMyYTg1NThiZjgxNDRiOTk3ZGE3NDU4YTA3ZWZpbHRlcnM9X3RhZ3MlM0F1c2VyXzQy"


          api_key

string

Generated API Key.

Did you find this page helpful?

Create Secured API Key | JavaScript API Client V3 (Deprecated)

About this method

Examples

Generate a secured API key containing a filter

Generate a secured API key with an expiration date

Generate a secured API key with indices restriction

Generate a secured API key with a network restriction

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

Parameters

Response

JSON format

On this page