Skip to main content
This guide explains the differences between the master key and API keys, and how to manage them in self-hosted Meilisearch instances.

​
Master key

The master key grants full control over your Meilisearch instance. It is the only key with access to endpoints for creating and deleting API keys by default. Since the master key is not an API key, it cannot be listed or configured through the /keys endpoints.
Exposing the master key can give malicious users complete control over your Meilisearch instance. Only use the master key when managing API keys, never for regular operations.

​
Setting the master key

Launch Meilisearch with a master key to protect your instance: 
meilisearch --master-key="your-master-key-here"
Your master key must be at least 16 bytes. Use a secure, randomly generated string.

​
Resetting the master key

If your master key is compromised, reset it by relaunching your instance with a new value: 
meilisearch --master-key="new-master-key-here"
Resetting the master key automatically invalidates all existing API keys. You will need to create new API keys after resetting.

​
API keys

API keys grant access to a specific set of indexes, routes, and endpoints. You can configure them to expire after a certain date. Use the /keys route to create, configure, and delete API keys. Use API keys for all API operations except API key management. This includes:
  • Searching documents
  • Adding and updating documents
  • Configuring index settings
  • Managing indexes

​
Default API keys

When you launch Meilisearch with a master key, four default API keys are automatically created:
KeyPurposePermissions
Default Search API KeyFrontend search queriesSearch only, all indexes
Default Admin API KeyBackend operationsFull access except key management
Default Read-Only Admin API KeyRead-only accessRead-only access to all indexes, documents, and settings
Default Chat API KeyFrontend conversational searchSearch and chat completions, all indexes
In most cases, these default keys are sufficient:
  • Use the Default Search API Key for client-side search
  • Use the Default Admin API Key for server-side operations (do not expose on a public frontend)
  • Use the Default Read-Only Admin API Key for read-only access to all indexes, documents, and settings (do not expose on a public frontend)
  • Use the Default Chat API Key for conversational search (can be safely used from the frontend)

​
Creating custom API keys

Create custom API keys for more granular control: 
curl -X POST "${MEILISEARCH_URL}/keys" \
  -H "Authorization: Bearer ${MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Search key for products index",
    "actions": ["search"],
    "indexes": ["products"],
    "expiresAt": "2025-12-31T23:59:59Z"
  }'

​
Best practices

  1. Never expose the master key in client-side code or public repositories
  2. Use API keys for all regular operations
  3. Limit API key permissions to only what’s needed
  4. Set expiration dates on API keys when appropriate
  5. Rotate keys regularly in production environments

API keys reference

Full API documentation for key management

Security overview

Learn about Meilisearch security model