Create API key

Create a new API key with the specified name, description, actions, and index scopes. The key value is returned only once at creation time; store it securely.

POST /keys

cURL

cURL

curl \
  -X POST 'MEILISEARCH_URL/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"
  }'

201

{
  "uid": "01b4bc42-eb33-4041-b481-254d00cce834",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "name": "Indexing Products API key",
  "description": null,
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}

Authorizations

Authorization · string · header · required

An API key is a token that you provide when making API calls. Read more about how to secure your project.

Include the API key to the Authorization header, for instance:

-H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1'

If you use a SDK, ensure you instantiate the client with the API key, for instance with JS SDK:

const client = new MeiliSearch({
  host: 'MEILISEARCH_URL',
  apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1'
});

Body

application/json

actions · enum<string>[] · required

A list of actions permitted for the key. ["*"] for all actions. The * character can be used as a wildcard when located at the last position. e.g. documents.* to authorize access on all documents endpoints.

Available options: *, search, documents.*, documents.add, documents.get, documents.delete, indexes.*, indexes.create, indexes.get, indexes.update, indexes.delete, indexes.swap, tasks.*, tasks.cancel, tasks.delete, tasks.get, settings.*, settings.get, settings.update, stats.*, stats.get, metrics.*, metrics.get, dumps.*, dumps.create, snapshots.*, snapshots.create, version, keys.create, keys.get, keys.update, keys.delete, experimental.get, experimental.update, export, network.get, network.update, chatCompletions, chats.*, chats.get, chats.delete, chatsSettings.*, chatsSettings.get, chatsSettings.update, *.get, webhooks.get, webhooks.update, webhooks.delete, webhooks.create, webhooks.*, indexes.compact, fields.post

Example:

["documents.add"]

indexes · string[] · required

A list of accessible indexes permitted for the key. ["*"] for all indexes. The * character can be used as a wildcard when located at the last position. e.g. products_* to allow access to all indexes whose names start with products_.

Example:

["products"]

description · string | null

A description for the key. null if empty.

Example:

null

name · string | null

A human-readable name for the key. null if empty.

Example:

"Indexing Products API key"

uid · string | null

A uuid v4 to identify the API Key. If not specified, it's generated by Meilisearch.

Example:

"01b4bc42-eb33-4041-b481-254d00cce834"

expiresAt · string<date-time> | null

Represent the expiration date and time as RFC 3339 format. null equals to no expiration time.

Response

201

application/json

Key has been created.

Represents an API key used for authenticating requests to Meilisearch. Each key has specific permissions defined by its actions and can be scoped to particular indexes. Keys provide fine-grained access control for your Meilisearch instance.

key · string · required

The actual API key string to use in the Authorization: Bearer <key> header when making requests to Meilisearch. Keep this value secret and never expose it in client-side code.

uid · string<uuid> · required

The unique identifier (UUID) for this API key. Use this to update or delete the key. The UID remains constant even if the key's name or description changes.

actions · enum<string>[] · required

The list of actions (permissions) this key is allowed to perform. Examples include documents.add, search, indexes.create, settings.update, etc. Use * to grant all permissions.

Available options: *, search, documents.*, documents.add, documents.get, documents.delete, indexes.*, indexes.create, indexes.get, indexes.update, indexes.delete, indexes.swap, tasks.*, tasks.cancel, tasks.delete, tasks.get, settings.*, settings.get, settings.update, stats.*, stats.get, metrics.*, metrics.get, dumps.*, dumps.create, snapshots.*, snapshots.create, version, keys.create, keys.get, keys.update, keys.delete, experimental.get, experimental.update, export, network.get, network.update, chatCompletions, chats.*, chats.get, chats.delete, chatsSettings.*, chatsSettings.get, chatsSettings.update, *.get, webhooks.get, webhooks.update, webhooks.delete, webhooks.create, webhooks.*, indexes.compact, fields.post

indexes · string[] · required

The list of index UIDs this key can access. Use * to grant access to all indexes, including future ones. Patterns are also supported, e.g., movies_* matches any index starting with "movies_".

createdAt · string<date-time> · required

The date and time when this API key was created, formatted as an RFC 3339 date-time string. This is automatically set by Meilisearch and cannot be modified.

updatedAt · string<date-time> · required

The date and time when this API key was last modified, formatted as an RFC 3339 date-time string. This is automatically updated by Meilisearch when the key's name or description changes.

name · string | null

A human-readable name for the API key. Use this to identify the purpose of each key, such as "Frontend Search Key" or "Admin Key for CI/CD". This is optional and can be null.

description · string | null

A longer description explaining the purpose or usage of this API key. Useful for documenting why the key was created and how it should be used. This is optional and can be null.

expiresAt · string<date-time> | null

The expiration date and time of the key in RFC 3339 format. After this time, the key will no longer be valid for authentication. Set to null for keys that never expire.