Securing your project

This tutorial will show you how to secure your Meilisearch project.

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 overview:

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:

CLI

./meilisearch --master-key="MASTER_KEY"

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:

• uuidgen
• openssl rand
• shasum
• randomkeygen.com

Meilisearch will launch as usual. The start up log should include a message informing you the instance is protected:

A master key has been set. Requests to Meilisearch won't be authorized unless you provide an authentication key.

If you supplied an insecure key, Meilisearch will display a warning and suggest you relaunch your instance with an autogenerated alternative:

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 two API keys: Default Search API Key and Default Admin 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 in the same section where you previously located the master key:

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

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.

Meilisearch’s response will include at least the two default API keys:

{
  "results": [
    {
      "name": "Default Search API Key",
      "description": "Use it to search from the frontend",
      "key": "0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33",
      "uid": "123-345-456-987-abc",
      "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": "123-345-456-987-abc",
      "actions": [
        "*"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2024-01-25T16:19:53.94816Z",
      "updatedAt": "2024-01-25T16:19:53.94816Z"
    }
  ],
  …
}

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

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"
  }'

Then use the Default Search API Key to perform search operations in the index you just created:

cURL

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" }'

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.