This tutorial will show you how to secure your Meilisearch project. You will see how to manage your master key and how to safely send requests to the Meilisearch API using an API key.
Creating the master key
The master key is the first and most important step to secure your Meilisearch project.
Creating the master key in Meilisearch Cloud
Meilisearch Cloud automatically generates a master key for each project. This means Meilisearch Cloud projects are secure by default.
You can view your master key by visiting your project settings, then clicking “API Keys” on the sidebar:
Creating the master key in a self-hosted instance
To protect your self-hosted instance, relaunch it using the --master-key command-line option or the MEILI_MASTER_KEY environment variable:
./meilisearch --master-key="MASTER_KEY"
UNIX:export MEILI_MASTER_KEY="MASTER_KEY"
./meilisearch
set MEILI_MASTER_KEY="MASTER_KEY"
./meilisearch
The master key must be at least 16-bytes-long and composed of valid UTF-8 characters. Use one of the following tools to generate a secure master key: A master key has been set. Requests to Meilisearch won't be authorized unless you provide an authentication key.
We generated a new secure master key for you (you can safely use this token):
>> --master-key E8H-DDQUGhZhFWhTq263Ohd80UErhFmLIFnlQK81oeQ <<
Restart Meilisearch with the argument above to use this new and secure master key.
Obtaining API keys
When your project is protected, Meilisearch automatically generates four API keys: Default Search API Key, Default Admin API Key, Default Read-Only Admin API Key, and Default Chat API Key. API keys are authorization tokens designed to safely communicate with the Meilisearch API.
Obtaining API keys in Meilisearch Cloud
Find your API keys by visiting your project settings, then clicking “API Keys” on the sidebar:
Obtaining API keys in a self-hosted instance
Use your master key to query the /keys endpoint to view all API keys in your instance:
curl -X GET 'MEILISEARCH_URL/keys' \
-H 'Authorization: Bearer MASTER_KEY'
Only use the master key to manage API keys. Never use the master key to perform searches or other common operations.
{
"results": [
{
"name": "Default Search API Key",
"description": "Use it to search from the frontend",
"key": "0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33",
"uid": "74c9c733-3368-4738-bbe5-1d18a5fecb37",
"actions": [
"search"
],
"indexes": [
"*"
],
"expiresAt": null,
"createdAt": "2024-01-25T16:19:53.949636Z",
"updatedAt": "2024-01-25T16:19:53.949636Z"
},
{
"name": "Default Admin API Key",
"description": "Use it for anything that is not a search operation. Caution! Do not expose it on a public frontend",
"key": "62cdb7020ff920e5aa642c3d4066950dd1f01f4d",
"uid": "20f7e4c4-612c-4dd1-b783-7934cc038213",
"actions": [
"*"
],
"indexes": [
"*"
],
"expiresAt": null,
"createdAt": "2024-01-25T16:19:53.94816Z",
"updatedAt": "2024-01-25T16:19:53.94816Z"
},
{
"name": "Default Read-Only Admin API Key",
"description": "Use it to read information across the whole database. Caution! Do not expose this key on a public frontend",
"key": "9e32fb64e3569a749b0b87900d1026074e798743",
"uid": "7dc1ec09-94fb-49b5-b77b-03ce75af89a0",
"actions": [
"*.get",
"keys.get"
],
"indexes": [
"*"
],
"expiresAt": null,
"createdAt": "2024-01-25T16:19:53.94716Z",
"updatedAt": "2024-01-25T16:19:53.94716Z"
},
{
"name": "Default Chat API Key",
"description": "Use it to chat and search from the frontend",
"key": "0acaa4f3d57517e4b4d7c0052b02772620bd375a",
"uid": "d4e13ace-2a00-428c-90d1-b1c99eec98bd",
"actions": [
"chatCompletions",
"search"
],
"indexes": [
"*"
],
"expiresAt": null,
"createdAt": "2024-01-25T16:19:53.94606Z",
"updatedAt": "2024-01-25T16:19:53.94606Z"
}
],
…
}
Sending secure API requests to Meilisearch
Now you have your API keys, you can safely query the Meilisearch API. Add API keys to requests using an Authorization bearer token header.
Use the Default Admin API Key to perform sensitive operations, such as creating a new index:
curl \
-X POST 'MEILISEARCH_URL/indexes' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer DEFAULT_ADMIN_API_KEY' \
--data-binary '{
"uid": "medical_records",
"primaryKey": "id"
}'
Default Search API Key to perform search operations in the index you just created:
curl \
-X POST 'MEILISEARCH_URL/indexes/medical_records/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
--data-binary '{ "q": "appointments" }'
Admin API keys
Meilisearch provides two admin API keys for managing your instance:
- The
Default Admin API Key grants full access to all Meilisearch operations except API key management. Use it to configure index settings, add documents, and perform other administrative tasks.
- The
Default Read-Only Admin API Key allows read-only access to the whole database. Use it when you need to retrieve information from your Meilisearch instance without being able to modify it.
Do not expose admin API keys on a public frontend.
Chat API key
The Default Chat API Key is designed for frontend usage with conversational search. It has access to both search and chatCompletions actions, allowing users to both perform searches and interact with the chat completions feature.
Conclusion
You have successfully secured Meilisearch by configuring a master key. You then saw how to access the Meilisearch API by adding an API key to your request’s authorization header. 
