Api clients / Ruby / V1 / Methods

Jan. 09, 2023

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

This version of the Ruby API client has been deprecated in favor of the latest version of the Ruby API client.

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

See code examples

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

Copy

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'
  ]
);

1
2
3
# 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' })

1
2
3
4
5
6
7
8
9
10
11
12
// Only available on Node - CommonJS build

// 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'
  }
);

console.log(publicKey);

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
from algoliasearch.search_client import SearchClient

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

1
2
3
4
5
6
7
8
9
// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX

let parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
let restriction = SecuredAPIKeyRestriction()
  .set(\.query, to: Query()
    .set(\.filters, to: "_tags:user_42"))

let publicKey = client.generateSecuredApiKey(parentApiKey: parentAPIKey, with: restriction)

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

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

1
2
3
4
5
6
// 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"))
)

1
2
3
4
5
6
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

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

1
2
3
# 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 })

1
2
3
4
5
6
7
8
9
10
// Only available on Node - CommonJS build

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

1
2
3
4
5
6
7
8
9
10
import time

from algoliasearch.search_client import SearchClient

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

1
2
3
4
5
6
7
// generate a public API key that is valid for 1 hour:

let parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
let restriction = SecuredAPIKeyRestriction()
  .set(\.validUntil, to: Date().addingTimeInterval(.hour).timeIntervalSince1970)

let publicKey = client.generateSecuredApiKey(parentApiKey: parentAPIKey, with: restriction)

1
2
3
4
5
6
7
8
# 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);

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

1
2
3
4
5
val validUntil = System.currentTimeMillis()/1000 + 3600
val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(validUntil = Some(validUntil)
)

1
2
3
4
5
6
7
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

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'
  ]
);

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

1
2
3
4
5
6
7
8
9
10
// Only works in Node

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

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

1
2
3
4
5
6
7
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'}
)

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

let parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
let restriction = SecuredAPIKeyRestriction()
  .set(\.restrictIndices, to: ["index1", "index2"])

let publicKey = client.generateSecuredApiKey(parentApiKey: parentAPIKey, with: restriction)

1
2
3
4
5
6
7
# 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);

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

1
2
3
4
5
6
// Generate a public API key that is restricted to `index1` and `index2`

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

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

1
2
3
4
5
6
7
8
9
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

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'
  ]
);

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

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

1
2
3
4
5
6
7
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'}
)

1
2
3
4
5
6
7
// generate a public API key that is restricted to '192.168.1.0/24':

let parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
let restriction = SecuredAPIKeyRestriction()
  .set(\.restrictSources, to: ["192.168.1.0/24"])

let publicKey = client.generateSecuredApiKey(parentApiKey: parentAPIKey, with: restriction)

1
2
3
4
5
6
SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
    RestrictSources = "192.168.1.0/24",
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

1
2
3
4
5
6
7
8
9
10
// Sync & Async version

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

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

1
2
3
4
5
6
// 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"),
)

1
2
3
4
5
6
val parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
val restriction = SecuredAPIKeyRestriction(
    restrictSources = listOf("192.168.1.0/24")
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

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

Copy

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'
  ]
);

1
2
3
4
5
6
7
8
9
// Only works in Node

// The rate limit will be based on the passed user token
const publicKey = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    userToken: 'user_42'
  }
);

1
2
3
4
5
6
7
from algoliasearch.search_client import SearchClient

# The rate limit will be based on the passed user token
public_key = SearchClient.generate_secured_api_key(
    'YourSearchOnlyApiKey',
    {'userToken': 'user_42'}
)

1
2
3
4
5
6
7
8
9
10
11
// generate a public API key for user 42. Here, records are tagged with:
//  - 'user_XXXX' if they are visible by user XXXX

let parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
let restriction = SecuredAPIKeyRestriction()
  .set(\.query, to: Query()
    .set(\.filters, to: "_tags:user_42")
    .set(\.userToken, to: "42")
  )

let publicKey = client.generateSecuredApiKey(parentApiKey: parentAPIKey, with: restriction)

1
2
3
4
5
6
7
8
// The rate limit will be based on the passed user token

SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
    UserToken = "42"
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

1
2
3
4
5
6
7
8
9
10
11
12
// Sync & Async version

// The rate limit will be based on the passed user token

SecuredApiKeyRestriction restriction =
new SecuredApiKeyRestriction()
    .setQuery(new Query().setUserToken("42"));

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

1
2
3
4
5
6
// The rate limit will be based on the passed user token

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

1
2
3
4
5
// The rate limit will be based on the passed user token
val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(userToken = Some("42"))
)

1
2
3
4
5
6
7
8
// The rate limit will be based on the passed user token

val parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
val restriction = SecuredAPIKeyRestriction(
    userToken = UserToken("42")
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

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

The generated API key.

Did you find this page helpful?

Create Secured API Key | Ruby API Client V1 (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