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
{
"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.
NOTE
Since key
is a hash of the uid
and master key, 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
This also means that, if the master key changes, all key
values are automatically changed.
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
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
{
"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 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.
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 key object.
Create a key
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
{
"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
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.
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
{
"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 the specified API key.
Path parameters
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'