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
)
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.
Generate a secured API key without any call to Algolia’s servers.
When you need to restrict the scope of an API key, 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.
Don’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 (such as “valid until” and “restrict indices”).
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.
// Create a public API key with a fixed filteruse\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 filterpublic_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 filterconstpublicKey=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
fromalgoliasearch.search_clientimportSearchClientpublic_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 filterletparentAPIKey=APIKey("YourSearchOnlyApiKey")letrestriction=SecuredAPIKeyRestriction().set(\.query,to:Query().set(\.filters,to:"_tags:user_42"))letpublicKey=client.generateSecuredApiKey(parentApiKey:parentAPIKey,with:restriction)
1
2
3
4
5
6
7
// Create a public API key with a fixed filtervalparentAPIKey=APIKey("YourSearchOnlyApiKey")valrestriction=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 filterSecuredApiKeyRestrictionrestriction=newSecuredApiKeyRestriction{Query=newQuery{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 filterSecuredApiKeyRestrictionrestriction=newSecuredApiKeyRestriction().setQuery(newQuery().setFilters("_tags:user_42"));StringpublicKey=client.generateSecuredApiKey("YourSearchOnlyApiKey",restriction);
1
2
3
4
5
// Create a public API key with a fixed filterkey,err:=search.GenerateSecuredAPIKey("YourSearchOnlyApiKey",opt.Filters("_tags:user_42"),)
1
2
3
4
5
// Create a public API key with a fixed filtervalpublicKey=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 houruse\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 hourvalid_until=Time.now.to_i+3600public_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 hourconstvalidUntil=Math.floor(Date.now()/1000)+3600;constpublicKey=client.generateSecuredApiKey('YourSearchOnlyApiKey',{validUntil});
1
2
3
4
5
6
7
8
9
10
importtimefromalgoliasearch.search_clientimportSearchClient# Create a public API key that expires in 1 hour
valid_until=int(time.time())+3600public_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 hourletparentAPIKey=APIKey("YourSearchOnlyApiKey")letrestriction=SecuredAPIKeyRestriction().set(\.validUntil,to:Date().addingTimeInterval(3600).timeIntervalSince1970)letpublicKey=client.generateSecuredApiKey(parentApiKey:parentAPIKey,with:restriction)
1
2
3
4
5
6
7
8
// Create a public API key that expires in 1 hourvalparentAPIKey=APIKey("YourSearchOnlyAPIKey")valhourInMilliseconds=60*60*1000valrestriction=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 hourvardate=DateTime.UtcNow.AddHours(1);SecuredApiKeyRestrictionrestriction=newSecuredApiKeyRestriction{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 hourintvalidUntil=(int)(System.currentTimeMillis()/1000+3600);SecuredApiKeyRestrictionrestriction=newSecuredApiKeyRestriction().setQuery(newQuery().setValidUntil(validUntil));StringpublicKey=client.generateSecuredApiKey("YourSearchOnlyApiKey",restriction);
1
2
3
4
5
6
// Create a public API key that expires in 1 hourvalid_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 hourvalvalidUntil=System.currentTimeMillis()/1000+3600valpublicKey=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"constpublicKey=client.generateSecuredApiKey('YourSearchOnlyApiKey',{restrictIndices:'index1,index2'});
1
2
3
4
5
6
7
fromalgoliasearch.search_clientimportSearchClient# 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"letparentAPIKey=APIKey("YourSearchOnlyAPIKey")letrestriction=SecuredAPIKeyRestriction().set(\.restrictIndices,to:["index1","index2"])letpublicKey=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"valparentAPIKey=APIKey("YourSearchOnlyAPIKey")valrestriction=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"SecuredApiKeyRestrictionrestriction=newSecuredApiKeyRestriction{RestrictIndices=newList<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"SecuredApiKeyRestrictionrestriction=newSecuredApiKeyRestriction().setRestrictIndices(Arrays.asList("index1","index2"))StringpublicKey=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"valpublicKey=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`constpublicKey=client.generateSecuredApiKey('YourSearchOnlyApiKey',{restrictSources:'192.168.1.0/24'});
1
2
3
4
5
6
7
fromalgoliasearch.search_clientimportSearchClient# 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`letparentAPIKey=APIKey("YourSearchOnlyAPIKey")letrestriction=SecuredAPIKeyRestriction().set(\.restrictSources,to:["192.168.1.0/24"])letpublicKey=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`valparentAPIKey=APIKey("YourSearchOnlyAPIKey")valrestriction=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`SecuredApiKeyRestrictionrestriction=newSecuredApiKeyRestriction{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`SecuredApiKeyRestrictionrestriction=newSecuredApiKeyRestriction().setRestrictSources(Collections.singletonList("192.168.1.0/24"));StringpublicKey=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`StringpublicKey=client.generateSecuredApiKey("YourSearchOnlyApiKey",Query(restrictSources=Some("192.168.1.0/24")))
Generate a secured API key with a rate limiting applied per user
Copy
1
2
3
4
5
6
7
8
// Create a public API key for a specific useruse\Algolia\AlgoliaSearch\SearchClient;$public_key=SearchClient::generateSecuredApiKey('YourSearchOnlyApiKey',['userToken'=>'user_42']);
1
2
# The rate limit will be based on the passed user tokenpublic_key=Algolia::Search::Client.generate_secured_api_key('YourSearchOnlyApiKey',{userToken: 'user_42'})
1
2
3
4
5
6
7
// Create a public API key for a specific userconstpublicKey=client.generateSecuredApiKey('YourSearchOnlyApiKey',{userToken:'user_42'});
1
2
3
4
5
6
7
fromalgoliasearch.search_clientimportSearchClient# 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 userletparentAPIKey=APIKey("SearchOnlyAPIKey")letrestriction=SecuredAPIKeyRestriction().set(\.query,to:Query().set(\.userToken,to:"42"))letpublicKey=client.generateSecuredApiKey(parentApiKey:parentAPIKey,with:restriction)
1
2
3
4
5
6
7
// Create a public API key for a specific uservalparentAPIKey=APIKey("YourSearchOnlyAPIKey")valrestriction=SecuredAPIKeyRestriction(userToken=UserToken("42"))ClientSearch.generateAPIKey(parentAPIKey,restriction)
1
2
3
4
5
6
7
// Create a public API key for a specific userSecuredApiKeyRestrictionrestriction=newSecuredApiKeyRestriction{UserToken="42"};client.GenerateSecuredApiKeys("YourSearchOnlyApiKey",restriction);
1
2
3
4
5
6
7
8
9
// Create a public API key for a specific userSecuredApiKeyRestrictionrestriction=newSecuredApiKeyRestriction().setQuery(newQuery().setUserToken("42"));StringpublicKey=client.generateSecuredApiKey("YourSearchOnlyApiKey",restriction);
1
2
3
4
5
// Create a public API key for a specific userkey,err:=search.GenerateSecuredAPIKey("YourSearchOnlyApiKey",opt.UserToken("user_42"),)
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 uservalpublicKey=client.generateSecuredApiKey("YourSearchOnlyApiKey",Query(userToken=Some("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.
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, 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.
This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language and/or implementation, the actual type in your language might differ from what’s written here. You can view the response in the logs (using the getLogs method).