Keys

The keys route allows you to create, manage, and delete API keys. In order to use these endpoints, the master key must be set and supplied in the header of the request:

curl \
  -H 'Authorization: Bearer replaceThisWithYourMasterKey'
  …

Learn more about managing keys and their rights.

Get all keys

GET

/keys

List all existing API keys. Expired keys are included in the response, but deleted keys are not.

See below for an explanation of returned fields.

Example

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

client.getKeys()

client.get_keys()

$client->getKeys();

client.getKeys();

client.keys

Result keyResult = await client.GetKeysAsync();
var keys = keyResult.Result;

let keys = client.get_keys().await.unwrap();

self.client.getKeys() { result in
    switch result {
    case .success(let keys):
        print(keys)
    case .failure(let error):
        print(error)
    }
}

await client.getKeys();

Response: 200 Ok

{
  "results": [
    {
      "description": "Manage documents: Products/Reviews API key",
      "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
      "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"
    },
    {
      "description": "Default Search API Key (Use it to search from the frontend code)",
      "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99",
      "actions": [
        "search"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2021-08-11T10:00:00Z",
      "updatedAt": "2021-08-11T10:00:00Z"
    },
    {
      "description": "Default Admin API Key (Use it for all other operations. Caution! Do not share it on the client side)",
      "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f",
      "actions": [
        "*"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2021-08-11T10:00:00Z",
      "updatedAt": "2021-08-11T10:00:00Z"
    }
  ]
}

Returned fields

description

A description for the key. Default value is null.

key

An alphanumeric key value generated by Meilisearch 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.

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}

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 is required.

Example

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

client.getKey('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4')

client.get_key('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4')

$client->getKey('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4');

client.getKey("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4");

client.key('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4')

client.GetKey("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4")

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

let key = client.get_key("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4").await.unwrap();

await client.getKey('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4');

Response: 200 Ok

{
  "description": "Add documents: Products API key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "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

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 all tasks endpoints. Tasks from non-authorized indexes will be omitted from the response. Also provides access to the get one task by index and get all tasks by index endpoints on authorized indexes.
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.
dumps.get	Provides access to the get dump status endpoint. Not restricted by indexes.
version	Provides access to the get Meilisearch version 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 masterKey' \
  -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 string[] { "documents.add" },
    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"
)
self.client.createKey(keyParams) { result in
    switch result {
    case .success(let key):
        print(keys)
    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

{
    "description": "Add documents: Products API key",
    "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
    "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}

Update the description, permissions, or expiration date of an API key. A valid API key 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/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \
  -H 'Authorization: Bearer masterKey' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "description": "Manage documents: Products/Reviews API key",
    "actions": [
      "documents.add",
      "documents.delete"
    ],
    "indexes": [
      "products",
      "reviews"
    ],
    "expiresAt": "2042-04-02T00:42:42Z"
  }'

client.updateKey('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4', {
    description: 'Manage documents: Products/Reviews API key',
    actions: [
      'documents.add',
      'documents.delete'
    ],
    indexes: [
      'products',
      'reviews'
    ],
    expiresAt: '2021-12-31T23:59:59Z'
})

client.update_key(key='d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4',
  options={
    'description': 'Manage documents: Products/Reviews API key',
    'actions': ['documents.add', 'documents.delete'],
    'indexes': ['products', 'reviews'],
    'expiresAt': '2042-04-02T00:42:42Z'
})

$client->updateKey('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4',
  [
    'description' => 'Manage documents: Products/Reviews API key',
    'actions' => ['documents.add', 'documents.delete'],
    'indexes' => ['products', 'reviews'],
    'expiresAt' => '2042-04-02T00:42:42Z',
  ]);

//Not yet implemented

client.update_key(
  'd0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4',
  {
    description: 'Manage documents: Products/Reviews API key',
    actions: [
      'documents.add',
      'documents.delete'
    ],
    indexes: [
      'products',
      'reviews'
    ],
    expires_at: '2042-04-02T00:42:42Z'
  }
)

client.UpdateKey("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4", &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),
})

// Not implemented yet

let key = client.get_key("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4").await.unwrap();
key.description = "Manage documents: Products/Reviews API key".to_string();
key.actions = vec![Action::DocumentsAdd, Action::DocumentsDelete];
key.indexes = vec!["products".to_string(), "reviews".to_string()];
key.expires_at = Some(time::macros::datetime!(2042 - 04 - 02 00:42:42 UTC));
let updated_key = client.update_key(&key);

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

await client.updateKey(
  'd0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4',
  description: 'Manage documents: Products/Reviews API key',
  actions: ['documents.add', 'documents.delete'],
  indexes: ['products', 'reviews'],
  expiresAt: DateTime(2042, 04, 02),
);

Response: 200 Ok

{
    "description": "Manage documents: Products/Reviews API key",
    "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
    "actions": [
        "documents.add",
        "documents.delete"
    ],
    "indexes": [
        "products",
        "reviews"
    ],
    "expiresAt": "2021-12-31T23:59:59Z",
    "createdAt": "2021-11-12T10:00:00Z",
    "updatedAt": "2021-10-12T15:00:00Z"
}

Delete a key

DELETE

/keys/{key}

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

Example

curl \
  -X DELETE 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \
  -H 'Authorization: Bearer masterKey'

client.deleteKey('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4')

client.delete_key('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4')

$client->deleteKey('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4')

client.deleteKey("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4")

client.delete_key('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4')

client.DeleteKey("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4")

client.DeleteKeyAsync("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4")

let key = client.get_key("d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4").await.unwrap();
client.delete_key(&key);

self.client.deleteKey(key: "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4")
{ result in
    switch result {
    case .success:
        print("success")
    case .failure(let error):
        print(error)
    }
}

await client.deleteKey('d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4');

Response: 204 No Content