> ## Documentation Index
> Fetch the complete documentation index at: https://platform.kimi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Admin API 进行组织管理

> 将 Admin API 接入企业现有系统，自动处理成员入离职、项目与权限管理、财务对账和安全审计。

当企业内部多个团队都在使用 Kimi API，围绕账号、权限、费用和安全的日常管理负担也会随之增加：员工入职、离职时，管理员需要调整权限、清理密钥；财务需要定期核对账单和用量；安全团队需要核查审计日志，排查异常操作等。

过去，这些工作都要在控制台手动完成，再将结果同步到企业内部系统。管理人员不仅要在两套系统之间来回切换、重复操作，也容易出现遗漏。

现在，Kimi 开放平台向企业提供「组织管理接口」 **Admin API**，方便管理员将原本要在控制台手动做的成员、项目、密钥管理以及账单用量查询，接进企业自己的系统自动执行，减少重复操作、**对账更方便、权限和密钥更好管**。

**Admin API 接口免费**，调用时不产生额外的计费项。在 [platform.kimi.com](https://platform.kimi.com) 注册并完成企业认证后，即可体验。详细的接口定义、参数和返回格式见 [Admin API 参考](https://platform.kimi.com/docs/admin-api/overview.md)。

> [!WARNING]
>
> 调用 Admin API 需使用 Admin Key，不能与模型推理 API Key 混用。

![Admin API 组织资源与数据层级总览](https://mintcdn.com/moonshotcn/diLNzUKdsnWNhM_d/assets/pics/org-admin-api/overview.png?fit=max\&auto=format\&n=diLNzUKdsnWNhM_d\&q=85\&s=a25a34b0965a483046cfeb5ec97200ea)

## 典型使用场景示例

| 场景 | 推荐 Admin API 用法 | 价值 |
| - | - | - |
| 新员工入职 | 创建组织邀请，成员接受后加入对应项目。 | 减少手工邀请和项目配置。 |
| 离职成员权限清理 | 先吊销成员名下的推理 API Key，再将其移出组织。 | 避免留下可用凭证和权限。 |
| 财务对账 | 定时将日账单、产品账单和请求明细同步到财务系统。 | 减少手工导表，方便核对费用和逐笔 token 用量。 |
| 成本分摊 | 按项目汇总账单和用量，对应到部门或业务线。 | 按团队核算费用和用量。 |
| 余额监控与充值提醒 | 定时查询账户余额，低于设定阈值时触发提醒或充值审批。 | 及时发现余额不足并安排充值。 |
| 429 错误排查 | 查询组织速率限制，并关联用量数据和业务请求日志排查原因。 | 判断是否触发限速，缩小排查范围。 |
| 安全审计 | 定期获取 Admin Key 信息和审计日志，接入内部审计流程。 | 及时发现异常操作和权限变化。 |

## 快速开始

### 完成企业认证

进入「控制台 → 组织管理 → 组织认证」完成企业认证。认证完成后，Admin API 自动开通，无需单独申请。

### 在控制台创建 Admin Key

Admin Key 只能在控制台创建。

组织管理员进入「控制台 → 组织管理 → Admin API Keys」，创建 Admin Key。创建时，按实际用途选择权限：

| 要执行的操作 | 需要选择的权限 |
| - | - |
| 查看成员、项目和推理 API Key 等信息 | 组织只读（`org:read`） |
| 管理成员、邀请、项目、项目成员和推理 API Key | 组织读写（`org:write`，已包含组织只读） |
| 查询账单、余额和用量 | 账单只读（`billing:read`） |
| 查询审计日志 | 审计只读（`audit:read`） |

如果同一 Admin Key 需要多项能力，可以同时选择对应权限。

创建后，立即复制并妥善保存完整密钥。完整密钥只在创建或轮换时显示一次，不要在代码中硬编码或与他人共享。

在终端中设置后续示例使用的环境变量：

```bash theme={null}
export MOONSHOT_ADMIN_KEY="替换为你创建的 Admin Key"
```

### 验证连接

创建 Admin Key 后，调用组织信息接口验证连接（要求 Admin Key 具备 `org:read`）。

```bash theme={null}
curl https://api.moonshot.cn/v1/admin/organizations \
  --header "Authorization: Bearer $MOONSHOT_ADMIN_KEY"
```

请求返回当前组织信息，即表示 Admin Key 可用。每个 Admin Key 固定绑定一个组织，调用时无需再填写组织 ID。

## 管理组织资源

以下写操作要求 Admin Key 具备 `org:write`，且 Key 持有者在调用时仍是组织管理员。

### 管理组织成员

通过 API 可以 [创建邀请](https://platform.kimi.com/docs/admin-api/invite-create.md) 、 [查询邀请状态](https://platform.kimi.com/docs/admin-api/invite.md) 、 [查询组织成员](https://platform.kimi.com/docs/admin-api/members.md) 、 [修改成员角色](https://platform.kimi.com/docs/admin-api/member-update-role.md) 和 [移除成员](https://platform.kimi.com/docs/admin-api/member-remove.md) 。受邀人接受邀请后，再为其配置项目权限。

移除成员前，先吊销其名下的推理 API Key。成员被移出组织后，其 Admin Key 会失效，但项目推理 API Key 不会自动吊销。

### 管理项目与预算

通过 API 可以 [创建](https://platform.kimi.com/docs/admin-api/project-create.md) 、 [修改](https://platform.kimi.com/docs/admin-api/project-update.md) 和 [归档项目](https://platform.kimi.com/docs/admin-api/project-archive.md) ，也可以 [设置项目日消费预算和月消费预算](https://platform.kimi.com/docs/admin-api/project-spend-limits-update.md) 。项目日/月消费预算按 Asia/Shanghai 自然日/月累计。达到已设置且大于 0 的预算后，该项目后续 API 请求会被拒绝；消费统计与限制生效存在延迟，延迟期间产生的费用仍需支付。

归档项目前，应确认项目中没有仍在运行的业务。

### 管理项目成员

通过 API 可以 [添加项目成员](https://platform.kimi.com/docs/admin-api/project-member-add.md) 、 [调整项目成员角色](https://platform.kimi.com/docs/admin-api/project-member-update-role.md) 和 [将成员移出项目](https://platform.kimi.com/docs/admin-api/project-member-remove.md) 。只能添加已加入组织的成员。

### 管理推理 API Key

通过 API 可以 [查询](https://platform.kimi.com/docs/admin-api/project-api-keys.md) 、 [改名](https://platform.kimi.com/docs/admin-api/api-key-rename.md) 和 [吊销](https://platform.kimi.com/docs/admin-api/api-key-revoke.md) 已有推理 API Key，但不能创建新 Key。吊销前，应根据 Key 所属项目和成员确认影响范围，避免影响仍在运行的业务。

## 查询组织数据

### 查询账单与请求明细

金额以 [日账单](https://platform.kimi.com/docs/admin-api/billing-daily-bills.md) 和 [产品账单](https://platform.kimi.com/docs/admin-api/billing-product-bills.md) 为准，适合用于财务对账和按项目分摊成本。

[请求明细](https://platform.kimi.com/docs/admin-api/billing-request-details.md) 用于查看逐笔 token 用量。

某一天的日账单、产品账单和请求明细在次日 07:00（UTC+8）起可查。 [中断请求明细](https://platform.kimi.com/docs/admin-api/billing-interrupted-requests.md) 不受这一时间限制，当天数据随写入即可查询。

### 查询用量、余额与组织限速

* [用量聚合](https://platform.kimi.com/docs/admin-api/usage.md) ：按分钟、小时或天查询 token 用量和调用次数，适合分析使用趋势和项目用量。
* [账户余额](https://platform.kimi.com/docs/admin-api/billing-account.md) ：定时查询余额，并在低于企业内部阈值时发送提醒或发起充值审批流程。
* [组织限速](https://platform.kimi.com/docs/admin-api/rate-limits.md) ：业务请求出现 429 时，先查询组织速率限制，再结合用量数据和业务请求记录，判断是否为限速所致。

### 查询审计日志

[审计日志](https://platform.kimi.com/docs/admin-api/audit-logs.md) 记录控制台管理操作、登录事件和 Admin API 操作，可用于核查异常登录、权限变更和密钥管理操作。

组织管理员需要先在控制台开启审计日志。开启后产生的事件才可查询，开启前的事件不会补记，关闭期间也不记录。

## 使用注意事项

* **管理 Admin Key 持有者**：持有者退出组织或被注销后，其 Admin Key 会失效。定期检查持有者和权限，并及时交接相关自动化任务。
* **处理 Admin API 限流**：同一组织下的所有 Admin Key 共享各接口的调用限额。调用 Admin API 收到 429 时，应逐步延长重试间隔。新增 Admin Key 不会提高限额。

## 相关文档

* [Admin API 参考](https://platform.kimi.com/docs/admin-api/overview.md)
* [使用控制台进行组织管理](https://platform.kimi.com/docs/guide/org-best-practice.md)

## 常见问题

> [accordion] Admin Key 和推理 API Key 在哪里创建？
>
> 两类 Key 都在控制台创建。组织管理员在「控制台 → 组织管理 → Admin API Keys」创建 Admin Key；推理 API Key 在「控制台 → 组织管理 → API Key 管理」创建。Admin API 可以查询、改名和吊销已有推理 API Key，但不能创建推理 API Key。

> [accordion] 吊销推理 API Key 或归档项目后，会发生什么？
>
> 吊销推理 API Key 后立即生效，使用该 Key 的模型调用会被拒绝。项目归档后，该项目下推理 API Key 的模型调用也会被拒绝。自动执行这些操作前，应确认 Key 和项目的影响范围。

> [accordion] 账单和请求明细什么时候能查？
>
> 某一天的日账单、产品账单和请求明细在次日 07:00（UTC+8）起可查；中断请求明细不受这一时间限制，当天数据随写入即可查询。

> [accordion] 怎样用请求 ID 查单笔 token 用量？
>
> 调用推理 API 时，在请求头中传入自己的请求 ID（`X-Msh-Client-Request-Id`）。按时间范围拉取请求明细后，将返回结果中的 `client_request_id` 与企业请求日志中的请求 ID 逐笔匹配，即可查看对应请求的 token 用量。
>
> 请求明细提供 token 等用量信息，不提供金额；金额以日账单、产品账单为准。请求明细和中断请求明细保留 90 天，单次查询的时间范围最多 31 天。

> [accordion] 审计日志需要提前开启吗？
>
> 需要。组织在控制台开启审计日志后，才能查询开启后产生的事件；开启前的记录不会补回，关闭期间也不记录。有审计需求的组织应在开始使用 Admin API 时同步开启。