Meilisearch Authentication: API Keys & Security Best Practices (2026)

Authentication overview

Meilisearch employs API keys as its primary method for authentication, enabling controlled access to a Meilisearch instance. This system ensures that interactions with the search engine, such as indexing documents, performing searches, or managing settings, are authorized. API keys serve as credentials to verify the identity and permissions of the client making a request to the Meilisearch API. Each key is associated with specific privileges, dictating which operations can be performed.

When a Meilisearch instance is initialized, a master key is generated. This master key possesses full administrative privileges and is crucial for initial setup and for generating additional API keys with more granular permissions. The use of distinct keys for different purposes, such as a public key for search operations and a private key for administrative tasks, helps enforce a principle of least privilege, minimizing potential security risks by granting only necessary access to various application components or users. For production environments, it is a recommended practice to avoid exposing the master key directly and instead use purpose-specific API keys.

Supported authentication methods

Meilisearch primarily relies on API keys to manage access. These keys are categorized by the level of access they grant, providing a mechanism for role-based authorization within the search instance. The three main types of keys are:

• Master Key: This key has full administrative access to the Meilisearch instance. It can perform all operations, including creating and deleting indexes, managing settings, and creating other API keys. The master key is typically generated when the Meilisearch instance is first set up. Developers can find more information about the master key in the Meilisearch API Keys documentation.
• Private Key (Admin API Key): Private keys are designed for administrative operations that require more permissions than searching, but typically less than the master key. They can be configured to manage indexes, update settings, add or delete documents, and perform other data manipulation tasks. These keys should be kept confidential and used only by backend services or trusted environments.
• Public Key (Search API Key): Public keys are specifically for performing search queries. They are safe to embed in client-side applications (e.g., web browsers, mobile apps) because they only allow read-only access to search operations and do not expose any sensitive data or administrative functions. This key type helps ensure the security of the Meilisearch instance while enabling users to perform searches directly from their applications.

The following table summarizes the key types and their typical use cases:

Getting your credentials

Your Meilisearch credentials, specifically API keys, are obtained during the initial setup of your Meilisearch instance or can be generated programmatically afterward. The method of obtaining keys varies slightly depending on whether you are using Meilisearch Cloud or a self-hosted instance.

Meilisearch Cloud

For Meilisearch Cloud users, the master key is typically provided when you provision a new instance. This key is displayed once and should be stored securely immediately. Additional API keys with tailored permissions can then be generated directly through the Meilisearch Cloud dashboard or by using the Meilisearch API Key creation endpoint with your master key. The cloud environment provides an interface to manage these keys, allowing you to define their access rights and expiration dates.

Self-Hosted Meilisearch

When running a self-hosted Meilisearch instance, the master key is generated upon the first launch of the Meilisearch process. If you start Meilisearch without explicitly setting a master key, one will be generated automatically and printed to the console. For production deployments, it is recommended to define your master key explicitly using the --master-key flag or the MEILI_MASTER_KEY environment variable when starting the Meilisearch instance. This ensures the master key is known and consistently available. For detailed instructions on setting up the master key, refer to the Meilisearch master key setup guide.

Once you have your master key, you can use the Meilisearch API to create additional keys with specific permissions. This is done by making a POST request to the /keys endpoint, specifying the desired UID, description, list of allowed actions, and allowed indexes for the new key. For example, to create a key that only allows search queries on a specific index, you would define these parameters in the request body.

Authenticated request example

Authenticated requests to Meilisearch are made by including the API key in the Authorization header of your HTTP request. The key should be prefixed with Bearer, following the standard for bearer token authentication. This applies to all API key types (Master, Private, Public), with the specific key used determining the allowed actions.

Here's an example of an authenticated search request using a Public (Search) API Key in Python:

import requests

MEILISEARCH_HOST = "http://localhost:7700" # Replace with your Meilisearch instance host
MEILISEARCH_SEARCH_API_KEY = "your_public_search_api_key" # Replace with your actual search API key

headers = {
    "Authorization": f"Bearer {MEILISEARCH_SEARCH_API_KEY}",
    "Content-Type": "application/json"
}

search_query = {
    "q": "apple",
    "attributesToRetrieve": ["title", "description"]
}

response = requests.post(f"{MEILISEARCH_HOST}/indexes/products/search", headers=headers, json=search_query)

if response.status_code == 200:
    print("Search results:")
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

For operations requiring a Private (Admin) API Key or Master Key, the process is similar. For instance, updating an index's settings would involve a PUT request to the /indexes/{index_uid}/settings endpoint with the appropriate key in the Authorization header.

When using one of Meilisearch's official SDKs, the API key is typically passed during the client initialization, and the SDK handles the construction of the Authorization header for subsequent requests. For example, in JavaScript:

import { Meilisearch } from 'meilisearch'

const client = new Meilisearch({
  host: 'http://localhost:7700',
  apiKey: 'YOUR_PUBLIC_SEARCH_API_KEY',
})

client.index('products').search('apple').then((response) => {
  console.log(response.hits)
})

Security best practices

Securing your Meilisearch instance and its data involves careful management of API keys and adhering to general security principles:

1. Treat all API Keys as Sensitive: Even public search keys, while less critical than private keys, should be managed with care. Never hardcode API keys directly into public-facing source code repositories. Use environment variables or secure configuration management systems. The Google Cloud API Keys documentation provides general advice on API key security.
2. Principle of Least Privilege: Create API keys with the minimum necessary permissions for their intended task. For example, use a Public (Search) API Key for all client-side search requests and never expose an Admin or Master Key to the client-side. Generate specific keys for different backend services or applications, each with only the permissions required for its function.
3. Rotate API Keys Regularly: Periodically changing your API keys reduces the window of opportunity for a compromised key to be exploited. Establish a schedule for key rotation, especially for critical keys like the Master Key and Admin Keys.
4. Monitor API Key Usage: Keep an eye on the activity associated with your API keys. Unusual patterns of requests, such as a high volume of administrative operations from a search-only key, could indicate a compromise.
5. Secure Your Meilisearch Instance: If self-hosting, ensure your Meilisearch instance is properly secured. This includes running it behind a firewall, exposing it only to trusted IP addresses, and ensuring that communication is encrypted using HTTPS. For Meilisearch Cloud, these infrastructure security aspects are typically managed by the provider.
6. Use HTTPS: Always interact with your Meilisearch instance over HTTPS. This encrypts the communication between your client and the Meilisearch server, protecting your API keys and data from interception during transit.
7. Environment Variables for Keys: For self-hosted instances, use environment variables (e.g., MEILI_MASTER_KEY) to provide the master key to the Meilisearch process rather than embedding it directly in scripts or configuration files. This prevents accidental exposure in version control systems.
8. Restrict Key Access: Limit who has access to generate, view, or manage API keys within your organization. Implement access controls and auditing for credential management systems.

By implementing these practices, developers can significantly enhance the security posture of their Meilisearch deployments and protect against unauthorized access and data breaches. Further information on securing a Meilisearch instance is available in the Meilisearch security overview.