Java

Api keys

Overview

When creating your Algolia Account, you’ll notice there are 3 different API Keys:

  • Admin API Key - it provides full control of all your indices. The admin API key should always be kept secure; do NOT give it to anybody; do NOT use it in any application and always create a new key that will be more restricted

  • Search-Only API Key - It allows you to search on every indices.

  • Monitoring API Key - It allows you to access the Monitoring API

API keys are very sensitive part of your application and should follow our recommendations of best practices.

Other types of API keys

The Admin API Key and Search-Only API Key both have really large scope and sometimes you want to give a key to someone that have restricted permissions, can it be an index, a rate limit, a validity limit, …

To address those use-cases we have two different type of keys:

  • Secured API Keys

When you need to restrict the scope of the Search Key, we recommend to use Secured API Key. You can generate them on the fly (without any call to the API) from the Search Only API Key or any search User Key using the Generate key method

  • User API Keys

If Secured API Keys does not meet your requirements, you can make use of User keys. Managing and especially creating those keys requires a call to the API.

We have several methods to manage them:

Generate key - generateSecuredApiKey

When you need to restrict the scope of the Search Key, we recommend to use Secured API Key. You can generate a Secured API Key from the Search Only API Key or any search User API Key

There is a few things to know about Secured API Keys

  • They always need to be generated on your backend using one of our API Client
  • You can generate them on the fly (without any call to the API)
  • They will not appear on the dashboard as they are generated without any call to the API
  • The key you use to generate it needs to become private and you should not use it in your frontend.
  • The generated secured API key will inherit any restriction from the search key it has been generated from

You can then use the key in your frontend code

var client = algoliasearch('YourApplicationID', 'YourPublicAPIKey');

var index = client.initIndex('indexName')

index.search('something', function(err, content) {
  if (err) {
    console.error(err);
    return;
  }

  console.log(content);
});

Filters

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

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

Warning:

If you set filters in the key groups:admin, and groups:press OR groups:visitors in the query parameters, this will be equivalent to groups:admin AND (groups:press OR groups:visitors)

Having one API Key per User

One of the usage of secured API keys, is to have allow users to see only part of an index, when this index contains the data of all users. In that case, you can tag all records with their associated user_id in order to add a user_id=42 filter when generating the Secured API Key to retrieve only what a user is tagged in.

Warning

If you’re generating Secured API Keys using the JavaScript client in 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.

Valid Until

You can set a Unix timestamp used to define the expiration date of the API key

# generate a public API key that is valid for 1 hour:
long validUntil = System.currentTimeMillis()/1000 + 3600
String publicKey = client.generateSecuredApiKey("YourSearchOnlyApiKey", new Query().setValidUntil(validUntil));

Index Restriction

You can restrict the key to a list of index names allowed for the secured API key

# 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));

Rate Limiting

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

User Rate Limiting

By default the 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.

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

Network restriction

For more protection against API key leaking and reuse you can restrict the key to be valid only from specific IPv4 networks

//Sync & Async version

String publicKey = client.generateSecuredApiKey("YourSearchOnlyApiKey", new Query().setRestrictSources("192.168.1.0/24"));

Did you find this page helpful?

We're always looking for advice to help improve our documentation! Please let us know what's working (or what's not!) - we're constantly iterating thanks to the feedback we receive.

Send us your suggestions!