API 密钥

API 密钥用于以编程方式访问 Clouisle API，无需用户登录会话。每个密钥以其所有者用户身份进行身份验证，所有请求都应用所有者的角色权限。

访问 API 密钥

1. 点击右上角个人资料图标
2. 从用户菜单中选择 "API 密钥"
3. 或直接导航到 /app/api-keys

密钥列表显示每个密钥的名称、key_prefix（前 12 个字符）、状态（活跃 / 过期 / 已停用）、过期时间、最后使用时间以及智能体 / 工作流绑定。管理员可以按状态筛选、按名称或前缀搜索并查看所有密钥；普通用户只能查看自己的密钥。

创建密钥

服务器默认值：如果未指定，scopes 默认为 ["chat"]，rate_limit 默认为 1000。

密钥格式

clou_<64 个十六进制字符>

密钥生成为 64 个随机十六进制字符（32 字节），前缀为 clou_。仅前 12 个字符（key_prefix）以明文存储并在列表中显示；完整密钥经过哈希处理。

编辑密钥

通过 PUT /api/v1/api-keys/{id} 可以编辑：

• 名称
• 作用域（可自由替换；无仅添加规则）
• 速率限制
• 过期日期
• 活跃状态（is_active）
• 智能体 / 工作流绑定

无法编辑：密钥本身（没有轮换端点）。

停用 / 重新激活密钥

停用（撤销）会立即禁用密钥而不删除它：

• POST /api/v1/api-keys/{id}/deactivate
• POST /api/v1/api-keys/{id}/activate（重新启用）

删除密钥

DELETE /api/v1/api-keys/{id} 永久删除密钥。无需先撤销密钥。

使用 API 密钥

在 Authorization 头中包含 API 密钥：

curl -X GET "https://your-domain.com/api/v1/agents" \
  -H "Authorization: Bearer clou_your_api_key_here"

import requests

api_key = "clou_your_api_key_here"

response = requests.get(
    "https://your-domain.com/api/v1/agents",
    headers={"Authorization": f"Bearer {api_key}"},
)

访问规则：

• 密钥必须处于活跃状态且未过期
• 如果密钥绑定到智能体，则只能访问这些智能体；如果没有智能体绑定，则可以访问所有智能体
• 如果密钥绑定到工作流，则只能运行这些工作流；如果没有工作流绑定，则可以运行所有工作流
• 所有者的角色权限适用于所有请求

作用域

每个 API 密钥都带有一个 scopes 字段——一个 JSON 字符串数组（例如 ["chat"]）。作用域仅作为元数据存储：后端记录您提供的值，但身份验证不读取或强制执行作用域。没有固定的作用域枚举，没有作用域名称验证，也没有按请求的作用域检查。

默认值：如果不提供 scopes，密钥将使用默认值创建：

["chat"]

提供作用域：创建或更新密钥时，scopes 接受任何 JSON 字符串数组。示例：

["agent:read", "agent:chat", "kb:read"]

["read", "write"]

[]

更新语义：更新密钥时（PUT /api/v1/api-keys/{id}），作用域可以自由替换——没有"仅添加，从不删除"规则，也没有独立的作用域管理端点。

不存在的功能：

• 没有 model:read / model:use 或 tool:read / tool:use 作用域
• 没有通配符 * 作用域处理
• 没有作用域验证、枚举或接受的作用域名称文档
• 没有包含 required_scope / provided_scopes 的作用域必需错误负载

速率限制

rate_limit 按密钥存储（每分钟请求数；0 = 无限制；默认 1000），任何具有 apikey:create 权限的用户都可以设置。后端不强制执行，也不发出 X-RateLimit-* 响应头。

统计

GET /api/v1/api-keys/stats 返回当前用户（或管理员的所有用户）的密钥统计信息（总数、活跃、已停用、已过期）。

错误代码

当请求因身份验证或授权失败时，响应正文使用以下代码：

最佳实践

✅ 推荐做法：

• 使用描述性名称
• 设置过期日期
• 将密钥绑定到其需要的特定智能体 / 工作流
• 将密钥存储在环境变量或密钥管理器中
• 停用未使用的密钥

❌ 避免做法：

• 将密钥提交到版本控制
• 公开共享密钥
• 保持未使用的密钥处于活跃状态

故障排除

API 密钥无法使用

问题：请求因身份验证错误而失败

解决方案：

1. 验证密钥处于活跃状态（is_active）且未过期
2. 检查 Authorization 头格式：Bearer clou_...
3. 检查拼写错误——创建后仅显示前 12 个字符
4. 验证密钥是否有权访问目标智能体 / 工作流
5. 如果完整密钥丢失，请创建新密钥

密钥已泄露

问题：怀疑密钥已暴露

解决方案：

1. 立即停用密钥
2. 创建新密钥并更新您的应用程序
3. 查看审计日志

相关文档

• API 参考 - API 端点参考
• 智能体管理 - 管理智能体
• 工作流 - 管理工作流