/keys 路由允许您创建、管理和删除 API 密钥。要使用这些端点，您必须首先设置主密钥。一旦设置了主密钥，您可以通过在请求头中提供它，或使用具有 keys.get、keys.create、keys.update 或 keys.delete 操作访问权限的 API 密钥来访问这些端点。

如果未设置主密钥就访问 /keys 路由，将抛出 missing_master_key 错误。

​
密钥对象

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

类型: String
默认值: null
描述: 密钥的人类可读名称

​
description

类型: String
默认值: null
描述: 密钥的描述。您可以在此处添加有关密钥的任何重要信息

​
uid

类型: String
默认值: 不适用
描述: 用于识别 API 密钥的 UUID v4。如果未指定，Meilisearch 将自动生成。

​
key

类型: String
默认值: 不适用
描述: Meilisearch 在创建 API 密钥时，通过哈希 uid 和主密钥生成的字母数字密钥值。用于向 受保护的 Meilisearch 实例发起调用时的授权。

此值也用作 {key} 路径变量，用于更新、删除或获取特定密钥。

如果主密钥更改，所有 key 值将自动更改。

自定义 API 密钥是确定性的：key 是 uid 和主密钥的 SHA256 哈希。要重复使用自定义 API 密钥，请使用相同的主密钥启动新实例，并使用相同的 uid 重新创建您的 API 密钥。

您不能在实例之间重复使用默认 API 密钥。 Meilisearch 会在您首次启动实例时自动生成它们的 uid。

​
actions

类型: Array
默认值: 不适用
描述: 密钥允许的 API 操作数组，表示为字符串。API 操作仅在授权的 indexes 上可能。["*"] 表示所有操作。

您可以使用 * 作为通配符来访问 documents、indexes、tasks、settings、stats 和 dumps 操作的所有端点。例如，documents.* 授予对所有文档操作的访问权限。

出于安全原因，我们不建议创建可以执行所有操作的密钥。

名称描述
search提供对 POST 和 GET 搜索端点的访问权限
documents.add提供对添加文档和更新文档端点的访问权限
documents.get提供对获取单个文档、通过 POST 获取文档和通过 GET 获取文档端点的访问权限
documents.delete提供对删除单个文档、删除所有文档、批量删除和按过滤器删除端点的访问权限
indexes.create提供对创建索引端点的访问权限
indexes.get提供对获取单个索引和列出所有索引端点的访问权限。未经授权的 indexes 将从响应中省略
indexes.update提供对更新索引端点的访问权限
indexes.delete提供对删除索引端点的访问权限
indexes.swap提供对交换索引端点的访问权限。未经授权的 indexes 将不会被交换
tasks.get提供对获取单个任务和获取任务端点的访问权限。来自未经授权的 indexes 的任务将从响应中省略
tasks.cancel提供对取消任务端点的访问权限。来自未经授权的 indexes 的任务将不会被取消
tasks.delete提供对删除任务端点的访问权限。来自未经授权的 indexes 的任务将不会被删除
settings.get提供对获取设置端点以及所有子路由的等效访问权限
settings.update提供对更新设置和重置设置端点以及所有子路由的等效访问权限
stats.get提供对获取索引统计信息端点和获取所有索引统计信息端点的访问权限。对于后者，未经授权的 indexes 将从响应中省略
dumps.create提供对创建转储端点的访问权限。不受 indexes 限制
snapshots.create提供对创建快照端点的访问权限。不受 indexes 限制
version提供对获取 Meilisearch 版本端点的访问权限
keys.get提供对获取所有密钥端点的访问权限
keys.create提供对创建密钥端点的访问权限
keys.update提供对更新密钥端点的访问权限
keys.delete提供对删除密钥端点的访问权限
network.get提供对获取网络对象端点的访问权限
network.update提供对更新网络对象端点的访问权限

​
indexes

类型: Array
默认值: 不适用
描述: 密钥被授权操作的索引数组。使用 ["*"] 表示所有索引。只有密钥的 允许的操作才能在这些索引上使用。

您还可以通过在字符串末尾添加 * 字符作为通配符。这允许 API 密钥访问以该字符串开头的所有索引名称。例如，使用 "indexes": ["movie*"] 将授予 API 密钥访问 movies 和 movie_ratings 索引的权限。

​
expiresAt

类型: String
默认值: 不适用
描述: 密钥过期日期和时间，以 RFC 3339 格式表示。如果密钥永不过期，则为 null。

一旦密钥超过其 expiresAt 日期，将其用于 API 授权将返回错误。

​
createdAt

类型: String
默认值: null
描述: 密钥创建日期和时间，以 RFC 3339 格式表示。

​
updatedAt

类型: String
默认值: null
描述: 密钥最后更新日期和时间，以 RFC 3339 格式表示。

​
获取所有密钥

GET
/keys

以 results 数组的形式返回最近创建的 20 个密钥。过期的密钥包含在响应中，但已删除的密钥不包含。

​
查询参数

可以使用 offset 和 limit 查询参数对结果进行分页。

查询参数默认值描述
offset0要跳过的密钥数量
limit20要返回的密钥数量

​
响应

名称类型描述
results数组密钥对象数组
offset整数已跳过的密钥数量
limit整数已返回的密钥数量
total整数API 密钥总数

​
示例

curl \
  -X GET 'MEILISEARCH_URL/keys?limit=3' \
  -H 'Authorization: Bearer MASTER_KEY'

​
响应: 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
}

API 密钥按其 createdAt 日期降序显示。这意味着最新创建的密钥会首先出现。

​
获取单个密钥

GET
/keys/{key_or_uid}

获取指定密钥的信息。尝试使用不存在或已删除的密钥来使用此端点将导致错误。

​
路径参数

需要有效的 API key 或 uid。

名称类型描述
key *String请求的 API 密钥的 key 值
uid *String请求的 API 密钥的 uid

​
示例

curl \
  -X GET 'MEILISEARCH_URL/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

​
响应: 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"
}

有关这些字段的解释，请参阅密钥对象。

​
创建密钥

POST
/keys

使用提供的描述、权限和过期日期创建 API 密钥。

​
请求体

名称类型默认值描述
actions *数组不适用密钥允许的 API 操作列表。["*"] 表示所有操作
indexes *数组不适用密钥被授权操作的索引数组。["*"] 表示所有索引
expiresAt *String不适用密钥过期日期和时间，以 RFC 3339 格式表示。如果密钥永不过期，则为 null。
nameStringnull密钥的人类可读名称
uidString不适用用于识别 API 密钥的 UUID v4。如果未指定，Meilisearch 将自动生成。
descriptionStringnull密钥的可选描述

​
示例

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

​
更新密钥

PATCH
/keys/{key_or_uid}

更新 API 密钥的 name 和 description。

密钥的更新是部分更新。这意味着您只需提供要更新的字段，因为有效负载中不存在的任何字段都将保持不变。

​
路径参数

需要有效的 API key 或 uid。

名称类型描述
key *String请求的 API 密钥的 key 值
uid *String请求的 API 密钥的 uid

​
请求体

名称类型默认值描述
nameStringnull密钥的人类可读名称
descriptionStringnull密钥的可选描述

​
示例

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

​
响应: 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
/keys/{key_or_uid}

删除指定的 API 密钥。

​
路径参数

需要有效的 API key 或 uid。

名称类型描述
key *String请求的 API 密钥的 key 值
uid *String请求的 API 密钥的 uid

​
示例

curl \
  -X DELETE 'MEILISEARCH_URL/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

​
响应: 204 No Content