管理服务账号、Credits 上限、长期 Key 与短期 Token。
文档说明
先阅读约定与规范和获取 API Key。本站 Base URL 为 https://api.qoder.com.cn。示例 UUID 不代表真实资源,请替换为目标组织中的实际 UUID。
服务账号(Service Account)供应用和服务调用 Qoder,不对应组织成员,也不占用成员席位。
服务账号管理 API 提供:
- 创建、查询、更新和归档服务账号;
- 设置服务账号当前账期的 Credits 用量上限;
- 创建、查询、轮转和吊销长期 Service Account Key;
- 使用长期 Key 签发短期 Service Account Token;
- 查询当前账期已使用的 Credits 和 Key 使用状态。
权限要求
组织需开通服务账号能力。不同接口使用以下凭证:
| 接口 | 认证请求头 |
|---|---|
| 服务账号及长期 Key 管理 | Authorization: Bearer <organization_api_key> |
| 短期 Token 签发 | Authorization: Bearer <service_account_key> |
API 列表
1. 创建服务账号
POST /v1/organizations/{organization_id}/service-accounts
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
organization_id | string | 是 | 组织 ID |
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 去除首尾空白后长度为 1 至 100;同一组织内唯一 |
description | string | 否 | 去除首尾空白后最长 500 个字符 |
limitAmount | float64 | 否 | -1 或有限的非负数;默认 -1 |
成功响应 (201 Created)
响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 服务账号 ID |
organizationId | string | 所属组织 ID |
name | string | 服务账号名称 |
description | string | 描述;为空时不返回 |
status | string | active 或 archived |
tokenValidAfter | string | Token 生效边界,UTC RFC 3339;为空时不返回 |
createdBy | string | 创建操作主体 ID |
createdAt | string | 创建时间,UTC RFC 3339 |
updatedAt | string | 更新时间,UTC RFC 3339 |
activeKeyCount | int32 | 当前有效且未过期的长期 Key 数量 |
lastUsedAt | string | 最近一次成功使用时间;从未使用时不返回 |
limitAmount | float64 | 当前组织账期的 Credits 用量上限 |
usedAmount | float64 | 当前组织账期已累计使用的 Credits |
limitAmount 语义:
-1:不设置服务账号独立上限;0:冻结服务账号的新增 Credits 消耗;- 大于
0:当前账期最多可使用的 Credits; - 省略:创建时默认为
-1,更新时保持原值。
2. 列出服务账号
GET /v1/organizations/{organization_id}/service-accounts
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
organization_id | string | 是 | 组织 ID |
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
status | string | 否 | active 或 archived;省略时不按状态筛选 |
keyword | string | 否 | 匹配名称或描述的关键字,不区分大小写;去除首尾空白后最长 500 个字符 |
maxResults | integer | 否 | 每页数量,最大 100;默认 20 |
nextToken | string | 否 | 上一页响应返回的分页游标 |
periodStart 和 periodEnd 时,默认选择最近的账期。有可用账期时,已归档账号只有在所选账期内用量大于零才会出现在列表中。详见按账期列出服务账号。
成功响应 (200 OK)
nextToken。
3. 获取服务账号详情
GET /v1/organizations/{organization_id}/service-accounts/{service_account_id}
成功时返回 200 OK 和完整的服务账号资源。服务账号不存在或不属于目标组织时返回 404 Not Found。
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
organization_id | string | 是 | 组织 ID |
service_account_id | string | 是 | 服务账号 ID |
成功响应 (200 OK)
响应为服务账号对象,字段及示例见创建服务账号。
4. 更新服务账号
PUT /v1/organizations/{organization_id}/service-accounts/{service_account_id}
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
organization_id | string | 是 | 组织 ID |
service_account_id | string | 是 | 服务账号 ID |
请求体
请求体至少包含 name、description、limitAmount 中的一个字段。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 否 | 去除首尾空白后不能为空,最长 100 个字符;同一组织内唯一 |
description | string | 否 | 去除首尾空白后最长 500 个字符;空字符串用于清空描述 |
limitAmount | float64 | 否 | -1 或有限的非负数 |
成功响应 (200 OK)
响应为服务账号对象,字段及示例见创建服务账号。
5. 归档服务账号
POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/archive
该操作无需请求体。归档后:
- 服务账号状态变为
archived; - 该账号所有未吊销的长期 Key 被级联吊销;
- 不能再创建或轮转长期 Key;
- 历史用量仍可通过用量 API查询;
- 不提供取消归档接口。
200 OK 和归档后的服务账号资源。
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
organization_id | string | 是 | 组织 ID |
service_account_id | string | 是 | 服务账号 ID |
成功响应 (200 OK)
返回归档后的服务账号对象:status 为 archived,activeKeyCount 为 0,tokenValidAfter 为归档时间。其余字段说明见创建服务账号。
6. 创建长期 Key
POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys
- 明文
token只在创建或轮转成功响应中返回一次; - 查询列表只返回脱敏的
tokenDisplay,无法恢复明文 Token; - 长期 Key 应立即保存到服务端密钥系统,避免写入日志、URL、错误消息或源码;
- 可用 Scope 请与 Qoder 实施团队确认;
- 单个 Key 的 Scope 不得为空或重复,最多 20 个,每个最长 100 个字符;
- 单个服务账号默认最多拥有 5 个有效且未过期的 Key;
- 同一组织默认最多拥有 100 个有效服务账号、500 个有效且未过期的 Service Account Key,实际限额以组织配置为准;
- 已吊销或已过期的 Key 不计入上述上限。
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
organization_id | string | 是 | 组织 ID |
service_account_id | string | 是 | 服务账号 ID |
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 去除首尾空白后长度为 1 至 100 |
scope | string | 是 | 一个或多个空格分隔的 Scope;可用值请与 Qoder 实施团队确认 |
expiresAt | string | 否 | 必须是晚于当前时间的 RFC 3339 时间 |
成功响应 (201 Created)
返回 201 Created。token 只在本次响应中出现:
响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | Key ID |
organizationId | string | 所属组织 ID |
serviceAccountId | string | 所属服务账号 ID |
name | string | Key 名称 |
tokenDisplay | string | 脱敏后的 Token 展示值,不可用于认证 |
scope | string | Key 允许的权限范围,多个 Scope 使用空格分隔 |
status | string | active 或 revoked |
expiresAt | string | 过期时间;未设置时不返回 |
lastUsedAt | string | 最近一次成功使用时间;从未使用时不返回 |
createdBy | string | 创建操作主体 ID |
createdAt | string | 创建时间,UTC RFC 3339 |
updatedAt | string | 更新时间,UTC RFC 3339 |
isExpired | boolean | 当前时间是否已超过 expiresAt |
status=active 仅表示 Key 未被吊销;若 isExpired=true,该 Key 同样不能用于认证。
token 为 string,仅在创建或轮转时返回。
7. 列出长期 Key
GET /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
organization_id | string | 是 | 组织 ID |
service_account_id | string | 是 | 服务账号 ID |
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
status | string | 否 | active 或 revoked;默认 全部 |
maxResults | integer | 否 | 每页数量,最大 100;默认 20 |
nextToken | string | 否 | 上一页响应返回的分页游标 |
成功响应 (200 OK)
token。是否继续分页以 nextToken 是否存在为准;最后一页可以包含数据。
8. 轮转长期 Key
POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys/{key_id}/rotate
该操作无需请求体。轮转时:
- 创建一个继承原 Key 名称、Scope 和过期时间的新 Key;
- 吊销原 Key;
- 返回新 Key 的一次性明文
token。
201 Created,响应结构与创建长期 Key 相同。
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
organization_id | string | 是 | 组织 ID |
service_account_id | string | 是 | 服务账号 ID |
key_id | string | 是 | Key ID |
成功响应 (201 Created)
响应为新 Key 对象,包含一次性明文 token,字段及示例见创建长期 Key。
9. 吊销长期 Key
DELETE /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys/{key_id}
吊销成功时返回 204 No Content。重复吊销同一个 Key 仍返回成功。已吊销 Key 不能再用于认证或轮转。
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
organization_id | string | 是 | 组织 ID |
service_account_id | string | 是 | 服务账号 ID |
key_id | string | 是 | Key ID |
成功响应 (204 No Content)
成功时返回 204 No Content,无响应体。
10. 签发短期 Token
POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/tokens
调用方必须使用路径所指服务账号自己的长期 Service Account Key:
Qoder 校验长期 Key 的所属账号、状态、权限范围和有效期后签发 Token。
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
organization_id | string | 是 | 组织 ID |
service_account_id | string | 是 | 服务账号 ID |
请求体
请求体必须提供 scope。多个 Scope 使用空格分隔;省略 expirationSeconds 时默认签发有效期为 3,600 秒的 Token。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
scope | string | 是 | 一个或多个空格分隔的 Scope;可用值请与 Qoder 实施团队确认,且必须是来源 Key Scopes 的子集;总长度最多 2,048 个字符,最多 20 个不同 Scope,每个最多 100 个字符 |
expirationSeconds | integer | 否 | 0 或省略时使用 3,600 秒;可设置为 1 至 43,200 秒,且不会超过来源 Key 的剩余有效期 |
customId | string | 否 | 1 至 128 个 ASCII 字符,用于审计归因;首字符必须是字母或数字,其余字符可包含 ._:/@+- |
null 和错误类型均会被拒绝。
成功响应 (200 OK)
成功时返回 200 OK,并包含 Cache-Control: no-store 和 Pragma: no-cache:
accessToken,不依赖其内部结构,也不将其写入日志。
使用示例
创建服务账号
列出服务账号
获取服务账号详情
更新服务账号
归档服务账号
创建长期 Key
列出长期 Key
轮转长期 Key
吊销长期 Key
签发短期 Token
错误码
错误响应使用 OpenAPI 统一格式:
| HTTP 状态码 | 错误码 | 说明 |
|---|---|---|
400 | BadRequest、ServiceAccountLimitAmountInvalid、ServiceAccountArchived、ServiceAccountKeyScopeUnsupported、ServiceAccountKeyLimitExceeded、OrganizationServiceAccountKeyLimitExceeded | 请求体、字段值、Key 数量上限或资源当前状态不允许该操作 |
401 | Unauthorized | 认证凭证缺失、无效或已失效 |
403 | Forbidden、OrganizationPlanCapabilityForbidden | 调用方不是目标服务账号自己的长期 Key、无权访问目标组织或组织未开通服务账号能力 |
404 | NotFound | 服务账号或 Key 不存在,或不属于目标组织 |
409 | ServiceAccountNameAlreadyExists、ServiceAccountKeyAlreadyExists | 服务账号名称冲突或 Key 唯一性冲突 |
500 | InternalError | 服务内部错误 |
503 | InternalError 或下游业务错误码 | Token 签发服务或下游依赖不可用 |
code 字段中。请同时处理 HTTP 状态码和实际错误码,不要假定所有参数错误都返回 BadRequest,或所有冲突都返回 AlreadyExists。
相关 API
- 组织、成员与服务账号用量 API:查询服务账号历史用量事件和汇总。