快速开始

按照身份验证指南登录，然后打开 Management Keys 页面创建 Management Key，并将它与标准应用密钥分开保存。只在 Platform Management 请求中以 bearer token 形式发送它。

标准 API Key 不能调用密钥或 Guardrail 管理端点。Management Key 即使有效，如果所有者不再拥有要求的账户角色，也会收到 403 Forbidden。

使用 GET /api/v1/keys 查看 Management Key 所属账户可见的密钥：

后续查询、更新、撤销或 Guardrail assignment 请求应使用返回的公开 identifier。不要根据密钥名称或 masked token 推断访问权限。

使用 POST /api/v1/keys 创建应用密钥。完整 secret 只会在 create response 中返回一次，因此丢弃响应前必须把它存入密钥管理系统。轮换时先创建替代密钥，将它部署到应用并验证流量，最后再撤销旧密钥。

credit_limit_windows 可按需组合 1h、1d、7d 三个滚动支出窗口。任一已配置窗口用尽后，该密钥的调用会返回 429 Too Many Requests，直到消费记录移出窗口。更新密钥时发送空对象可清除全部滚动窗口。

创建请求省略全部额度字段和 guardrail_id 时，新密钥使用工作区 Governance Defaults。显式额度、滚动窗口或 Guardrail 优先，不会附加默认总额度。传入 credit_limit_cents: null 可明确不设原生总额度。指定金额但省略重置周期时，仍表示终身额度。更新密钥不会重新套用默认值，修改默认值也不会追改已有密钥。

创建和更新支持 tags：由完整 key:value 字符串组成的数组。列表、查询、创建和更新响应均返回完整数组。PATCH 提交标签会替换整个数组，不传 tags 则保留原值。key 长度为 1–32、value 为 1–64，只能有一个冒号且不能含空白；含预设在内最多 20 个不同标签。格式错误或预设冲突返回 422 和明确的标签错误；非数组或非字符串元素返回 400。

用途必须且只能有一个：usage:developer 或 usage:service。Management API 新建时未指定用途（包括 tags: []）默认添加 usage:service；Dashboard 新建及更新未指定用途时默认 usage:developer。存量密钥迁移为 Developer。环境可选，至多一个：env:production、env:staging、env:dev，不接受 env:prod。

Dashboard 创建和编辑支持用途、环境快捷选择，以及自定义标签和仅来自当前工作区未撤销标准密钥的建议。列表只显示 value，悬停显示完整标签。标签不改变密钥所有权、可见性或权限。标签可使密钥的消费计入共享标签预算。

工作区管理员在 Team 页的成员预算表单中设置成员必带标签。必带标签区分大小写，只允许 team:growth 等自定义标签，不能使用 usage: 或 env: 命名空间。每位成员最多配置 19 个必带标签，每个 Key 仍受总数 20 个标签的限制。

该成员在此工作区新建的每个标准 Key 都会自动带上必带标签。创建时先将提交标签与必带标签取并集，再校验格式和数量。例如，成员配置了 team:growth，Management API 创建时传入 tags: ["project:chatbot"]，响应会包含 project:chatbot、team:growth 及默认的 usage:service。

PATCH 显式提交 tags 时，必须保留全部必带标签。即使调用者是管理员，移除必带标签也会返回 422，校验错误会列出缺少的标签。不传 tags 则保留原值。成员仍可增删普通标签。

管理员须在 Team 修改成员配置来撤销必带标签。保存后，新必带标签会补齐到该成员已有的所有标准 Key，撤销的必带标签会从这些 Key 移除，其他标签保留。停用和过期 Key 也会同步，已删除 Key 不变。任一 Key 无法保存最终标签集合时，整个表单保存失败，错误会指出需要先处理的 Key。

标签预算按 Key 当前标签统计。修改必带标签也会改变本期已有消费的预算归属，新增标签可能立即耗尽对应标签预算。现有成员的必带标签默认为空，管理员保存配置前不会改变已有 Key。

Guardrail 是账户级可复用策略，用于控制模型、Provider 与支出。通过 /api/v1/guardrails 管理策略，再使用 /api/v1/guardrail_assignments 绑定或移除策略。Assignment 被拒绝时，应将其作为策略或 ownership failure 处理，不能静默地在没有 Guardrail 的情况下继续。

先创建总额为正且 credit_limit_behavior 为 "block" 的 Guardrail，再向 /api/v1/guardrail_assignments POST {"guardrail_id": "guardrail_abc123", "tag": "dept:ml"}。tag、api_token_id、account_user_id 必须且只能提供一个。标签分配的创建、查看和删除仅限账户管理员。非管理员列表仅包含自己密钥上的分配。

标签沿用标准 API Key 区分大小写的 key:value 格式。没有密钥时也可提前创建池，每个账户的同名标签只有一个池。多标签密钥必须通过每个池的检查。停用的 Guardrail 不执行限制。标签预算拒绝返回 HTTP 403，消息包含标签名。Management 配置请求不消耗预算。

池按密钥当前标签聚合，包含软删除、停用和过期标准密钥的历史花费。新增标签立即计入该密钥当前周期已有花费，移除标签立即移出。创建、删除或重建同名池都不会清零。页面密钥数量排除软删除密钥，花费仍包含它们。

credit_limit_reset_interval 为 null 表示终身预算，也可选择 daily、weekly、monthly，周期边界使用 UTC。只设置周期而不设置金额无效。阈值默认 80，范围为 1 至 100。直接 PATCH Guardrail 会修改引用它的全部分配，控制台标签预算编辑会复制策略后只更新该池。

准入检查完整请求预留金额。实际结算可能超过预留，使用率可以超过 100%，之后的付费请求会被阻止。UsageLog 使用日志创建时间，进行中任务预留使用任务创建时间，Batch 使用其创建时间。因此旧周期受理的任务可能在新周期结算。