Required API Key:
no ACL required
About this method
Generate a virtual API Key without any call to the server.
When you need to restrict the scope of a API key, we recommend using the Secured API Key.
You can generate a Secured API Key from any API key.
Learn more about secured API keys.
If you’re generating Secured API Keys using the JavaScript client on your frontend,
it will result in a security breach since the user is able to modify the filters you’ve set by modifying the code from the browser.
You can define a number of restrictions (valid until, restrict indices, etc.).
If you want to rate-limit a secured API Key,
the API key you generate from the secured api key needs to be rate-limited.
You can do that via the dashboard or the API using the
Add API Key or Update API Key method
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'
]
);
|
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
| // Only works in Node
// 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'
}
);
|
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
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
| key, err := search.GenerateSecuredAPIKey(
"YourSearchOnlyApiKey",
opt.Filters("_tags:user_42"),
)
|
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
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 works in Node
// 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
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
| // Generate a public API key that is valid for 1 hour
key, err := search.GenerateSecuredAPIKey(
"YourSearchOnlyApiKey",
opt.Filters("_tags:user_42"),
)
|
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
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":
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
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
| 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
| String publicKey = client.generateSecuredApiKey(
"YourSearchOnlyApiKey",
Query(restrictSources = Some("192.168.1.0/24"))
)
|
1
2
3
4
5
6
7
| val parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
val restriction = SecuredAPIKeyRestriction(
query = Query(filters = "_tags:user_42"),
userToken = UserToken("42")
)
ClientSearch.generateAPIKey(parentAPIKey, restriction)
|
Generate a secured API key with a rate limiting applied per user
1
2
3
4
5
6
7
8
9
10
| // 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' => 'user_42',
'userToken' => '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', userToken: 'user_42' })
|
1
2
3
4
5
6
7
8
9
10
11
| // Only works in Node
// 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',
userToken: 'user_42'
}
);
|
1
2
3
4
5
6
7
8
| from algoliasearch.search_client import SearchClient
# generate a public API key for user 42. Here, records are tagged with:
# - 'user_XXXX' if they are visible by user XXXX
public_key = SearchClient.generate_secured_api_key(
'YourSearchOnlyApiKey',
{'filters': '_tags:user_42', 'userToken': 'user_42'}
)
|
1
2
3
4
5
6
7
8
9
10
| // 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" },
UserToken = "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").setUserToken("42"));
String publicKey = client.generateSecuredApiKey(
"YourSearchOnlyApiKey",
restriction
);
|
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
key, err := search.GenerateSecuredAPIKey(
"YourSearchOnlyApiKey",
opt.Filters("_tags:user_42"),
opt.UserToken("user_42"),
)
|
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")), userToken = Some("42")
)
|
1
2
3
4
5
6
| val parentAPIKey = APIKey("SearchOnlyApiKeyKeptPrivate")
val restriction = SecuredAPIKeyRestriction(
restrictSources = listOf("192.168.1.0/24")
)
ClientSearch.generateAPIKey(parentAPIKey, restriction)
|
Parameters
apiKey
|
API key to generate from.
|
filters
|
type: string
default: ""
Optional
Every filter set in the API key will always be applied.
On top of that, filters can be applied
in the query parameters.
If you set filters in the key groups:admin; and groups:press OR groups:visitors
in the searchParameter parameter; this will be equivalent to
groups:admin AND (groups:press OR groups:visitors).
|
validUntil
|
type: integer
default: no expiration date
Optional
A Unix timestamp used to define 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 sources description
Optional
IPv4 network allowed to use the generated key.
This is used for more protection against API key leaking and reuse.
|
userToken
|
type: string
default: no sources description
Optional
Specify a user identifier.
This is often used with rate limits.
By default, rate limits will only use the IP.
This can be an issue when several of your end users are using the same IP.
To avoid that, you can set a userToken query parameter when generating the key.
When set, a unique user will be identified by his IP + user_token instead of only by his IP.
This allows you to restrict a single user to performing a maximum of N API calls per hour,
even if he shares his IP with another user.
|
searchParameter
|
type: key value mapping
default: none
Optional
A mapping of search parameters that
will be forced at query time.
If specified in both the query and the API key filters the following parameters will be combined with an AND:
|
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.
1
| "YTgyMzMwOTkzMjA2Mzk5OWUxNjhjYmIwMGZkNGFmMzk2NDU3ZjMyYTg1NThiZjgxNDRiOTk3ZGE3NDU4YTA3ZWZpbHRlcnM9X3RhZ3MlM0F1c2VyXzQy"
|
api_key
|
Generated API Key.
|
