Skip to main content
This page documents an earlier version of the API client. For the latest version, see Generate secured API key.
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.
Secured API keys must have stricter permissions than their base API key. If you use the same permissions and restrictions as the base API key, using this key generates a 403 status error.

​
Examples

​
Generate a secured API key containing a filter

// Create a public API key with a fixed filter
SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
  Query = new Query { Filters = "_tags:user_42" },
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

​
Generate a secured API key with an expiration date

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

​
Generate a secured API key with indices restriction

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

​
Generate a secured API key with a network restriction

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

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

// Create a public API key for a specific user
SecuredApiKeyRestriction restriction = new SecuredApiKeyRestriction
{
    UserToken = "42"
};

client.GenerateSecuredApiKeys("YourSearchOnlyApiKey", restriction);

​
Parameters

​
apiKey
string
required
The search-only API key that the secured API key will inherit its restrictions from.
​
filters
string
Filters that apply to every search made with the secured API key. You can add extra filters at search time with the filters 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).
​
restrictIndices
list
Index names that can be queried. By default, all indices are queried.
​
restrictSources
string
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).
​
searchParameter
object
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):
​
userToken
string
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.
​
validUntil
integer
Unix timestamp used to set the expiration date of the API key.

​
Response

​
api_key
string
The generated API key.

​
Response as JSON

This section shows the JSON response returned by the API. Each API client wraps this response in language-specific objects, so the structure may vary. To view the response, use the getLogs method. Don’t rely on the order of properties—JSON objects don’t preserve key order.
JSON
"YTgyMzMwOTkzMjA2Mzk5OWUxNjhjYmIwMGZkNGFmMzk2NDU3ZjMyYTg1NThiZjgxNDRiOTk3ZGE3NDU4YTA3ZWZpbHRlcnM9X3RhZ3MlM0F1c2VyXzQy"
⌘I