# Keys

To communicate with MeiliSearch's RESTful API most of the routes require an API key.

The following information defines a key:

  • A Key generated by MeiliSearch
  • A Description
  • An ACL: list of permissions
  • An Indexes list with wildcard on which the ACL's are applied
  • A Revoked updatable boolean to revoke a key soon
  • An Expires_at timestamp that indicated the expire date of the token

A key is passed to MeiliSearch using the header X-Meili-Api-Key: myApiKey

# Master key

This is the only key that is not created by the API but is set as environement variable or as a binary flag when launching the MeiliSearch binary.

This key gives access to every route of the API.

WARNING

When no master key is set on binary launch, no API key is needed on any route. Giving full access to the API.

# Examples


# with the flag
$ ./meilisearch --api-key myMasterKey
# with the environement variable
$ MEILI_API_KEY=myMasterKey ./meilisearch

This header X-Meili-Api-Key: myMasterKey gives access to the whole API.


$ ./meilisearch

The header X-Meili-Api-Key is not required on any API requests. Creating an important security breach.

# Creating a key

Depending on the environment from which you use the MeiliSearch API, you only use a certain action set. It is possible to create an API key that only gives access to this set of actions.

You can create as many keys as you want.

# Key

MeiliSearch generates the key.

The key is returned on key creation. This key is your API KEY.

In the header, the API key is set in the X-Meili-Api-Key attribute.

This way:

$ curl \
  -X POST 'http://localhost:7700/indexes' \
  --header ' X-Meili-Api-Key: myApiKey'

# Description

The description expects a summary on the API KEY and the ACL it contains.

It should help you track your keys.

# ACL

ACL or Access-Control List is the list of permissions an API KEY can have.

  • IndexesRead: read access on indexes
  • IndexesWrite: write access on indexes
  • DocumentsRead: read access on documents
  • DocumentsWrite: write access on documents
  • SettingsRead: read access on settings
  • SettingsWrite: write access on settings
  • Admin: full permission on keys and stats
  • All: all of the above

Read gives access to all GET methods of the given route.

Write gives access to all POST, PUT, PATCH, DELETE methods of the given route.

# Example

If you use the API on the browser side to only make search queries, you do not need this same API key to be able to do anything else.

$ curl \
  -X POST 'http://localhost:7700/keys' \
  --data '{
      "expiresAt": 1574332928,
      "description": "search key",
      "acl": ["documentsRead"],
      "indexes": ["movies"]
  }'

This will return an API key that you can safely use on your browser side.

# Indexes

Indexes attribute contains a list of indexes to which the key is applied.

Wildcards are also acceptable inputs. Wildcards work as follows

  • "name_of_index" exact name of index
  • "*suffix" every index with this suffix
  • "prefix*"every index with this prefix
  • "*" all indexes.

# Examples

Given a set of indexes: english_movies, chinese_movies, french_books

The indexes list: ["*_movies"] will give access to english_movies and chinese_movies but not french_books.


Given a set of indexes: english_movies, chinese_movies, english_books, french_books

The indexes list: ["english_*"] will give access to english_movies and english_books but not french_books and chinese_movies.

# Revoked

Boolean set to false on key creation. It is updatable on key update.

Once it is set to true the API key loses all his accesses.

TIP

The revoked status can be toggled back at any time by an admin.

# Expires at

This attribute takes a timestamp as input. This timestamp is the expire date after which the API KEY will lose all his accesses.