管理 API Key
管理 API Key 用于调用账户级接口，查询账户下的 API Key、用量、额度和计费数据。它不是模型调用凭证，不能用于发送模型请求。
管理 API Key 使用 mk- 前缀；普通 API Key 通常使用 sk- 前缀。两类 Key 的用途、Base URL 和可调用接口不同，请勿混用。
创建管理 API Key
管理 API Key 通过 UniGateway 控制台创建：
- 登录 UniGateway Dashboard。
- 在左侧导航栏点击 管理 Key，进入管理 API Key 页面。
- 点击页面右上角的 新建管理 Key。
- 在创建页面填写管理 API Key 名称。建议使用能够标识用途或运行环境的名称，例如
billing-export或production-audit。 - 点击 创建 Key。
- 创建成功后，使用 复制 按钮复制完整 Key，并立即保存到受控的密钥存储或服务端环境变量中。
重要：管理 API Key 的完整值仅在创建成功页面显示一次。 离开该页面或点击 完成 后，控制台不会再次显示或提供原始 Key。未复制、未保存或丢失完整 Key 时，无法恢复原值；请重新创建管理 API Key，并在确认新 Key 可用后删除不再使用的 Key。
配置管理 API Key
管理 API Key 只能保存在服务端环境变量或受控的密钥管理服务中。不要将真实 Key 写入浏览器前端代码、日志、公开仓库、截图、工单或导出文件。
Bash 或兼容 shell：
export UNIGATEWAY_MANAGEMENT_KEY="<YOUR_UNIGATEWAY_MANAGEMENT_KEY>"
Windows PowerShell：
$env:UNIGATEWAY_MANAGEMENT_KEY = "<YOUR_UNIGATEWAY_MANAGEMENT_KEY>"
调用账户级接口时，将该变量作为 Bearer token：
Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY
账户级接口使用 https://unigateway.ai 作为 Base URL，不使用模型 API 的 https://api.unigateway.ai Base URL。
管理 API Key 与普通 API Key
| Key 类型 | 主要用途 | Base URL | 示例环境变量 |
|---|---|---|---|
管理 API Key（mk-） | 查询账户 API Key、用量、额度和计费数据 | https://unigateway.ai | UNIGATEWAY_MANAGEMENT_KEY |
普通 API Key（sk-） | 调用模型接口；查询当前 Key 自身的额度、限制和用量 | 模型接口：https://api.unigateway.ai/v1；自身查询：https://unigateway.ai | UNIGATEWAY_API_KEY |
管理 API Key 不能调用 GET /v1/models 或其他模型接口。普通 API Key 可以调用模型接口，也可以通过 GET /v1/api-key 和 GET /v1/usage 查询当前 Key 自身的数据，但不能查询同一账户下其他 API Key 或账户范围的数据。需要查询全部 API Key 的数据时，请使用管理 API Key。
验证管理 API Key
创建并配置管理 API Key 后，在加载该环境变量的服务端环境执行账户 API Key 列表请求：
Example request
Run it in your stack
Pick the SDK style that matches your app and copy the snippet directly into your project.
curl -G https://unigateway.ai/v1/account/api-keys \
-H "Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY" \
--data-urlencode "limit=1" \
--data-urlencode "offset=0"curl -G https://unigateway.ai/v1/account/api-keys \
-H "Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY" \
--data-urlencode "limit=1" \
--data-urlencode "offset=0"
请求返回 200 OK 且响应包含 items、total 和分页字段时，表示管理 API Key 可用于账户级接口。响应不会返回任何完整 API Key 或 Key Hash。
轮换与删除
管理 API Key 需要轮换或怀疑泄露时，按以下顺序操作：
- 在管理 API Key 页面创建新的管理 API Key，并在创建成功页面复制完整值。
- 将新值更新到服务端环境变量或密钥管理服务。
- 重启或重新加载读取该变量的服务进程，然后重新执行上一节的验证请求。
- 确认所有账户级任务均已使用新 Key 后，在控制台删除旧 Key。
删除旧 Key 后，使用该 Key 的账户级请求会失败。删除前应先检查定时任务、报表导出和监控服务，确保它们已经加载新 Key。
安全限制
- 管理 API Key 可以读取账户范围的 API Key 元数据、用量和计费数据，应按高敏感凭证管理。
- 不要把管理 API Key 交给浏览器、移动端或不受信任的第三方服务。
- 为不同环境或自动化任务创建独立的管理 API Key，便于审计和轮换。
- 仅授予需要账户范围查询的服务使用管理 API Key；日常模型调用和单个普通 API Key 的自身用量查询应使用对应的普通 API Key。
- 发现 Key 出现在代码仓库、日志、截图或共享文档中时，应立即创建新 Key、更新服务配置并删除旧 Key。
常见问题
Q: 创建后没有复制管理 API Key，如何处理？
完整 Key 只在创建成功页面显示一次，控制台不会恢复原值。请重新进入管理 API Key 页面创建新 Key，在成功页面点击 复制，保存到服务端环境变量 UNIGATEWAY_MANAGEMENT_KEY 或受控密钥管理服务，然后按验证管理 API Key重新请求。确认旧 Key 未被使用后将其删除。
Q: 使用管理 API Key 调用模型接口为什么失败？
这是凭证用途不匹配。确认模型请求使用普通 API Key，并将 Base URL 设置为 https://api.unigateway.ai/v1；管理 API Key 仅用于账户级接口，不能调用模型接口。
Q: 使用普通 API Key 调用账户管理接口返回 401，如何处理？
如果要查询账户下全部 API Key、其他 Key 的用量或账户计费数据，检查 Authorization 头是否使用了 UNIGATEWAY_MANAGEMENT_KEY，且变量值为当前有效的 mk- Key。确认请求地址以 https://unigateway.ai 开头，修正环境变量后重启或重新加载服务进程，再执行 GET /v1/account/api-keys?limit=1&offset=0 验证。普通 sk- API Key 仍可使用 GET /v1/api-key 或 GET /v1/usage 查询自身数据，但不能调用账户范围的管理接口。
Q: 管理 API Key 已泄露，如何处理？
立即在控制台创建新的管理 API Key，复制并保存新值，更新所有使用 UNIGATEWAY_MANAGEMENT_KEY 的服务，重启或重新加载这些服务并执行账户 API Key 列表请求验证。验证成功后删除旧 Key，并清理已经公开的日志、截图、导出文件和共享文档副本。