Api clients / Ruby / V1 / Methods

Create Secured API Key | Ruby API Client V1 (Deprecated)

Deprecated content
This documentation is for a deprecated version of Ruby API client . Some features and settings may be missing or their usage may have changed. Refer to the documentation for the latest version of Ruby API client for up-to-date information.
Required API Key: no ACL required
Method signature
Algolia.generate_secured_api_key(apiKey, {
  'filters': string,
  'validUntil': integer,
  'restrictIndices': array,
  'restrictSources': string,
  'userToken': string
  # any searchParameter
})

About this method

Generate a secured API key without any call to our servers.

When you need to restrict the scope of an API key, you should use secured API keys. You can only generate a secured API key from your search-only API keys: you can’t use Admin API keys, or other secured API keys.

You shouldn’t generate secured API keys from your frontend. If you do, users can modify the code and remove restrictions, which can expose hidden, sensitive data.

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

Keep in mind that the more limitations you set, the longer the key. You might face network limitations with a key longer than 500 characters, so consider this when adding restrictions.

If you want to rate-limit a secured API key, the key that you used to generate it must also be rate-limited. You can create a rate-limited key via the dashboard, or using either the Add API Key or Update API Key methods of an API client.

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 = \Algolia\AlgoliaSearch\SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    '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 = \Algolia\AlgoliaSearch\SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    '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 = \Algolia\AlgoliaSearch\SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    '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 = \Algolia\AlgoliaSearch\SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    '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
// The rate limit will be based on the passed user token

$public_key = \Algolia\AlgoliaSearch\SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'userToken' => 'user_42'
  ]
);

Parameters

apiKey
type: string
Required

The API key that your new secured API key inherits restrictions from.

filters
type: string
default: ""
Optional

Filters that apply to every search made with the secured API key. You can add extra filters at search time with the filters query parameter.

For example, if you set the filter group:admin on your generated API key, and you add groups:press OR groups:visitors with the filters query parameter, your final search filter is equivalent to groups:admin AND (groups:press OR groups:visitors).

validUntil
type: integer
default: no expiration date
Optional

A Unix timestamp used to set 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 can be useful when you want impose a rate limit on specific users. By default, we set rate limits based on the IP address. This can become an issue when several users search from the same IP address. To avoid this, you can set a unique userToken for each user when generating their API key. This lets you restrict each user to 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 applied at query time.

If you specify any of the following parameters in both the API key (A) and in your search (B), they are combined (A AND B):

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

The generated API key.

Did you find this page helpful?