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

    An interface element named "API keys" showing three obscured keys: "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:

    ./meilisearch --master-key="MASTER_KEY"
    
    Tools for generating a 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:

    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:

    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 'http://localhost:7700/keys' \
    -H 'Authorization: Bearer MASTER_KEY'
    Do not use the master key for API requests

    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 \
      -X POST 'http://localhost:7700/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 \
      -X POST 'http://localhost:7700/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.