Securing your 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 settings, then clicking “API Keys” on the sidebar:

An interface element named 'API keys' showing obscured security keys including: 'Master key', 'Default Search API Key', and 'Default Admin API Key'

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
Environment variable

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

UNIX:

export MEILI_MASTER_KEY="MASTER_KEY"
./meilisearch

Windows:

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:

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

An interface element named 'API keys' showing three obscured keys: 'Master key', 'Default Search API Key', and 'Default Admin API 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 \
  -X GET 'MEILISEARCH_URL/keys' \
  -H 'Authorization: Bearer MASTER_KEY'

const client = new MeiliSearch({ host: 'MEILISEARCH_URL', apiKey: 'masterKey' })
client.getKeys()

client = Client('MEILISEARCH_URL', 'masterKey')
client.get_keys()

$client = new Client('MEILISEARCH_URL', 'masterKey');
$client->getKeys();

Client client = new Client(new Config("MEILISEARCH_URL", "masterKey"));
client.getKeys();

client = MeiliSearch::Client.new('MEILISEARCH_URL', 'masterKey')
client.keys

client := meilisearch.New("MEILISEARCH_URL", meilisearch.WithAPIKey("masterKey"))
client.GetKeys(nil);

MeilisearchClient client = new MeilisearchClient("MEILISEARCH_URL", "masterKey");
var keys = await client.GetKeysAsync();

let client = Client::new("MEILISEARCH_URL", Some("MASTER_KEY")); let keys = client .get_keys() .await .unwrap();

client = try MeiliSearch(host: "MEILISEARCH_URL", apiKey: "masterKey")
client.getKeys { result in
    switch result {
    case .success(let keys):
        print(keys)
    case .failure(let error):
        print(error)
    }
}

var client = MeiliSearchClient('MEILISEARCH_URL', 'masterKey');
await client.getKeys();

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 default API keys:

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

let client = Client::new("MEILISEARCH_URL", Some("DEFAULT_ADMIN_API_KEY"));
let task = client
  .create_index("medical_records", Some("id"))
  .await
  .unwrap();

Then use the 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" }'

let client = Client::new("MEILISEARCH_URL", Some("DEFAULT_SEARCH_API_KEY"));
let index = client.index("medical_records");
index
  .search()
  .with_query("appointments")
  .execute::<MedicalRecord>()
  .await
  .unwrap();

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 the Chats API. 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.

Comparisons

Migration

Self-hosting

Demos

Under the hood

Other resources

Creating the master key

Creating the master key in Meilisearch Cloud

Creating the master key in a self-hosted instance

Obtaining API keys

Obtaining API keys in Meilisearch Cloud

Obtaining API keys in a self-hosted instance

Sending secure API requests to Meilisearch

Admin API keys

Chat API key

Conclusion

​Creating the master key

​Creating the master key in Meilisearch Cloud

​Creating the master key in a self-hosted instance

​Obtaining API keys

​Obtaining API keys in Meilisearch Cloud

​Obtaining API keys in a self-hosted instance

​Sending secure API requests to Meilisearch

​Admin API keys

​Chat API key

​Conclusion

Creating the master key

Creating the master key in Meilisearch Cloud

Creating the master key in a self-hosted instance

Obtaining API keys

Obtaining API keys in Meilisearch Cloud

Obtaining API keys in a self-hosted instance

Sending secure API requests to Meilisearch

Admin API keys

Chat API key

Conclusion