API 密钥参考

API Key 用于程序化调用 Agent、工作流和其他受保护 API。完整密钥只在创建响应中显示一次，后续列表只显示 key_prefix。

字段

字段	类型	默认值	说明
`name`	string	必填	`1-100` 字符
`scopes`	string[]	`["chat"]`	权限作用域；列表为空表示完全访问（数据模型语义），以实际后端权限校验为准
`rate_limit`	integer	`1000`	每分钟请求数；`0` 表示无限制；`ge=0`。当前后端不强制该值，详见限额与配额
`expires_at`	datetime/null	null	null 表示永不过期
`agent_ids`	UUID[]	`[]`	空列表允许访问全部 Agent
`workflow_ids`	UUID[]	`[]`	空列表允许访问全部工作流
`is_active`	boolean	true（创建后）	禁用后认证失败

完整密钥形如 clou_ + 64 个十六进制字符（32 字节随机数的十六进制表示）。服务端把密钥的前 12 个字符作为 key_prefix 存储，用于快速定位候选 Key。请求头：

Authorization: Bearer clou_your_api_key_here

校验流程：

用前 12 字符作为 key_prefix 查询启用中的候选 Key —— 已被禁用的 Key 直接查不到，最终返回 2001（INVALID_TOKEN）。
对候选逐一比对密钥哈希，全部不匹配同样返回 2001。
校验 expires_at：已过期返回 2002（TOKEN_EXPIRED）。
校验关联用户是否存在且启用；用户未启用返回 2004（INACTIVE_USER）。
通过后更新 last_used_at，并以该用户的全局角色权限执行后续鉴权。

JWT 与 API Key 都使用 Bearer 格式，但 API Key 的资源范围由 Key 本身的绑定与所属用户权限共同限制。

创建后立即复制并存入 Secret 管理器。编辑可以修改名称、作用域、限速值、过期时间、资源范围和启用状态，但无法恢复已丢失的完整密钥。删除不可撤销；轮换应创建新 Key、迁移调用方、再禁用旧 Key。