Managing API keys

This guide shows you how to access and configure API keys.

You can access the /keys route using the master key or an API key with access to the keys.get, keys.create, keys.update, or keys.delete actions.

You can use the list keys endpoint to obtain information on any active key in your Meilisearch instance. This is useful when you need an overview of existing keys and their permissions. Meilisearch automatically generates two default API keys for all protected projects: Default Search API Key and Default Admin API Key.

By default, GET /keys returns the 20 most recently created keys. You can change this using the limit query parameter. Expired keys will appear in the response, but deleted keys will not.

As with creating, deleting, and updating API keys, you either need the master key or an API key with the keys.get action to access this endpoint.

GET /keys/{key_or_uid} returns information on a single key. {key_or_uid} should be replaced with the full key or uid value obtained during key creation.

We can query our instance to confirm which active keys can search our patient_medical_records index:

curl \
  -X GET 'http://localhost:7700/keys' \
  -H 'Authorization: Bearer MASTER_KEY'

{
  "results": [
    {
      "name": "Default Search API Key",
      "description": "Use it to search from the frontend",
      "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
      "uid":"74c9c733-3368-4738-bbe5-1d18a5fecb37",
      "actions": [
        "search"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2022-01-01T10:00:00Z",
      "updatedAt": "2022-01-01T10:00:00Z"
    },
    {
      "name": "Default Admin API Key",
      "description": "Use it for all other than search operations. Caution! Do not expose it on a public frontend",
      "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f",
      "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213",
      "actions": [
        "*"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2021-08-11T10:00:00Z",
      "updatedAt": "2021-08-11T10:00:00Z"
    },
    {
      "name": null,
      "description": "Search patient records key",
      "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
      "uid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab",
      "actions": [
        "search"
      ],
      "indexes": [
        "patient_medical_records"
      ],
      "expiresAt": "2023-01-01T00:00:00Z",
      "createdAt": "2022-01-01T10:00:00Z",
      "updatedAt": "2022-01-01T10:00:00Z"
    }
  ],
  "offset":0,
  "limit":20,
  "total":3
}

You can create API keys by using the create key endpoint. This endpoint is always protected and can only be accessed with the master key or an API key with the keys.create action.

Let's create a new API key so authorized users can search through out patient_medical_records index:

curl \
  -X POST 'http://localhost:7700/keys' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MASTER_KEY' \
  --data-binary '{
    "description": "Search patient records key",
    "actions": ["search"],
    "indexes": ["patient_medical_records"],
    "expiresAt": "2023-01-01T00:00:00Z"
  }'

All /keys endpoints are synchronous, so your key will be generated immediately:

{
  "name": null,
  "description": "Search patient records key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid": "ac5cd97d-5a4b-4226-a868-2d0eb6d197ab",
  "actions": [
    "search"
  ],
  "indexes": [
    "patient_medical_records"
  ],
  "expiresAt": "2023-01-01T00:00:00Z",
  "createdAt": "2022-01-01T10:00:00Z",
  "updatedAt": "2022-01-01T10:00:00Z"
}

It is good practice to always set an expiry date when creating a new API key. If you are sure this is not necessary in your application, you can create an API key with no expiry date by explicitly passing a null value to expiresAt.

You can only update the name and description of an API key, even after it expires.

For example, we can update the Default Search API Key and change its description:

curl \
  -X PATCH 'http://localhost:7700/keys/74c9c733-3368-4738-bbe5-1d18a5fecb37' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "description": "Default Search API Key" }'

{
  "name": "Default Search API Key",
  "description": "Default Search API Key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid":"74c9c733-3368-4738-bbe5-1d18a5fecb37",
  "actions": [
    "search"
  ],
  "indexes": [
    "*"
  ],
  "expiresAt": null,
  "createdAt": "2022-01-01T10:00:00Z",
  "updatedAt": "2022-01-01T10:00:00Z"
}

To update an API key, you must use the update API key endpoint, which can only be accessed with the master key or an API key with the keys.update action.

Meilisearch supports partial updates with the PATCH route. This means your payload only needs to contain the data you want to update—in this case, description.

If a key is no longer useful or has been compromised, you can use delete key endpoint to disable it before its expiry date.

If we accidentally exposed our Search patient records key, we can delete it to prevent unauthorized parties from gaining access to our patient_medical_records index:

curl \
  -X DELETE 'http://localhost:7700/keys/ac5cd97d-5a4b-4226-a868-2d0eb6d197ab' \
  -H 'Authorization: Bearer MASTER_KEY'

Once a key is past its expiresAt date, using it for API authorization will return an error. Expired keys will still be returned by the list keys endpoint.

The key field is generated by hashing the master key and the uid. As a result, key values are deterministic between instances sharing the same configuration.

You can determine the value of an API key with the following command, replacing HYPHENATED_UUID and MASTER_KEY with the correct values for your key and instance:

echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY