# API 密钥
Typesense 允许您创建具有细粒度访问控制的 API 密钥。您可以按集合、操作、记录甚至字段级别来限制访问，或者这些限制的组合。
了解更多关于如何在 Typesense 中管理数据访问的信息，请参阅这篇专门指南文章。
WARNING
我们将使用您启动 Typesense 时设置的初始引导密钥（通过 --api-key）来创建其他密钥。强烈建议您不要在生产应用程序中直接使用引导 API 密钥。相反，您应该为当前应用程序生成一个具有适当范围的密钥。
# 创建 API 密钥
# 管理员密钥
首先，我们来创建一个拥有所有操作权限的 API 密钥，这实际上是一个管理员密钥，等同于你启动 Typesense 时使用的密钥（通过 --api-key 参数）。
通过将 actions 和 collections 都设置为通配符 ['*'] 范围，我们就能创建一个拥有全局访问权限的管理员密钥。不过，你应该避免创建这种范围过大的密钥。
WARNING
生成的密钥仅在创建时返回一次。请务必将此密钥妥善保存在安全的地方。
# 仅搜索 API 密钥
现在让我们看看如何创建一个仅限搜索的密钥，该密钥可以将操作范围限制为仅搜索操作，并且仅针对特定集合。
通过将 actions 范围设置为 ["documents:search"] 并将 collections 范围设置为 ["companies"]，我们可以生成一个仅允许在 companies 集合上执行搜索操作的密钥。
# 示例响应
集合名称可以包含正则表达式。例如，如果您有多个以 org_ 开头的集合，并希望为它们设置一个通用密钥，可以这样定义权限：
{
"description": "用于搜索组织集合的密钥。",
"actions": [
"documents:search"
],
"collections": [
"org_.*"
]
}
# 定义
POST ${TYPESENSE_HOST}/keys
# 参数
| 参数名 | 是否必填 | 描述 |
|---|---|---|
| actions | 是 | 允许的操作列表。具体可选值请参考下表。 |
| collections | 是 | 该 API 密钥适用的集合列表。支持正则表达式。例如：coll.* 会匹配所有名称中包含 "coll" 的集合。 |
| description | 是 | 用于标识密钥用途的内部描述 |
| value | 否 | 默认情况下，当不指定此参数时，Typesense 会自动生成一个随机密钥。如果需要使用特定字符串作为密钥，可以在创建时通过此参数指定。 |
| expires_at | 否 | 密钥有效的 Unix 时间戳 (opens new window) 截止时间 |
| autodelete | 否 | 自动删除过期密钥。此操作每小时执行一次。默认值：false |
# 示例操作
以下是一个_示例_操作列表。
通常，我们建议使用 资源:操作 的格式来表示一个动作，其中 操作 可以是以下之一：create（创建）、delete（删除）、get（获取）、list（列出）、search（搜索）或 *（全部）。
# 集合操作
| 操作 | 描述 |
|---|---|
collections:create | 允许创建集合。 |
collections:delete | 允许删除集合。 |
collections:get | 允许获取集合的 schema。 |
collections:list | 允许获取所有集合的 schema。 |
collections:* | 允许所有与集合相关的操作。 |
# 文档操作
| 操作 | 描述 |
|---|---|
documents:search | 仅允许搜索请求。 |
documents:get | 允许获取单个文档。 |
documents:create | 允许创建文档。 |
documents:upsert | 允许更新或插入文档。 |
documents:update | 允许更新文档。 |
documents:delete | 允许删除文档。 |
documents:import | 允许批量导入文档。 |
documents:export | 允许批量导出文档。 |
documents:* | 允许所有文档相关操作。 |
# 别名操作
| 操作 | 描述 |
|---|---|
aliases:list | 允许获取所有别名 |
aliases:get | 允许检索单个别名 |
aliases:create | 允许创建别名 |
aliases:delete | 允许删除别名 |
aliases:* | 允许所有别名操作 |
# 同义词操作
| 操作 | 描述 |
|---|---|
synonyms:list | 允许获取所有同义词 |
synonyms:get | 允许检索单个同义词 |
synonyms:create | 允许创建同义词 |
synonyms:delete | 允许删除同义词 |
synonyms:* | 允许所有同义词操作 |
# 覆盖规则操作
| 操作 | 描述 |
|---|---|
overrides:list | 允许获取所有覆盖规则 |
overrides:get | 允许检索单个覆盖规则 |
overrides:create | 允许创建覆盖规则 |
overrides:delete | 允许删除覆盖规则 |
overrides:* | 允许所有覆盖规则操作 |
# 停用词操作
| 操作 | 描述 |
|---|---|
stopwords:list | 允许获取所有停用词集 |
stopwords:get | 允许检索单个停用词集 |
stopwords:create | 允许创建停用词集 |
stopwords:delete | 允许删除停用词集 |
stopwords:* | 允许所有停用词相关操作 |
# API密钥操作
| 操作 | 描述 |
|---|---|
keys:list | 允许获取所有密钥的元数据 |
keys:get | 允许获取单个密钥的元数据 |
keys:create | 允许创建API密钥 |
keys:delete | 允许删除API密钥 |
keys:* | 允许所有API密钥相关操作 |
# 分析操作
| 操作 | 描述 |
|---|---|
analytics:list | 允许获取所有分析规则 |
analytics:get | 允许获取单个分析规则 |
analytics:create | 允许创建分析规则和事件 |
analytics:delete | 允许删除分析规则和事件 |
analytics:* | 允许所有分析规则和事件相关操作 |
# 分析规则操作
| 操作 | 描述 |
|---|---|
analytics/rules:list | 允许获取所有分析规则。 |
analytics/rules:get | 允许获取单个分析规则。 |
analytics/rules:create | 允许创建分析规则。 |
analytics/rules:delete | 允许删除分析规则。 |
analytics/rules:* | 允许所有与分析规则相关的操作。 |
# 分析事件操作
| 操作 | 描述 |
|---|---|
analytics/events:create | 允许创建分析事件。 |
# 其他操作
| 操作 | 描述 |
|---|---|
metrics.json:list | 允许访问 metrics 端点。 |
stats.json:list | 允许访问 stats 端点。 |
debug:list | 允许访问 /debug 端点。 |
* | 允许所有操作。 |
# 获取 API 密钥
检索（关于）密钥的元数据。
# 示例响应
请注意，当您检索密钥时只会返回密钥前缀。出于安全原因，只有创建端点会返回完整的 API 密钥。
# 定义
GET ${TYPESENSE_HOST}/keys/:id
# 列出所有密钥
获取所有密钥的（元数据）信息。
# 示例响应
请注意，在检索密钥时只返回密钥前缀。出于安全原因，只有创建端点会返回完整的 API 密钥。
# 定义
GET ${TYPESENSE_HOST}/keys/
# 删除API密钥
根据ID删除指定的API密钥。
# 示例响应
# 定义
DELETE ${TYPESENSE_HOST}/keys/:id
# 生成限定范围的搜索密钥
您可以生成嵌入了搜索参数的限定范围搜索API密钥。这在以下几种场景中非常有用：
- 当您在单个Typesense集合中索引来自多个用户/客户的数据（即多租户场景）时，可以创建带有嵌入式
filter_by参数的限定搜索密钥，这些密钥仅允许用户访问他们自己的数据子集。 - 您可以嵌入任何搜索参数（例如
exclude_fields或limit_hits），以防止用户能够在客户端修改这些参数。
当您在搜索API调用中使用这些限定搜索密钥时，Typesense会自动应用您嵌入其中的参数，用户将无法覆盖这些参数。
# 示例
让我们以在单个集合中存储多个用户数据的第一个用例为例。
- 首先，您需要在集合中的每个文档添加一个名为
accessible_to_user_ids的数组字段，列出所有应该有权访问该文档的用户ID。 - 然后，当某个用户（例如
user_id: 1）访问您的搜索界面时，您需要（在后端服务器上）为他们生成一个唯一的限定范围搜索API密钥，并嵌入一个过滤器参数filter_by: accessible_to_user_ids:=1。
当使用这个限定范围的搜索API密钥发起搜索请求时，Typesense 会自动应用 filter_by 条件，因此用户实际上只能搜索到 accessible_to_user_ids 字段中包含他们自己用户ID的文档。
假设您还希望用户无法知道有权访问文档的完整用户ID列表，您还可以在限定范围的API密钥中嵌入 exclude_fields: accessible_to_user_ids 参数，这样该字段就不会出现在响应结果中。
# 基于角色的访问控制 高级
让我们考虑另一个场景：一个组织拥有许多用户，每个用户可以属于一个或多个角色（例如：管理员、销售、支持等）。您可以将所有组织和用户的数据记录/文档存储在单个集合中，然后使用 Scoped API 密钥有条件地允许已登录用户仅搜索其所属组织的数据，并且只能访问其角色权限范围内的数据子集。
- 首先，您需要在集合中的每个文档添加一个名为
accessible_to_organization_id的字段。 - 再添加一个数组字段
accessible_to_roles到每个文档中，列出该组织内有权访问此文档的所有角色。 - 使用 API Keys 端点为每个组织生成一个父级搜索 API 密钥。
- 当属于
organization_id: 1且角色为sales和marketing的用户登录时，您可以使用该组织的父级搜索 API 密钥生成一个 Scoped API 密钥，并嵌入过滤器filter_by: accessible_to_organization_id:=1 && accessible_to_roles:=[sales,marketing]。
当使用这个 scoped 搜索 API 密钥发起搜索请求时，Typesense 会自动应用 filter_by 条件，因此用户实际上只能搜索那些文档中列有其 organization_id 和 role(s) 的文档。
现在，如果某个用户离开组织，为了增强安全性，您可以删除该组织的父级搜索 API 密钥并生成一个新的密钥，之后为新登录的用户使用新密钥生成 scoped 搜索 API 密钥。一旦父级搜索 API 密钥被撤销，所有基于它生成的 scoped API 密钥都会自动失效。
TIP
一旦父级搜索 API 密钥被撤销，所有基于它生成的 scoped API 密钥都会自动失效。
# 使用方法
我们可以无需向 Typesense 服务器发起任何请求，就能生成限定范围的搜索 API 密钥。
我们需要使用一个仅具备搜索权限的预生成 API 密钥，用该密钥对参数创建 HMAC 摘要，并将其作为 API 密钥使用。我们的客户端库会为您处理这一逻辑，但您也可以从命令行生成限定范围的搜索 API 密钥。
TIP
限定范围的搜索 API 密钥必须仅从父 API 密钥创建，且该父密钥除 documents:search 外不得拥有其他权限
# 示例响应
您还可以为限定范围的 API 密钥设置自定义的 expires_at。限定范围 API 密钥的过期时间应短于用于生成它的父 API 密钥的过期时间。
WARNING
如果您的集合中有文档仅允许特定用户子集访问，请记住永远不要在前端暴露您的主搜索密钥，因为暴露主搜索密钥将允许用户绕过您嵌入的搜索参数/过滤器查询所有文档。