指南

快速开始

使用 RunAPI Management Key 创建和治理标准 API Key 与 Guardrail。

Platform Management 让账户管理员通过 API 创建、查看、更新和撤销标准 API Key 与 Guardrail，不必每次都进入控制台操作。

创建 Management Key

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

HTTP

Authorization: Bearer YOUR_MANAGEMENT_KEY

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

列出标准 API Key

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

SHELL

curl "https://runapi.ai/api/v1/keys" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY"

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

创建并轮换密钥

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

SHELL

curl -X POST "https://runapi.ai/api/v1/keys" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production worker"}'

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

应用 Guardrail

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

处理管理错误

401 Unauthorized 表示凭据缺失、格式错误、已撤销或无效。
403 Forbidden 表示凭据类别或账户角色不能执行该操作。
404 Not Found 表示当前已验证账户看不到请求的资源。
422 Unprocessable Content 表示一个或多个提交值违反 resource rule。