API 密钥

API 密钥用于在你的应用与 Hindsight API 之间进行认证。本页介绍如何通过 Hindsight Cloud 界面管理 API 密钥。

访问 API 密钥

1. 登录 Hindsight Cloud
2. 在顶部导航栏中打开 Organization 菜单并选择 API Keys

查看 API 密钥

API Keys 页面显示组织内的所有密钥：

列	说明
Name	你为密钥设置的描述性名称
Key Prefix	用于识别的前几位字符
Created	密钥创建时间
Last Used	使用此密钥的最近一次 API 调用
Expires	过期时间（若已设置）
Status	Active（活动）或 Revoked（已撤销）

筛选密钥

使用 Active only 复选框：

• 勾选 - 仅显示活动密钥（默认）
• 取消勾选 - 显示包括已撤销在内的所有密钥

已撤销的密钥以灰色显示并带有 "Revoked" 标记。

创建 API 密钥

所需权限

仅 Owner（所有者） 和 Admin（管理员） 可以创建 API 密钥。Member（成员）可查看密钥但不能创建或撤销。

1. 点击 Create API Key
2. 为密钥输入 Name（例如 "Production Server"、"CI/CD Pipeline"）
3. 选择 Expiration 期限：

选项	说明
Never	密钥永不过期
1 hour	用于测试的短期密钥
1 day	临时访问
7 days	每周轮换
30 days	每月轮换
90 days	每季度轮换
1 year	每年轮换
Custom	输入具体天数

4. 可选：将密钥限定为特定记忆库
5. 点击 Create

创建之后

请立即复制密钥

你的 API 密钥在创建后 仅显示一次。请立即复制并安全存储。

如果丢失，你需要创建一个新的。

对话框将显示：

• 完整 API 密钥（点击复制）
• 安全存储说明
• Close 按钮

限定记忆库范围的密钥

默认情况下，API 密钥可以访问你组织中的所有记忆库。你可以限制密钥仅访问特定记忆库，以缩小密钥泄露时的影响范围。

创建限定记忆库范围的密钥

1. 创建密钥时勾选 Restrict to specific banks
2. 从列表中选择一个或多个记忆库
3. 点击 Create

该密钥将仅能访问所选记忆库。访问其他任何记忆库的请求都将返回 403 Forbidden 错误。

查看记忆库范围

每张密钥卡显示其记忆库范围：

• All banks —— 不受限的访问
• Bank: my-bank —— 限定单个记忆库
• Banks: bank-1, bank-2, ... —— 限定多个记忆库

编辑记忆库限制

要更改密钥可访问的记忆库：

1. 在某个活动密钥卡上点击 Edit（铅笔图标）
2. 勾选或取消勾选 Restrict to specific banks
3. 更新记忆库选择
4. 点击 Save

备注

已撤销、已过期或通过编程方式创建的密钥无法编辑记忆库限制。通过 编程 API 创建的密钥是不可变的——请撤销后重新创建。

使用场景

场景	推荐范围
使用单个记忆库的生产服务	限定为该单个记忆库
针对特定环境的 CI/CD 管线	限定为预发/测试记忆库
管理所有记忆库的管理工具	不限制（所有记忆库）
每个代理一个 MCP 连接	限定为该代理的记忆库

编程方式创建密钥

具备 create_scoped_keys 能力的 API 密钥可以通过 API 编程方式创建、列出和撤销限定记忆库范围的子密钥。这对需要在无需管理员/UI 访问的情况下，为短期、最小权限场景配置密钥的集成和代理非常有用。

前置条件

Owner 或 Admin 必须先创建一个启用了创建受限密钥能力的父级 API 密钥：

1. 进入 API Keys 页面
2. 点击 Create API Key
3. 输入名称（例如 "Key Creator - CI/CD"）
4. 设置过期时间
5. 可选 限定为特定记忆库
6. 在 Capabilities 下勾选 Allow creating scoped child keys
7. 点击 Create

具有此能力的密钥在 API Keys 列表中显示 Key Creator 徽章。编程方式创建的密钥显示 Created by <parent key name> 徽章。

创建限定范围的密钥

使用 Authorization: Bearer <parent-key> 来创建子密钥：

curl -X POST https://api.hindsight.vectorize.io/v1/api-keys/scoped \
  -H "Authorization: Bearer <parent-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent - Task 42",
    "allowed_bank_ids": ["bank-a"],
    "expires_in_days": 7,
    "metadata": {"agent_id": "task-42"}
  }'

约束：

• allowed_bank_ids 是必填（至少一个记忆库），且必须是父密钥记忆库范围的子集
• expires_in_days 是必填（最多 365 天），且不能超过父密钥的过期时间
• 子密钥永远不会获得 create_scoped_keys 能力——只有管理员创建的密钥才能再创建其他密钥
• 子密钥不可变——创建后无法编辑记忆库范围。请撤销后重新创建。

列出限定范围的密钥

列出调用方密钥所创建的所有密钥：

curl https://api.hindsight.vectorize.io/v1/api-keys/scoped \
  -H "Authorization: Bearer <parent-key>"

返回密钥元数据（id、name、prefix、记忆库范围、过期时间等），但绝不会返回原始密钥。

撤销限定范围的密钥

按 ID 撤销子密钥：

curl -X DELETE https://api.hindsight.vectorize.io/v1/api-keys/scoped/<key-id> \
  -H "Authorization: Bearer <parent-key>"

你只能撤销由你父密钥所创建的密钥。

使用场景

场景	方法
为 CI/CD 每个任务配置密钥	父密钥为每个任务创建短期子密钥
多代理系统中的代理隔离	父密钥创建限定到代理记忆库的子密钥
面向客户的集成令牌	父密钥创建客户专属子密钥
临时调试访问	父密钥为特定记忆库创建 1 小时子密钥

撤销 API 密钥

在以下情况撤销密钥：

• 不再需要
• 可能已被泄露
• 你正在轮换凭证

撤销密钥：

1. 在列表中找到该密钥
2. 点击 Delete（垃圾桶图标）
3. 确认撤销

撤销不可逆

已撤销的密钥无法恢复或重新激活。任何使用该密钥的应用将立即失去访问权限。

级联撤销： 撤销父密钥（具有 Key Creator 能力的密钥）会自动撤销其所有子密钥。

最佳实践

命名约定

使用能识别以下信息的描述性名称：

• 使用该密钥的应用或服务
• 环境（production、staging、development）
• 用途或所属团队

示例：

• Production API Server
• CI/CD Pipeline - GitHub Actions
• Development - Local Testing
• Mobile App - iOS

密钥轮换

定期轮换 API 密钥可提升安全性：

1. 在旧密钥过期前创建新密钥
2. 更新你的应用以使用新密钥
3. 验证新密钥工作正常
4. 撤销旧密钥

过期策略

根据安全需求选择过期时间：

使用场景	推荐过期时间
生产服务	90 天或 1 年
CI/CD 管线	30-90 天
开发/测试	7-30 天
快速调试	1 小时或 1 天

安全建议

• 绝不将密钥提交到版本控制 - 使用环境变量或密钥管理器
• 将密钥限定到特定记忆库 - 使用 限定记忆库范围的密钥 仅限每个服务所需的记忆库
• 限制密钥范围 - 为不同服务创建不同密钥
• 监控使用 - 检查 "Last Used" 以发现未授权访问
• 撤销未使用的密钥 - 移除不再需要的密钥
• 尽可能使用短期密钥 - 减少泄露时的风险