# Keys

The /keys route allows you to create, manage, and delete API keys. To use these endpoints, you must first set the master key. Once a master key is set, you can access these endpoints by supplying it in the header of the request, or using API keys that have access to the keys.get, keys.create, keys.update, or keys.delete actions.

Learn more about managing keys and their rights.

# Get all keys

GET

/keys

List the 20 most recently created keys. Expired keys are included in the response, but deleted keys are not. Results can be paginated by using the offset and limit query parameters.

See below for an explanation of returned fields.

# Query parameters

Query Parameter	Description	Default Value
`offset`	Number of keys to skip	0
`limit`	Number of keys to return	20

# Example

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

# Response: `200 Ok`

{
  "results": [
    {
      "name": null,
      "description": "Manage documents: Products/Reviews API key",
      "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
      "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
      "actions": [
        "documents.add",
        "documents.delete"
      ],
      "indexes": [
        "products",
        "reviews"
      ],
      "expiresAt": "2021-12-31T23:59:59Z",
      "createdAt": "2021-10-12T00:00:00Z",
      "updatedAt": "2021-10-13T15:00:00Z"
    },
    {
      "name": "Default Search API Key",
      "description": "Use it to search from the frontend code",
      "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99",
      "uid": "74c9c733-3368-4738-bbe5-1d18a5fecb37",
      "actions": [
        "search"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2021-08-11T10:00:00Z",
      "updatedAt": "2021-08-11T10:00:00Z"
    },
    {
      "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": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f",
      "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213",
      "actions": [
        "*"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2021-08-11T10:00:00Z",
      "updatedAt": "2021-08-11T10:00:00Z"
    }
  ],
  "offset":0,
  "limit":3,
  "total":7
}

NOTE

API keys are displayed in descending order based on their createdAt date. This means that the most recently created keys appear first.

# Returned fields

Returns API keys in an array called results, along with the following fields:

# `offset`

The number of keys skipped over.

# `limit`

The maximum number of keys to be returned by the request.

# `total`

The total number of API keys that can be browsed.

# The `results` array

For each key, it returns:

# `name`

A human-readable name for the key. Default value is null.

# `description`

A description for the key. Default value is null.

# `uid`

A uuid v4 (opens new window) to identify the API key. If not specified, it is automatically generated by Meilisearch.

# `key`

An alphanumeric key value generated by Meilisearch by hashing the uid and the master key on API key creation. Used for authorization when making calls to a protected Meilisearch instance.

This value is also used as the {key} path variable to update, delete, or get a specific key.

NOTE

Since key is a hash of the uid and master key, key values are deterministic between instances sharing the same configuration. This means if the master key changes, all key values are automatically changed.

Since the key field depends on the master key, it is computed at runtime and therefore not propagated to dumps and snapshots. As a result, even if a malicious user comes into possession of your dumps or snapshots, they will not have access to your instance's API keys.

# `actions`

An array of API actions permitted for the key. ["*"] for all actions.

# `indexes`

An array of indexes the key is authorized to act on. ["*"] for all indexes.

Only the key's permitted actions can be used on these indexes.

# `expiresAt`

Date and time when the key will expire, represented in RFC 3339 format. null if the key never expires.

# `createdAt`

Date and time when the key was created, represented in RFC 3339 format.

# `updatedAt`

Date and time when the key was last updated, represented in RFC 3339 format.

# Get one key

GET

/keys/{key_or_uid}

Get information on the specified key. Attempting to use this endpoint with a non-existent or deleted key will result in an error. A valid API key or uid is required.

# Example

curl \
  -X GET 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

# Response: `200 Ok`

{
  "name": null,
  "description": "Add documents: Products API key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}

For an explanation of these fields, see the get all keys endpoint.

# Create a key

POST

/keys

Create an API key with the provided description, permissions, and expiration date.

Only the indexes, actions, and expiresAt fields are mandatory.

# Body

# `name`

Type: string
Default value: null

A human-readable name for the key.

# `uid`

Type: string
Default value: none

A uuid v4 (opens new window) to identify the API key. If not specified, it is generated by Meilisearch.

# `description`

Type: string
Default value: null

An optional description for the key.

# `actions`

Type: array
Default value: none

A list of API actions permitted for the key. ["*"] for all actions.

name	description
search	Provides access to both `POST` and `GET` search endpoints on authorized indexes.
documents.add	Provides access to the add documents and update documents endpoints on authorized indexes.
documents.get	Provides access to the get one document and get documents endpoints on authorized indexes.
documents.delete	Provides access to the delete one document, delete all documents, and batch delete endpoints on authorized indexes.
indexes.create	Provides access to the create index endpoint.
indexes.get	Provides access to the get one index and list all indexes endpoints. Non-authorized `indexes` will be omitted from the response.
indexes.update	Provides access to the update index endpoint.
indexes.delete	Provides access to the delete index endpoint.
tasks.get	Provides access to the get one task and get tasks endpoints. Tasks from non-authorized `indexes` will be omitted from the response.
settings.get	Provides access to the get settings endpoint and equivalents for all subroutes on authorized indexes.
settings.update	Provides access to the update settings and reset settings endpoints and equivalents for all subroutes on authorized indexes.
stats.get	Provides access to the get stats of an index endpoint and the get stats of all indexes endpoint. For the latter, non-authorized `indexes` are omitted from the response.
dumps.create	Provides access to the create dump endpoint. Not restricted by `indexes`.
version	Provides access to the get Meilisearch version endpoint.
keys.get	Provides access to the get all keys endpoint.
keys.create	Provides access to the create key endpoint.
keys.update	Provides access to the update key endpoint.
keys.delete	Provides access to the delete key endpoint.

# `indexes`

Type: array
Default value: none

An array of indexes the key is authorized to act on. ["*"] for all indexes.

Only the key's permitted actions can be used on these indexes.

# `expiresAt`

Type: string
Default value: none

Date and time when the key will expire, represented in RFC 3339 format. null if the key never expires.

# Example

curl \
  -X POST 'http://localhost:7700/keys' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "description": "Add documents: Products API key",
    "actions": ["documents.add"],
    "indexes": ["products"],
    "expiresAt": "2042-04-02T00:42:42Z"
  }'

# Response: `201 Created`

{
  "name": null,
  "description": "Manage documents: Products/Reviews API key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}

# Update a key

PATCH

/keys/{key_or_uid}

Update the name and description of an API key. A valid API key or uid is required.

To learn more about the variables sent in the body of the request, see the create key endpoint.

Updates to keys are partial. This means you should provide only the fields you intend to update, as any fields not present in the payload will remain unchanged.

# Example

curl \
  -X PATCH 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "name": "Products/Reviews API key",
    "description": "Manage documents: Products/Reviews API key"
  }'

let mut key = client.get_key("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4").await.unwrap();
key
    .with_description("Manage documents: Products/Reviews API key".to_string())
    .with_actions(vec![Action::DocumentsAdd, Action::DocumentsDelete])
    .with_indexes(vec!["products".to_string(), "reviews".to_string()])
    .with_expires_at(time::macros::datetime!(2042 - 04 - 02 00:42:42 UTC))
    .update(&client);

# Response: `200 Ok`

{
  "name": "Products/Reviews API key",
  "description": "Manage documents: Products/Reviews API key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
  "actions": [
    "documents.add",
    "documents.delete"
  ],
  "indexes": [
    "products",
    "reviews"
  ],
  "expiresAt": "2021-12-31T23:59:59Z",
  "createdAt": "2021-10-12T00:00:00Z",
  "updatedAt": "2021-10-13T15:00:00Z"
}

# Delete a key

DELETE

/keys/{key_or_uid}

Delete the specified API key. A valid API key or uid is required.

# Example

curl \
  -X DELETE 'http://localhost:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

# Response: `204 No Content`

← Tasks All Settings →

# Keys

# Get all keys

# Query parameters

# Example

# Response: 200 Ok

# Returned fields

# offset

# limit

# total

# The results array

# name

# description

# uid

# key

# actions

# indexes

# expiresAt

# createdAt

# updatedAt

# Get one key

# Example

# Response: 200 Ok

# Create a key

# Body

# name

# uid

# description

# actions

# indexes

# expiresAt

# Example

# Response: 201 Created

# Update a key

# Example

# Response: 200 Ok

# Delete a key

# Example

# Response: 204 No Content

# Response: `200 Ok`

# `offset`

# `limit`

# `total`

# The `results` array

# `name`

# `description`

# `uid`

# `key`

# `actions`

# `indexes`

# `expiresAt`

# `createdAt`

# `updatedAt`

# Response: `200 Ok`

# `name`

# `uid`

# `description`

# `actions`

# `indexes`

# `expiresAt`

# Response: `201 Created`

# Response: `200 Ok`

# Response: `204 No Content`