> ## 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 概述

> 通过接口管理组织成员、邀请、项目与推理 API 密钥，并查询账单、用量与审计日志。

Kimi Admin API 让组织管理员通过接口管理成员、邀请、项目与推理 API 密钥，并查询账单、用量与审计日志——无需登录控制台。它是管理面 API：Admin API 凭证不能调用任何推理端点，推理 API key 也不能调用本 API。

> [!NOTE]
>
> Admin API 当前处于 **Beta** 阶段，面向已完成企业认证的组织开放。在「控制台 → 组织管理 → 组织认证」完成企业认证后，组织管理员即可在「组织管理 → Admin API Keys」自助创建 Admin Key。

服务地址为 `https://api.moonshot.cn`，本文所有端点路径均以 `/v1/admin/organizations` 开头。

## 身份验证

以 Bearer 方式发送 Admin API secret（`sk-admin-*`）：

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

每个 Admin API 密钥 固定绑定一个组织；组织永远从 key 推导——结构上不可能跨组织访问。key 的持有者退出组织或被注销后，key 即失效（软删、轮换、owner 失效与组织状态变更均在 ≤30 秒内生效，认证缓存 TTL 与全平台一致）。secret 仅在创建或轮换时展示一次，请妥善保存。每个组织最多同时持有 10 把未删除 Admin API key。

## 作用域（scope）

每个 Admin API 密钥 在创建时选定权限域：

| scope | 类型 | 覆盖范围 |
| - | - | - |
| `billing:read` | 只读 | 日/产品账单、请求明细、中断请求、账户余额、用量聚合 |
| `org:read` | 只读 | 成员、邀请、项目、项目成员、推理 API 密钥 元数据、项目消费预算、组织速率限制 |
| `org:write` | 写 | 组织成员与邀请、项目与项目成员、推理 API 密钥、项目支出限额的写操作（隐含 `org:read`，但不隐含 `billing:read` 或 `audit:read`） |
| `audit:read` | 只读 | 审计日志事件 |
| `all` | 读+写 | 以上全部；未来新增权限域自动覆盖 |

## 角色权限

| 角色 | 范围 | 权限差异 |
| - | - | - |
| `admin`（组织） | 组织 | 组织管理全权限：成员/邀请/项目/推理 API 密钥/组织设置/消费预算/组织速率限制/Admin Key 管理 |
| `member`（组织） | 组织 | 组织内资源使用；具体项目权限由项目内角色决定（可被加为项目 admin/member） |
| `admin`（项目） | 项目 | 项目内管理：项目成员/推理 API 密钥/项目预算与限速/项目更新与归档 |
| `member`（项目） | 项目 | 项目内资源使用（推理调用与项目查看） |

组织角色与项目角色同名但含义不同：字段描述中的 `role` 按资源区分——组织成员接口返回组织角色，项目成员接口返回项目角色。通过 API 可授予的角色仅限 `admin` / `member` 两种。

写端点额外要求 key 持有者在调用时仍是组织管理员，且适用更严格的限流（见下）。

## 速率限制

| 类别 | 限制 |
| - | - |
| 读端点 | 60 次/分钟/组织×端点（v2） |
| 写端点 | 20 次/分钟/组织×端点（v2） |
| 请求明细、中断请求、用量聚合 | 5 并发/组织×端点 |

限流按「组织 × 端点」计数（v2 全部端点）：同一组织下的所有 Admin Key 共享限额，多把 key 不会获得更高配额。v1 冻结四件（`/v1/organizations/billings/*`）保持 key × 端点粒度：读 60 次/分钟/key、明细并发 5/key。超限返回 `429 rate_limit_exceeded` / `concurrency_limit_exceeded`。**所有端点均可能返回 429，各端点页不再重复罗列**；响应暂不提供 `Retry-After` 头，建议指数退避重试（如 1s/2s/4s/8s）。排障请携响应中的 `request_id` 联系平台。

## 响应格式

成功响应按资源形态：单对象端点（组织信息、单成员、账户、限速、预算、单个邀请/key/项目等）直接返回对象本体（无信封）；集合端点返回 `data` 数组；分页端点在此基础上额外返回 `has_more` 与 `next`。写操作返回操作后的对象；删除操作返回 `deleted=true` 及对应资源 ID（uid/key 等，以各端点 Schema 为准）。

## 分页

分页端点（日/产品账单、请求明细、中断请求、用量聚合、审计日志）使用游标分页：响应携带 `has_more` 与 `next`；将 `next` 作为 `cursor` 查询参数传回即可翻页。页大小按端点：日/产品账单与用量聚合默认 100、最大 1000；请求明细与中断请求默认 100、最大 10000；审计日志默认 20、最大 100。游标只携带页位置——翻页时请原样重复全部过滤参数；**过滤条件变化时必须从第一页重新查询，不得复用旧游标**（服务端不校验参数一致性，复用会跨查询串页）。`limit` 可按需调整。

组织集合端点（成员、邀请、项目、项目成员、推理 API 密钥）一次性全量返回，无分页参数。协议之外的查询参数（如 `page_size`）会被静默忽略，请核对参数名。

## 错误格式

错误响应遵循统一格式。本文档收录的错误码均为公开 Admin API 端点可达的码；控制台管理页（Admin Key 签发等门户链路）的错误提示以页面展示为准，不在本体系：

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date_range",
    "message": "end must be greater than start.",
    "param": "end",
    "request_id": "..."
  }
}
```

`data_not_ready` 专用于账单类端点的数据就绪规则：T 日数据于 T+1 日 07:00（UTC+8）起可查。

## 数据口径

* 金额单位为毫分（1 元 = 100,000 毫分）。
* 时间窗左闭右开、按 CST 日界（Asia/Shanghai，UTC+8）；查询参数中的时间必须为 **epoch 毫秒**（如 `1761379200000`），响应体中的时间为 RFC 3339（另有说明除外）。**秒级时间戳不是合法输入**（会被当作 1970 年附近的时间窗，可能返回空结果而非报错），请核对单位为毫秒。
* T 日数据于 T+1 日 07:00（UTC+8）起可查；此前返回 `400 data_not_ready`；中断请求明细不受此限（近实时可查）。
* 数据留存与窗口：日/产品账单留存 365 天（窗口上限 = 留存期）；请求明细与中断请求留存 90 天、单次窗口 ≤31 天；审计日志单次窗口 ≤31 天；用量聚合窗口按粒度分档（`1m` ≤24 小时、`1h` ≤31 天、`1d` ≤93 天）。