API Key 管理
Token 格式、创建流程、8 个权限范围（scopes）、生命周期、用量分析、安全最佳实践。
API Key 是您与 Braidrun 开放平台对话的唯一凭据。每个 Key 携带一组 scope（权限范围）和一个 Token，丢失或泄漏时立即吊销新建。
Token 格式
text
dyk_<id>_<secret>
例：dyk_a3b9c8d7e6f5a1b2_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789dyk_— 品牌前缀，让 git secret-scanning / 日志脱敏工具可识别<id>— 16 字符 base62 公开 ID，可用作 lookup key（不敏感）<secret>— 32 字节随机 secret，base64url 编码（敏感，不得上传日志 / 报错信息）
Token 只展示一次
生成 API Key 时，原始 Token 只在创建对话框中展示一次。关闭后服务端只保留 Argon2id 哈希，无法回查原文。请立即复制保存到您的密钥管理工具（1Password / Vault / Doppler / GitHub Secrets / etc）。
创建 API Key
- 访问 控制台 → 账号设置 → API 密钥
- 点击「新建 API Key」
- 填入：名称（用于辨识）、scope 列表、有效期（永久 / 30 天 / 90 天 / 1 年）
- 点击「生成密钥」→ 立即复制 Token
权限范围（Scopes）
Scope 是细粒度权限，共 8 个：7 个可自助授予，CLUSTER_ADMIN 仅限管理员。给一个 Key 授予的越少越好，最小权限原则。
| Scope | 能做什么 | 典型场景 |
|---|---|---|
WEBHOOK_TRIGGER | 触发绑定到该 Key 的 Webhook | GitHub Push → 工作流；上游业务系统回调 |
APPROVAL_RESPOND | 批准 / 拒绝 manual_approval 步骤 —— 覆盖审批 Webhook 与 v1 审批端点（/api/v1/approvals/*，含列出待审批、读取详情、提交编辑后的审批表） | 邮件 / Slack 一键审批链接；外部审批系统对接 |
WORKFLOW_READ | 列出 / 读取工作流定义 | 在外部 dashboard 中展示当前工作流列表 |
WORKFLOW_EXECUTE | 通过 API 启动工作流（替代 Webhook 模式） | SDK 集成；自动化测试；批处理任务 |
EXECUTION_READ | 查询执行状态 / 读取完整 result | 回流执行结果到企业 BI / 数据仓库 |
EXECUTION_CANCEL | 取消运行中的执行 | 管理面板的「停止」按钮 / 紧急熔断 |
ARTIFACT_READ | 列出执行产物 / 获取下载链接 | 归档报表到对象存储；推送结果到下游系统 |
CLUSTER_ADMIN | 管理员专用：读取集群状态、管理自动扩缩容策略。只有管理员能授予；非管理员创建 Key 时该 scope 会被自动剥离 | 私有化部署的运维服务账号 |
生命周期
- 创建 — 用户自助；scope + 有效期由您决定
- 使用 — 每次成功调用都自动累计用量并更新 lastUsedAt 时间戳
- 吊销 — 用户随时可在「API 密钥」页面点「吊销」；幂等
- 过期 — expiresAt 一到立即失效；不需要主动吊销
用量分析
每个 Key 在「API 密钥」表格里点「使用情况」会弹出图表分析：
- 累计调用次数 + 窗口内（7/30/90/180 天可选）
- 峰值日（哪一天调用最多）
- 每日调用次数折线图
- 调用端点分布饼图（webhook.trigger / workflow.execute / etc）
- 最近一次使用时间
用量仅统计成功响应（HTTP 2xx）。鉴权失败 / 速率限制的请求不计入。
密钥安全最佳实践
请遵守
- 每个环境（生产 / 预发 / 本地）使用独立 Key —— 出事时只吊销受影响的环境
- 每个外部集成方使用独立 Key —— 用「使用情况」看哪个集成在用
- 永远不要把 Token 提交到代码仓库
- 在 CI/CD 中以加密 Secret 形式注入；不要打印到日志
- 观察到「最近使用」时间和您预期不符 → 立即吊销并查日志
- 给短期合作伙伴的 Key 务必设置 expiresAt（建议 90 天以内）