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.

WARNING

Accessing the /keys route without setting a master key will throw a missing_master_key error.

Key object

json

{
  "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`

Type: String
Default value: null
Description: A human-readable name for the key

`description`

Type: String
Default value: null
Description: A description for the key. You can add any important information about the key here

`uid`

Type: String
Default value: N/A
Description: A uuid v4 to identify the API key. If not specified, it is automatically generated by Meilisearch

`key`

Type: String
Default value: N/A
Description: 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.

If the master key changes, all key values are automatically changed.

Reusing API keys between instances

Custom API keys are deterministic: key is a SHA256 hash of the uid and master key. To reuse custom API keys, launch the new instance with the same master key and recreate your API keys with the same uid.

You cannot reuse default API keys between instances. Meilisearch automatically generates their uids the first time you launch an instance.

`actions`

Type: Array
Default value: N/A
Description: An array of API actions permitted for the key, represented as strings. API actions are only possible on authorized indexes. ["*"] for all actions.

You can use * as a wildcard to access all endpoints for the documents, indexes, tasks, settings, stats and dumps actions. For example, documents.* gives access to all document actions.

WARNING

For security reasons, we do not recommend creating keys that can perform all actions.

Name	Description
`search`	Provides access to both `POST` and `GET` search endpoints
`documents.add`	Provides access to the add documents and update documents endpoints
`documents.get`	Provides access to the get one document, get documents with POST, and get documents with GET endpoints
`documents.delete`	Provides access to the delete one document, delete all documents, batch delete, and delete by filter endpoints
`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
`indexes.swap`	Provides access to the swap indexes endpoint. Non-authorized `indexes` will not be swapped
`tasks.get`	Provides access to the get one task and get tasks endpoints. Tasks from non-authorized `indexes` will be omitted from the response
`tasks.cancel`	Provides access to the cancel tasks endpoint. Tasks from non-authorized `indexes` will not be canceled
`tasks.delete`	Provides access to the delete tasks endpoint. Tasks from non-authorized `indexes` will not be deleted
`settings.get`	Provides access to the get settings endpoint and equivalents for all subroutes
`settings.update`	Provides access to the update settings and reset settings endpoints and equivalents for all subroutes
`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`
`snapshots.create`	Provides access to the create snapshot 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: N/A
Description: An array of indexes the key is authorized to act on. Use["*"] for all indexes. Only the key's permitted actions can be used on these indexes.

You can also use the * character as a wildcard by adding it at the end of a string. This allows an API key access to all index names starting with that string. For example, using "indexes": ["movie*"] will give the API key access to the movies and movie_ratings indexes.

`expiresAt`

Type: String
Default value: N/A
Description: Date and time when the key will expire, represented in RFC 3339 format. null if the key never expires

NOTE

Once a key is past its expiresAt date, using it for API authorization will return an error.

`createdAt`

Type: String
Default value: null
Description: Date and time when the key was created, represented in RFC 3339 format

`updatedAt`

Type: String
Default value: null
Description: Date and time when the key was last updated, represented in RFC 3339 format

Get all keys

GET/keys

Returns the 20 most recently created keys in a results array. Expired keys are included in the response, but deleted keys are not.

Query parameters

Results can be paginated using the offset and limit query parameters.

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

Response

Name	Type	Description
`results`	Array	An array of key objects
`offset`	Integer	Number of keys skipped
`limit`	Integer	Number of keys returned
`total`	Integer	Total number of API keys

Example

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

Response: `200 Ok`

json

{
  "results": [
    {
      "name": null,
      "description": "Manage documents: Products/Reviews API key",
      "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
      "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
      "actions": [
        "documents.add",
        "documents.delete"
      ],
      "indexes": [
        "prod*",
        "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.

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.

Path parameters

A valid API key or uid is required.

Name	Type	Description
`key` *	String	`key` value of the requested API key
`uid` *	String	`uid` of the requested API key

Example

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

Response: `200 Ok`

json

{
  "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 key object.

Create a key

POST/keys

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

Body

Name	Type	Default value	Description
`actions` *	Array	N/A	A list of API actions permitted for the key. `["*"]` for all actions
`indexes` *	Array	N/A	An array of indexes the key is authorized to act on. `["*"]` for all indexes
`expiresAt` *	String	N/A	Date and time when the key will expire, represented in RFC 3339 format. `null` if the key never expires
`name`	String	`null`	A human-readable name for the key
`uid`	String	N/A	A uuid v4 to identify the API key. If not specified, it is generated by Meilisearch
`description`	String	`null`	An optional description for the key

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`

json

{
  "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.

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.

Path parameters

A valid API key or uid is required.

Name	Type	Description
`key` *	String	`key` value of the requested API key
`uid` *	String	`uid` of the requested API key

Body

Name	Type	Default value	Description
`name`	String	`null`	A human-readable name for the key
`description`	String	`null`	An optional description for the key

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"
  }'

Response: `200 Ok`

json

{
  "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.

Path parameters

A valid API key or uid is required.

Name	Type	Description
`key` *	String	`key` value of the requested API key
`uid` *	String	`uid` of the requested API key

Example

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

Response: `204 No Content`

Edit this page

Was this helpful?

Want to include more details? Raise an issue in our public docs repo.

Keys

WARNING

Key object

name

description

uid

key

Reusing API keys between instances

actions

WARNING

indexes

expiresAt

NOTE

createdAt

updatedAt

Get all keys

Query parameters

Response

Example

Response: 200 Ok

NOTE

Get one key

Path parameters

Example

Response: 200 Ok

Create a key

Body

Example

Response: 201 Created

Update a key

Path parameters

Body

Example

Response: 200 Ok

Delete a key

Path parameters

Example

Response: 204 No Content

Was this helpful?

`name`

`description`

`uid`

`key`

`actions`

`indexes`

`expiresAt`

`createdAt`

`updatedAt`

Response: `200 Ok`

Response: `200 Ok`

Response: `201 Created`

Response: `200 Ok`

Response: `204 No Content`