API Reference / API Methods / API keys / Create secured API Key
Feb. 26, 2019

Create secured API Key

Required API Key: no ACL required
Method signature
Client::generateSecuredApiKey(string apiKey, [
  'filters'           => string,
  'validUntil'        => integer,
  'restrictIndices'   => array,
  'restrictSources'   => string,
  'userToken'         => string
  // + 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

1
2
3
4
5
6
7
8
// 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 secured API key with an expiration date

1
2
3
4
5
6
7
8
// generate a public API key that is valid for 1 hour:
$validUntil = time() + 3600;
$public_key = \AlgoliaSearch\Client::generateSecuredApiKey(
  'SearchApiKey',
  [
    'validUntil' => $validUntil
  ]
);

Generate a secured API key with indices restriction

1
2
3
4
5
6
7
8
// generate a public API key that is restricted to 'index1' and 'index2':

$public_key = \AlgoliaSearch\Client::generateSecuredApiKey(
  'SearchApiKey',
  [
    'restrictIndices' => 'index1,index2'
  ]
);

Generate a secured API key with a network restriction

1
2
3
4
5
6
7
# 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 secured API key with a rate limiting applied per user

1
2
3
4
5
6
7
8
9
10
// 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'
  ]
);

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 sources description
Optional

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

userToken
type: string
default: no sources description
Optional

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
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:

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

1
"YTgyMzMwOTkzMjA2Mzk5OWUxNjhjYmIwMGZkNGFmMzk2NDU3ZjMyYTg1NThiZjgxNDRiOTk3ZGE3NDU4YTA3ZWZpbHRlcnM9X3RhZ3MlM0F1c2VyXzQy"
api_key
string

Generated API Key.

Did you find this page helpful?