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.

Learn more about managing keys and their rights.

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 (opens new window) 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. 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

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 and get documents endpoints
documents.delete	Provides access to the delete one document, delete all documents, and batch delete 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
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. ["*"] for all indexes. Only the key's permitted actions can be used on these indexes

expiresAt

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

createdAt

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

updatedAt

Type: String
Default value: null
Description: Date and time when the key was last updated, represented in RFC 3339 (opens new window) 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'

client.getKeys({ limit: 3 })

client.get_keys({'limit': 3})

$client->getKeys((new KeysQuery())->setLimit(3));

KeysQuery query = new KeysQuery().setLimit(3);
client.getKeys(query);

client.keys(limit: 3)

ResourceResults<Key> keyResult = await client.GetKeysAsync(new KeysQuery { Limit = 3 });

let mut query = KeysQuery::new()
  .with_limit(3)
  .execute(&client)
  .await
  .unwrap();

client.getKeys(params: KeysQuery(limit: 3)) { result in
    switch result {
    case .success(let keys):
        print(keys)
    case .failure(let error):
        print(error)
    }
}

await client.getKeys(params: KeysQuery(limit: 3));

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.

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'

client.getKey('6062abda-a5aa-4414-ac91-ecd7944c0f8d')

client.get_key('6062abda-a5aa-4414-ac91-ecd7944c0f8d')

$client->getKey('6062abda-a5aa-4414-ac91-ecd7944c0f8d');

client.getKey("6062abda-a5aa-4414-ac91-ecd7944c0f8d");

client.key('6062abda-a5aa-4414-ac91-ecd7944c0f8d')

client.GetKey("6062abda-a5aa-4414-ac91-ecd7944c0f8d")

Key key = await client.GetKeyAsync("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4");

let key = client
  .get_key("6062abda-a5aa-4414-ac91-ecd7944c0f8d")
  .await
  .unwrap();

client.getKey(keyOrUid: "6062abda-a5aa-4414-ac91-ecd7944c0f8d") { result in
    switch result {
    case .success(let key):
        print(key)
    case .failure(let error):
        print(error)
    }
}

await client.getKey('6062abda-a5aa-4414-ac91-ecd7944c0f8d');

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

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 (opens new window) format. null if the key never expires
name	String	null	A human-readable name for the key
uid	String	N/A	A uuid v4 (opens new window) 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"
  }'

client.createKey({
  description: 'Add documents: Products API key',
  actions: ['documents.add'],
  indexes: ['products'],
  expiresAt: '2021-11-13T00:00:00Z'
})

client.create_key(options={
  'description': 'Add documents: Products API key',
  'actions': ['documents.add'],
  'indexes': ['products'],
  'expiresAt': '2042-04-02T00:42:42Z'
})

$client->createKey([
  'description' => 'Add documents: Products API key',
  'actions' => ['documents.add'],
  'indexes' => ['products'],
  'expiresAt' => '2042-04-02T00:42:42Z',
]);

SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
Date dateParsed = format.parse("2042-04-02T00:42:42Z");

Key keyInfo = new Key();

keyInfo.setDescription("Add documents: Products API key");
keyInfo.setActions(new String[] {"documents.add"});
keyInfo.setIndexes(new String[] {"products"});
keyInfo.setExpiresAt(dateParsed);

client.createKey(keyInfo);

client.create_key(
  description: 'Add documents: Products API key',
  actions: ['documents.add'],
  indexes: ['products'],
  expires_at: '2042-04-02T00:42:42Z'
)

client.CreateKey(&meilisearch.Key{
  Description: "Add documents: Products API key",
  Actions: []string{"documents.add"},
  Indexes: []string{"products"},
  ExpiresAt: time.Date(2042, time.April, 02, 0, 42, 42, 0, time.UTC),
})

Key keyOptions = new Key
{
    Description = "Add documents: Products API key",
    Actions = new KeyAction[] { KeyAction.DocumentsAdd },
    Indexes = new string[] { "products" },
    ExpiresAt = DateTime.Parse("2042-04-02T00:42:42Z")
};
Key createdKey = await this.client.CreateKeyAsync(keyOptions);

let mut key_options = KeyBuilder::new("Add documents: Products API key");
key_options
  .with_action(Action::DocumentsAdd)
  .with_expires_at(time::macros::datetime!(2042 - 04 - 02 00:42:42 UTC))
  .with_index("products");
let new_key = client
  .create_key(key_options)
  .await
  .unwrap();

let keyParams = KeyParams(
  description: "Add documents: Products API key",
  actions: ["documents.add"],
  indexes: ["products"],
  expiresAt: "2042-04-02T00:42:42Z"
)
client.createKey(keyParams) { result in
    switch result {
    case .success(let key):
        print(key)
    case .failure(let error):
        print(error)
    }
}

await client.createKey(
  description: 'Add documents: Products API key',
  actions: ['documents.add'],
  indexes: ['products'],
  expiresAt: DateTime(2042, 04, 02)
);

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.

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

client.updateKey('6062abda-a5aa-4414-ac91-ecd7944c0f8d', {
    name: 'Products/Reviews API key',
    description: 'Manage documents: Products/Reviews API key',
})

client.update_key(key_or_uid='6062abda-a5aa-4414-ac91-ecd7944c0f8d',
  options={
    'name': 'Products/Reviews API key',
    'description': 'Manage documents: Products/Reviews API key'
})

$client->updateKey('6062abda-a5aa-4414-ac91-ecd7944c0f8d',
  [
    'name' => 'Products/Reviews API key',
    'description' => 'Manage documents: Products/Reviews API key'
  ]);

KeyUpdate keyChanges = new KeyUpdate();
keyChanges.setName("Products/Reviews API key");
keyChanges.setDescription("Manage documents: Products/Reviews API key");

client.updateKey("6062abda-a5aa-4414-ac91-ecd7944c0f8d", keyChanges);

client.update_key(
  '6062abda-a5aa-4414-ac91-ecd7944c0f8d',
  {
    description: 'Manage documents: Products/Reviews API key',
    name: 'Products/Reviews API key'
  }
)

client.UpdateKey("6062abda-a5aa-4414-ac91-ecd7944c0f8d", &meilisearch.Key{
  Description: "Manage documents: Products/Reviews API key",
  Actions: []string{"documents.add", "document.delete"},
  Indexes: []string{"products", "reviews"},
  ExpiresAt: time.Date(2042, time.April, 02, 0, 42, 42, 0, time.UTC),
})

await client.UpdateKeyAsync(
  "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
  description: "Manage documents: Products/Reviews API key",
  name: "Products/Reviews API key"
)

let mut key = client
  .get_key("6062abda-a5aa-4414-ac91-ecd7944c0f8d")
  .await
  .unwrap();
key
    .with_description("Manage documents: Products/Reviews API key".to_string())
    .with_name("Products/Reviews API key".to_string())
    .update(&client)
    .await
    .unwrap();

let keyParams = KeyUpdateParams(
  description: "Manage documents: Products/Reviews API key",
  name: "Products/Reviews API key"
)

client.updateKey(keyOrUid: "6062abda-a5aa-4414-ac91-ecd7944c0f8d", keyParams: keyParams) { result in
  switch result {
  case .success(let key):
      print(key)
  case .failure(let error):
      print(error)
  }
}

await client.updateKey(
  '6062abda-a5aa-4414-ac91-ecd7944c0f8d',
  description: 'Manage documents: Products/Reviews API key',
  name: '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

/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'

client.deleteKey('6062abda-a5aa-4414-ac91-ecd7944c0f8d')

client.delete_key('6062abda-a5aa-4414-ac91-ecd7944c0f8d')

$client->deleteKey('6062abda-a5aa-4414-ac91-ecd7944c0f8d');

client.deleteKey("6062abda-a5aa-4414-ac91-ecd7944c0f8d")

client.delete_key('6062abda-a5aa-4414-ac91-ecd7944c0f8d')

client.DeleteKey("6062abda-a5aa-4414-ac91-ecd7944c0f8d")

client.DeleteKeyAsync("6062abda-a5aa-4414-ac91-ecd7944c0f8d")

let key = client
  .get_key("6062abda-a5aa-4414-ac91-ecd7944c0f8d")
  .await
  .unwrap();
client
  .delete_key(&key)
  .await?;

client.deleteKey(keyOrUid: "6062abda-a5aa-4414-ac91-ecd7944c0f8d") { result in
    switch result {
    case .success:
        print("success")
    case .failure(let error):
        print(error)
    }
}

await client.deleteKey('6062abda-a5aa-4414-ac91-ecd7944c0f8d');

Response: 204 No Content