Managing API keys
This guide shows you how to access and configure API keys.
Accessing the /keys
API route
You can access the /keys
route using the master key or an API key with access to the keys.get
, keys.create
, keys.update
, or keys.delete
actions.
Listing API keys
You can use the list keys endpoint to obtain information on any active key in your Meilisearch instance. This is useful when you need an overview of existing keys and their permissions. Meilisearch automatically generates two default API keys for all protected projects: Default Search API Key
and Default Admin API Key
.
By default, GET /keys
returns the 20 most recently created keys. You can change this using the limit
query parameter. Expired keys will appear in the response, but deleted keys will not.
As with creating, deleting, and updating API keys, you either need the master key or an API key with the keys.get
action to access this endpoint.
GET /keys/{key_or_uid}
returns information on a single key. {key_or_uid}
should be replaced with the full key
or uid
value obtained during key creation.
We can query our instance to confirm which active keys can search our patient_medical_records
index:
curl \
-X GET 'http://localhost:7700/keys' \
-H 'Authorization: Bearer MASTER_KEY'
{
"results": [
{
"name": "Default Search API Key",
"description": "Use it to search from the frontend",
"key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
"uid":"74c9c733-3368-4738-bbe5-1d18a5fecb37",
"actions": [
"search"
],
"indexes": [
"*"
],
"expiresAt": null,
"createdAt": "2022-01-01T10:00:00Z",
"updatedAt": "2022-01-01T10:00:00Z"
},
{
"name": "Default Admin API Key",
"description": "Use it for all other than search operations. Caution! Do not expose it on a public frontend",
"key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f",
"uid": "20f7e4c4-612c-4dd1-b783-7934cc038213",
"actions": [
"*"
],
"indexes": [
"*"
],
"expiresAt": null,
"createdAt": "2021-08-11T10:00:00Z",
"updatedAt": "2021-08-11T10:00:00Z"
},
{
"name": null,
"description": "Search patient records key",
"key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
"uid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab",
"actions": [
"search"
],
"indexes": [
"patient_medical_records"
],
"expiresAt": "2023-01-01T00:00:00Z",
"createdAt": "2022-01-01T10:00:00Z",
"updatedAt": "2022-01-01T10:00:00Z"
}
],
"offset":0,
"limit":20,
"total":3
}
Creating an API key
You can create API keys by using the create key endpoint. This endpoint is always protected and can only be accessed with the master key or an API key with the keys.create
action.
Let's create a new API key so authorized users can search through out patient_medical_records
index:
curl \
-X POST 'http://localhost:7700/keys' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer MASTER_KEY' \
--data-binary '{
"description": "Search patient records key",
"actions": ["search"],
"indexes": ["patient_medical_records"],
"expiresAt": "2023-01-01T00:00:00Z"
}'
All /keys
endpoints are synchronous, so your key will be generated immediately:
{
"name": null,
"description": "Search patient records key",
"key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
"uid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab",
"actions": [
"search"
],
"indexes": [
"patient_medical_records"
],
"expiresAt": "2023-01-01T00:00:00Z",
"createdAt": "2022-01-01T10:00:00Z",
"updatedAt": "2022-01-01T10:00:00Z"
}
It is good practice to always set an expiry date when creating a new API key. If you are sure this is not necessary in your application, you can create an API key with no expiry date by explicitly passing a null
value to expiresAt
.
Updating an API key
You can only update the name
and description
of an API key, even after it expires.
For example, we can update the Default Search API Key
and change its description:
curl \
-X PATCH 'http://localhost:7700/keys/74c9c733-3368-4738-bbe5-1d18a5fecb37' \
-H 'Authorization: Bearer MASTER_KEY' \
-H 'Content-Type: application/json' \
--data-binary '{ "description": "Default Search API Key" }'
{
"name": "Default Search API Key",
"description": "Default Search API Key",
"key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
"uid":"74c9c733-3368-4738-bbe5-1d18a5fecb37",
"actions": [
"search"
],
"indexes": [
"*"
],
"expiresAt": null,
"createdAt": "2022-01-01T10:00:00Z",
"updatedAt": "2022-01-01T10:00:00Z"
}
To update an API key, you must use the update API key endpoint, which can only be accessed with the master key or an API key with the keys.update
action.
Meilisearch supports partial updates with the PATCH
route. This means your payload only needs to contain the data you want to update—in this case, description
.
Deleting an API key
If a key is no longer useful or has been compromised, you can use delete key endpoint to disable it before its expiry date.
If we accidentally exposed our Search patient records key
, we can delete it to prevent unauthorized parties from gaining access to our patient_medical_records
index:
curl \
-X DELETE 'http://localhost:7700/keys/ac5cd97d-5a4b-4226-a868-2d0eb6d197ab' \
-H 'Authorization: Bearer MASTER_KEY'
Expired keys
Once a key is past its expiresAt
date, using it for API authorization will return an error. Expired keys will still be returned by the list keys endpoint.
Retrieving the value of an API key
The key
field is generated by hashing the master key and the uid
. As a result, key
values are deterministic between instances sharing the same configuration.
You can determine the value of an API key with the following command, replacing HYPHENATED_UUID
and MASTER_KEY
with the correct values for your key and instance:
echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY
API keys and backups
Since the key
field depends on the master key, it is not propagated to dumps and snapshots. If a malicious user ever gets access to your dumps or snapshots, they will not have access to your instance's API keys.