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.

    NameDescription
    searchProvides access to both POST and GET search endpoints
    documents.addProvides access to the add documents and update documents endpoints
    documents.getProvides access to the get one document, get documents with POST, and get documents with GET endpoints
    documents.deleteProvides access to the delete one document, delete all documents, batch delete, and delete by filter endpoints
    indexes.createProvides access to the create index endpoint
    indexes.getProvides access to the get one index and list all indexes endpoints. Non-authorized indexes will be omitted from the response
    indexes.updateProvides access to the update index endpoint
    indexes.deleteProvides access to the delete index endpoint
    indexes.swapProvides access to the swap indexes endpoint. Non-authorized indexes will not be swapped
    tasks.getProvides access to the get one task and get tasks endpoints. Tasks from non-authorized indexes will be omitted from the response
    tasks.cancelProvides access to the cancel tasks endpoint. Tasks from non-authorized indexes will not be canceled
    tasks.deleteProvides access to the delete tasks endpoint. Tasks from non-authorized indexes will not be deleted
    settings.getProvides access to the get settings endpoint and equivalents for all subroutes
    settings.updateProvides access to the update settings and reset settings endpoints and equivalents for all subroutes
    stats.getProvides 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.createProvides access to the create dump endpoint. Not restricted by indexes
    snapshots.createProvides access to the create snapshot endpoint. Not restricted by indexes
    versionProvides access to the get Meilisearch version endpoint
    keys.getProvides access to the get all keys endpoint
    keys.createProvides access to the create key endpoint
    keys.updateProvides access to the update key endpoint
    keys.deleteProvides 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 ParameterDefault ValueDescription
    offset0Number of keys to skip
    limit20Number of keys to return

    Response

    NameTypeDescription
    resultsArrayAn array of key objects
    offsetIntegerNumber of keys skipped
    limitIntegerNumber of keys returned
    totalIntegerTotal 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/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.

    NameTypeDescription
    key *Stringkey value of the requested API key
    uid *Stringuid 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

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

    NameTypeDefault valueDescription
    actions *ArrayN/AA list of API actions permitted for the key. ["*"] for all actions
    indexes *ArrayN/AAn array of indexes the key is authorized to act on. ["*"] for all indexes
    expiresAt *StringN/ADate and time when the key will expire, represented in RFC 3339 format. null if the key never expires
    nameStringnullA human-readable name for the key
    uidStringN/AA uuid v4 to identify the API key. If not specified, it is generated by Meilisearch
    descriptionStringnullAn 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

    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.

    NameTypeDescription
    key *Stringkey value of the requested API key
    uid *Stringuid of the requested API key

    Body

    NameTypeDefault valueDescription
    nameStringnullA human-readable name for the key
    descriptionStringnullAn 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/keys/{key_or_uid}

    Delete the specified API key.

    Path parameters

    A valid API key or uid is required.

    NameTypeDescription
    key *Stringkey value of the requested API key
    uid *Stringuid 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