API client / Methods / API keys

Jun. 08, 2023

Create secured API key

Required API Key: no ACL required

Method signature

SearchClient::generateSecuredApiKey(string apiKey, [
  'filters'           => string,
  'validUntil'        => integer,
  'restrictIndices'   => array,
  'restrictSources'   => string,
  'userToken'         => string
  // + any searchParameter
])

Algolia::Search::Client.generate_secured_api_key(
  String apiKey,
  Hash opts = {
    filters: string,
    validUntil: integer,
    restrictIndices: array,
    restrictSources: string,
    userToken: string
    # any searchParameter
  }
)

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

SearchClient.generate_secured_api_key(apiKey, {
    'filters': string,
    'validUntil': integer,
    'restrictIndices': list,
    'restrictSources': str,
    'userToken': str
    # any searchParameter
})

client.generateSecuredApiKey(
  parentApiKey: APIKey,
  with restriction: SecuredAPIKeyRestriction
) -> APIKey

struct SecuredAPIKeyRestriction {
  var query: Query? = nil // add any searchParameter
  var restrictIndices: [IndexName]? = nil
  var restrictSources: [String]? = nil
  var validUntil: TimeInterval? = nil
  var userToken: UserToken? = nil
}

fun ClientSearch.generateAPIKey(
    parentAPIKey: APIKey,
    restriction: SecuredAPIKeyRestriction
): APIKey

data class SecuredAPIKeyRestriction(
    val query: Query? = null,
    val restrictIndices: List<IndexName>? = null,
    val restrictSources: List<String>? = null,
    val validUntil: Long? = null,
    val userToken: UserToken? = null
)

client.GenerateSecuredApiKey(
  String apiKey,
  new SecuredApiKeyRestriction
  {
    Query = new Query(), // add any searchParameter
    Filters = String ,
    ValidUntil = long,
    RestrictIndices = string,
    RestrictSources = string,
    UserToken = String
  }
)

client.generateSecuredApiKey(String apiKey,
  new SecuredApiKeyRestriction()
  .setQuery(new Query()) // add any searchParameter
  .setValidUntil(int validUntil)
  .setRestrictIndices(List<String> restrictIndices)
  .setRestrictSources(String restrictSources)
  .setUserToken(String userToken)
)

client.GenerateSecuredAPIKey(string apiKey, []interface{}{
  "filters": string,
  "validUntil": int,
  "restrictIndices": []string,
  "restrictSources": string,
  "userToken": string,
  // any searchParameter
})

client.generateSecuredApiKey(String apiKey, Query(
  filters = Some(String),
  validUntil = Some(int),
  restrictIndices = Some(List<String>),
  restrictSources = Some(String),
  userToken = Some(String)
  // any searchParameter
))

See code examples

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

You’re currently reading the JavaScript API client v4 documentation. Check the migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

About this method

Generate a secured API key without any calls to Algolia’s servers.

When you need to restrict the scope of an API key, generate a secured API key on your server, without any calls to Algolia.

You can’t generate secured API keys from your Admin API key or from other secured API keys.

When you generate a secured API key, you can define several restrictions, such as how long the key is valid for and which indexes it can access. The more restrictions you set, the longer the key will be. If the key is longer than 500 characters, you may have problems using it on some networks.

If you want to limit the number of requests that can be made with a secured API key, you must also rate-limit the key that you use to generate it. You can create a rate-limited key in the Algolia dashboard or use the Add API key or Update API key methods of an API client.

Examples

Read the Algolia CLI documentation for more information.

Generate a secured API key containing a filter

Copy

1
2
3
4
5
6
7
8
// Create a public API key with a fixed filter
use \Algolia\AlgoliaSearch\SearchClient;
$public_key = SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'filters' => '_tags:user_42'
  ]
);

1
2
3
4
5
# Create a public API key with a fixed filter
public_key = Algolia::Search::Client.generate_secured_api_key(
  'YourSearchOnlyApiKey',
  { filters: '_tags:user_42' }
)

1
2
3
4
5
6
7
8
9
// Create a public API key with a fixed filter
const publicKey = client.generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  {
    filters: '_tags:user_42'
  }
);

console.log(publicKey);

1
2
3
4
5
6
7
# Create a public API key with a fixed filter
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
// Create a public API key with a fixed filter
let parentAPIKey = APIKey("YourSearchOnlyApiKey")
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
// Create a public API key with a fixed filter
val parentAPIKey = APIKey("YourSearchOnlyApiKey")
val restriction = SecuredAPIKeyRestriction(
    query = Query(filters = "_tags:user_42")
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

1
2
3
4
5
6
7
// Create a public API key with a fixed filter
SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
  Query = new Query { Filters = "_tags:user_42" },
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

1
2
3
4
5
6
7
8
9
// Create a public API key with a fixed filter
SecuredApiKeyRestriction restriction =
new SecuredApiKeyRestriction()
    .setQuery(new Query().setFilters("_tags:user_42"));

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

1
2
3
4
5
// Create a public API key with a fixed filter
val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(filters = Some("_tags:user_42"))
)

Generate a secured API key with an expiration date

Copy

1
2
3
4
5
6
7
8
9
// Create a public API key that expires in 1 hour
use \Algolia\AlgoliaSearch\SearchClient;
$validUntil = time() + 3600;
$public_key = SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'validUntil' => $validUntil
  ]
);

1
2
3
# Create a public API key that expires in 1 hour
valid_until = Time.now.to_i + 3600
public_key = Algolia::Search::Client.generate_secured_api_key('YourSearchOnlyApiKey', { validUntil: valid_until })

1
2
3
4
5
6
7
8
// Create a public API key that expires in 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

# Create a public API key that expires in 1 hour
valid_until = int(time.time())  + 3600
public_key = SearchClient.generate_secured_api_key(
    "YourSearchOnlyApiKey",
    {"validUntil": valid_until}
)

1
2
3
4
5
6
// Create a public API key that expires in 1 hour
let parentAPIKey = APIKey("YourSearchOnlyApiKey")
let restriction = SecuredAPIKeyRestriction()
  .set(\.validUntil, to: Date().addingTimeInterval(3600).timeIntervalSince1970)

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

1
2
3
4
5
6
7
8
// Create a public API key that expires in 1 hour
val parentAPIKey = APIKey("YourSearchOnlyAPIKey")
val hourInMilliseconds = 60 * 60 * 1000
val restriction = SecuredAPIKeyRestriction(
    validUntil = Time.getCurrentTimeMillis() + hourInMilliseconds
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

1
2
3
4
5
6
7
8
// Create a public API key that expires in 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
// Create a public API key that expires in 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
6
// Create a public API key that expires in 1 hour
valid_until = time.Now().Unix() + int64(time.Hour.Seconds())
key, err := search.GenerateSecuredAPIKey(
    "YourSearchOnlyApiKey",
    valid_until
)

1
2
3
4
5
6
// Create a public API key that expires in 1 hour
val validUntil = System.currentTimeMillis() / 1000 + 3600
val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(validUntil = Some(validUntil)
)

Generate a secured API key with indices restriction

Copy

1
2
3
4
5
6
7
8
// Create a public API key that is restricted to "index1" and "index2"
use \Algolia\AlgoliaSearch\SearchClient;
$public_key = SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'restrictIndices' => 'index1,index2'
  ]
);

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

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

# Create 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
// Create a public API key that is restricted to "index1" and "index2"
let parentAPIKey = APIKey("YourSearchOnlyAPIKey")
let restriction = SecuredAPIKeyRestriction()
  .set(\.restrictIndices, to: ["index1", "index2"])

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

1
2
3
4
5
6
7
8
9
10
// Create a public API key that is restricted to "index1" and "index2"
val parentAPIKey = APIKey("YourSearchOnlyAPIKey")
val restriction = SecuredAPIKeyRestriction(
    restrictIndices = listOf(
        IndexName("index1"),
        IndexName("index2")
    )
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

1
2
3
4
5
6
7
// Create 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
// Create 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
// Create 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
// Create a public API key that is restricted to "index1" and "index2"
val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(restrictIndices = Some(Seq("index1", "index2"))
)

Generate a secured API key with a network restriction

Copy

1
2
3
4
5
6
7
8
// Create a public API key that is restricted to `192.168.1.0/24`
use \Algolia\AlgoliaSearch\SearchClient;
$public_key = SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'restrictSources' => '192.168.1.0/24'
  ]
);

1
2
# Create a public API key that is restricted to `192.168.1.0/24`
public_key = Algolia::Search::Client.generate_secured_api_key('YourSearchOnlyApiKey', { restrictSources: '192.168.1.0/24' })

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

# Create 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
// Create a public API key that is restricted to `192.168.1.0/24`
let parentAPIKey = APIKey("YourSearchOnlyAPIKey")
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
7
// Create a public API key that is restricted to `192.168.1.0/24`
val parentAPIKey = APIKey("YourSearchOnlyAPIKey")
val restriction = SecuredAPIKeyRestriction(
    restrictSources = listOf("192.168.1.0/24")
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

1
2
3
4
5
6
7
// Create a public API key that is restricted to `192.168.1.0/24`
SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
    RestrictSources = "192.168.1.0/24",
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

1
2
3
4
5
6
7
8
9
// Create a public API key that is restricted to `192.168.1.0/24`
SecuredApiKeyRestriction restriction =
new SecuredApiKeyRestriction()
    .setRestrictSources(Collections.singletonList("192.168.1.0/24"));

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

1
2
3
4
5
// Create 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
// Create a public API key that is restricted to `192.168.1.0/24`
String publicKey = client.generateSecuredApiKey(
    "YourSearchOnlyApiKey",
    Query(restrictSources = Some("192.168.1.0/24"))
)

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

Copy

1
2
3
4
5
6
7
8
// Create a public API key for a specific user
use \Algolia\AlgoliaSearch\SearchClient;
$public_key = SearchClient::generateSecuredApiKey(
  'YourSearchOnlyApiKey',
  [
    'userToken' => 'user_42'
  ]
);

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

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

# Create a public API key for a specific user
public_key = SearchClient.generate_secured_api_key(
    'YourSearchOnlyApiKey',
    {'userToken': 'user_42'}
)

1
2
3
4
5
6
7
8
// Create a public API key for a specific user
let parentAPIKey = APIKey("SearchOnlyAPIKey")
let restriction = SecuredAPIKeyRestriction()
  .set(\.query, to: Query()
    .set(\.userToken, to: "42")
  )

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

1
2
3
4
5
6
7
// Create a public API key for a specific user
val parentAPIKey = APIKey("YourSearchOnlyAPIKey")
val restriction = SecuredAPIKeyRestriction(
    userToken = UserToken("42")
)

ClientSearch.generateAPIKey(parentAPIKey, restriction)

1
2
3
4
5
6
7
// Create a public API key for a specific user
SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
    UserToken = "42"
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

1
2
3
4
5
6
7
8
9
// Create a public API key for a specific user
SecuredApiKeyRestriction restriction =
new SecuredApiKeyRestriction()
    .setQuery(new Query().setUserToken("42"));

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

1
2
3
4
5
6
7
// The rate limit will be based on the passed user token
// Create a public API key for a specific user

val publicKey = client.generateSecuredApiKey(
  "YourSearchOnlyApiKey",
  Query(userToken = Some("42"))
)

Parameters

Parameter	Description
`apiKey`	type: string Required The search-only API key that the secured API key will inherit its 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 Unix timestamp used to set the expiration date of the API key.
`restrictIndices`	type: list default: all indices Optional Index names that can be queried.
`restrictSources`	type: string default: no restricted sources Optional IPv4 network allowed to use the generated key. Use this to protect against API key leaking and reuse. You can only provide a single source, but you can specify a range of IPs (for example, `192.168.1.0/24`).
`userToken`	type: string default: users' IP address Optional Unique user IP address. This can be useful when you want to impose a rate limit on specific users. By default, rate limits are set 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. Specifying the `userToken` in a secured API key is also a good security practice as it ensures users don’t change it. Many features like Analytics, Personalization, and Dynamic Re-ranking rely on the authenticity of user identifiers. Setting the `userToken` at the API key level ensures that downstream services work as expected and prevents abuse.
`searchParameter`	type: key/value mapping default: none Optional 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

This section shows the JSON response returned by the API. Each API client encapsulates this response inside objects specific to the programming language, so that the actual response might be different. You can view the response by using the getLogs method. Don’t rely on the order of attributes in the response, as JSON doesn’t guarantee the ordering of keys in objects.

JSON format

Copy

1
"YTgyMzMwOTkzMjA2Mzk5OWUxNjhjYmIwMGZkNGFmMzk2NDU3ZjMyYTg1NThiZjgxNDRiOTk3ZGE3NDU4YTA3ZWZpbHRlcnM9X3RhZ3MlM0F1c2VyXzQy"

Field	Description
`api_key`	string The generated API key.

Did you find this page helpful?

Create secured API key

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 rate-limiting applied per user

Parameters

Response

JSON format

On this page