Authentication

MeiliSearch uses key-based authentication.

If your environment is set to production, authentication is mandatory. If it is set to development (the default), then authentication is optional.

If a MeiliSearch instance does not use authentication, all routes will be publicly accessible and unprotected.

Authentication is activated by setting a master key.

Key types

MeiliSearch uses three types of keys:

• The Master key grants access to all routes
• The Private key grants access to all routes except the /keys routes
• The Public key only grants access to the following routes:
  • GET /indexes/:index_uid/search
  • POST /indexes/:index_uid/search
  • GET /indexes/:index_uid/documents
  • GET /indexes/:index_uid/documents/:document_id

Both the private and public keys are automatically generated whenever you set or change the master key. You cannot create any additional keys.

The only route accessible to all, regardless of authentication, is GET /health.

Adding the master key

When launching a MeiliSearch instance, you have the option of setting the master key. By doing so, all routes will be protected and will require a key to access.

You can specify the master key by setting the MEILI_MASTER_KEY environment variable, or passing the command-line argument --master-key on launch.

Example

Env

CLI

export MEILI_MASTER_KEY=[YOUR_MASTER_KEY]
meilisearch

meilisearch --master-key=[YOUR_MASTER_KEY]

After setting up the master key, you can retrieve both the private and the public keys with the keys route.

Communicating with a protected instance

When using authentication, a key must be added to the header of each API call.

We strongly discourage using the master key for API calls. It is intended only for retrieving the public and private keys.

If an invalid key is provided, you will receive the HTTP/1.1 403 Forbidden status code. You will receive the same error if you fail to provide a key when querying a protected route.

Example

cURL

curl -X GET 'http://127.0.0.1:7700/keys' \
  --header "X-Meili-API-Key: masterKey"

Response

{
  "private": "8c222193c4dff5a19689d637416820bc623375f2ad4c31a2e3a76e8f4c70440d",
  "public": "948413b6667024a0704c2023916c21eaf0a13485a586c43e4d2df520852a4fb8"
}

Changing a key

Changing the master key will automatically generate new private and public keys. It is not possible to change one key without altering the others.

After changing the master key, it is mandatory to restart the MeiliSearch instance to generate new private and public keys.

Deactivating key-based authentication

In order to deactivate MeiliSearch’s key-based authentication, restart the instance without providing a master key:

• If the master key was set up with command-line flags, relaunch the instance without the --master-key option
• If the master key was configured with environment variables, unset it and relaunch the instance