Skip to main content

服务账号 API

管理服务账号、Credits 上限、长期 Key 与短期 Token。

文档说明

先阅读约定与规范和获取 API Key。本站 Base URL 为 https://api.qoder.com。示例 UUID 不代表真实资源,请替换为目标组织中的实际 UUID。 服务账号(Service Account)供应用和服务调用 Qoder,不对应组织成员,也不占用成员席位。 服务账号管理 API 提供:
  • 创建、查询、更新和归档服务账号;
  • 设置服务账号当前账期的 Credits 用量上限;
  • 创建、查询、轮转和吊销长期 Service Account Key;
  • 使用长期 Key 签发短期 Service Account Token;
  • 查询当前账期已使用的 Credits 和 Key 使用状态。
短期 Token 签发接口使用服务账号自己的长期 Key 认证。

权限要求

组织需开通服务账号能力。不同接口使用以下凭证:
接口认证请求头
服务账号及长期 Key 管理Authorization: Bearer <organization_api_key>
短期 Token 签发Authorization: Bearer <service_account_key>
组织 API Key 必须属于路径中的组织。签发短期 Token 时,必须使用路径所指服务账号自己的有效长期 Key。

API 列表

1. 创建服务账号

POST /v1/organizations/{organization_id}/service-accounts

路径参数

参数类型必填说明
organization_idstring是组织 ID

请求体

{
  "name": "CI Automation",
  "description": "用于持续集成任务",
  "limitAmount": 1000
}
参数类型必填说明
namestring是去除首尾空白后长度为 1 至 100;同一组织内唯一
descriptionstring否去除首尾空白后最长 500 个字符
limitAmountfloat64否-1 或有限的非负数;默认 -1

成功响应 (201 Created)

{
  "id": "019c1234-5678-7abc-8def-012345678901",
  "organizationId": "019c1234-5678-7abc-8def-012345678900",
  "name": "CI Automation",
  "description": "用于持续集成任务",
  "status": "active",
  "createdBy": "019c1234-5678-7abc-8def-012345678904",
  "createdAt": "2026-07-20T09:00:00Z",
  "updatedAt": "2026-07-20T09:00:00Z",
  "activeKeyCount": 0,
  "limitAmount": 1000,
  "usedAmount": 0
}

响应字段说明

字段类型说明
idstring服务账号 ID
organizationIdstring所属组织 ID
namestring服务账号名称
descriptionstring描述;为空时不返回
statusstringactive 或 archived
tokenValidAfterstringToken 生效边界,UTC RFC 3339;为空时不返回
createdBystring创建操作主体 ID
createdAtstring创建时间,UTC RFC 3339
updatedAtstring更新时间,UTC RFC 3339
activeKeyCountint32当前有效且未过期的长期 Key 数量
lastUsedAtstring最近一次成功使用时间;从未使用时不返回
limitAmountfloat64当前组织账期的 Credits 用量上限
usedAmountfloat64当前组织账期已累计使用的 Credits
limitAmount 语义:
  • -1:不设置服务账号独立上限;
  • 0:冻结服务账号的新增 Credits 消耗;
  • 大于 0:当前账期最多可使用的 Credits;
  • 省略:创建时默认为 -1,更新时保持原值。

2. 列出服务账号

GET /v1/organizations/{organization_id}/service-accounts

路径参数

参数类型必填说明
organization_idstring是组织 ID

查询参数

参数类型必填说明
statusstring否active 或 archived;省略时不按状态筛选
keywordstring否匹配名称或描述的关键字,不区分大小写;去除首尾空白后最长 500 个字符
maxResultsinteger否每页数量,最大 100;默认 20
nextTokenstring否上一页响应返回的分页游标
未指定 periodStart 和 periodEnd 时,默认选择最近的账期。有可用账期时,已归档账号只有在所选账期内用量大于零才会出现在列表中。详见按账期列出服务账号。

成功响应 (200 OK)

{
  "serviceAccounts": [
    {
      "id": "019c1234-5678-7abc-8def-012345678901",
      "organizationId": "019c1234-5678-7abc-8def-012345678900",
      "name": "CI Automation",
      "status": "active",
      "createdBy": "019c1234-5678-7abc-8def-012345678904",
      "createdAt": "2026-07-20T09:00:00Z",
      "updatedAt": "2026-07-20T09:00:00Z",
      "activeKeyCount": 1,
      "limitAmount": 1000,
      "usedAmount": 125.5
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjoyfQ=="
}
无数据时返回空数组。最后一页不返回 nextToken。

3. 获取服务账号详情

GET /v1/organizations/{organization_id}/service-accounts/{service_account_id} 成功时返回 200 OK 和完整的服务账号资源。服务账号不存在或不属于目标组织时返回 404 Not Found。

路径参数

参数类型必填说明
organization_idstring是组织 ID
service_account_idstring是服务账号 ID

成功响应 (200 OK)

响应为服务账号对象,字段及示例见创建服务账号。

4. 更新服务账号

PUT /v1/organizations/{organization_id}/service-accounts/{service_account_id}

路径参数

参数类型必填说明
organization_idstring是组织 ID
service_account_idstring是服务账号 ID

请求体

请求体至少包含 name、description、limitAmount 中的一个字段。
{
  "name": "CI Automation Production",
  "description": "生产持续集成任务",
  "limitAmount": 1500
}
参数类型必填说明
namestring否去除首尾空白后不能为空,最长 100 个字符;同一组织内唯一
descriptionstring否去除首尾空白后最长 500 个字符;空字符串用于清空描述
limitAmountfloat64否-1 或有限的非负数

成功响应 (200 OK)

响应为服务账号对象,字段及示例见创建服务账号。

5. 归档服务账号

POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/archive 该操作无需请求体。归档后:
  • 服务账号状态变为 archived;
  • 该账号所有未吊销的长期 Key 被级联吊销;
  • 不能再创建或轮转长期 Key;
  • 历史用量仍可通过用量 API查询;
  • 不提供取消归档接口。
重复归档同一账号不会重复改变状态。成功时返回 200 OK 和归档后的服务账号资源。

路径参数

参数类型必填说明
organization_idstring是组织 ID
service_account_idstring是服务账号 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_idstring是组织 ID
service_account_idstring是服务账号 ID

请求体

{
  "name": "CI Production",
  "scope": "<space-separated-scopes>",
  "expiresAt": "2027-07-20T00:00:00Z"
}
参数类型必填说明
namestring是去除首尾空白后长度为 1 至 100
scopestring是一个或多个空格分隔的 Scope;可用值请与 Qoder 实施团队确认
expiresAtstring否必须是晚于当前时间的 RFC 3339 时间

成功响应 (201 Created)

返回 201 Created。token 只在本次响应中出现:
{
  "id": "019c1234-5678-7abc-8def-012345678902",
  "organizationId": "019c1234-5678-7abc-8def-012345678900",
  "serviceAccountId": "019c1234-5678-7abc-8def-012345678901",
  "name": "CI Production",
  "tokenDisplay": "<masked_service_account_key>",
  "scope": "<space-separated-scopes>",
  "status": "active",
  "expiresAt": "2027-07-20T00:00:00Z",
  "createdBy": "019c1234-5678-7abc-8def-012345678904",
  "createdAt": "2026-07-20T09:00:00Z",
  "updatedAt": "2026-07-20T09:00:00Z",
  "isExpired": false,
  "token": "<service_account_key>"
}

响应字段说明

字段类型说明
idstringKey ID
organizationIdstring所属组织 ID
serviceAccountIdstring所属服务账号 ID
namestringKey 名称
tokenDisplaystring脱敏后的 Token 展示值,不可用于认证
scopestringKey 允许的权限范围,多个 Scope 使用空格分隔
statusstringactive 或 revoked
expiresAtstring过期时间;未设置时不返回
lastUsedAtstring最近一次成功使用时间;从未使用时不返回
createdBystring创建操作主体 ID
createdAtstring创建时间,UTC RFC 3339
updatedAtstring更新时间,UTC RFC 3339
isExpiredboolean当前时间是否已超过 expiresAt
status=active 仅表示 Key 未被吊销;若 isExpired=true,该 Key 同样不能用于认证。 token 为 string,仅在创建或轮转时返回。

7. 列出长期 Key

GET /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys

路径参数

参数类型必填说明
organization_idstring是组织 ID
service_account_idstring是服务账号 ID

查询参数

参数类型必填说明
statusstring否active 或 revoked;默认 全部
maxResultsinteger否每页数量,最大 100;默认 20
nextTokenstring否上一页响应返回的分页游标

成功响应 (200 OK)

{
  "keys": [
    {
      "id": "019c1234-5678-7abc-8def-012345678902",
      "organizationId": "019c1234-5678-7abc-8def-012345678900",
      "serviceAccountId": "019c1234-5678-7abc-8def-012345678901",
      "name": "CI Production",
      "tokenDisplay": "<masked_service_account_key>",
      "scope": "<space-separated-scopes>",
      "status": "active",
      "createdBy": "019c1234-5678-7abc-8def-012345678904",
      "createdAt": "2026-07-20T09:00:00Z",
      "updatedAt": "2026-07-20T09:00:00Z",
      "isExpired": false
    }
  ],
  "maxResults": 20
}
列表不返回明文 token。是否继续分页以 nextToken 是否存在为准;最后一页可以包含数据。

8. 轮转长期 Key

POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys/{key_id}/rotate 该操作无需请求体。轮转时:
  • 创建一个继承原 Key 名称、Scope 和过期时间的新 Key;
  • 吊销原 Key;
  • 返回新 Key 的一次性明文 token。
已吊销或已过期的 Key 不能轮转;已归档服务账号不能轮转 Key。成功时返回 201 Created,响应结构与创建长期 Key 相同。

路径参数

参数类型必填说明
organization_idstring是组织 ID
service_account_idstring是服务账号 ID
key_idstring是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_idstring是组织 ID
service_account_idstring是服务账号 ID
key_idstring是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_idstring是组织 ID
service_account_idstring是服务账号 ID

请求体

请求体必须提供 scope。多个 Scope 使用空格分隔;省略 expirationSeconds 时默认签发有效期为 3,600 秒的 Token。
{
  "scope": "<space-separated-scopes>",
  "expirationSeconds": 3600,
  "customId": "deployment-2026-07-20"
}
参数类型必填说明
scopestring是一个或多个空格分隔的 Scope;可用值请与 Qoder 实施团队确认,且必须是来源 Key Scopes 的子集;总长度最多 2,048 个字符,最多 20 个不同 Scope,每个最多 100 个字符
expirationSecondsinteger否0 或省略时使用 3,600 秒;可设置为 1 至 43,200 秒,且不会超过来源 Key 的剩余有效期
customIdstring否1 至 128 个 ASCII 字符,用于审计归因;首字符必须是字母或数字,其余字符可包含 ._:/@+-
请求体只接受上述三个字段;未知字段、显式 null 和错误类型均会被拒绝。

成功响应 (200 OK)

成功时返回 200 OK,并包含 Cache-Control: no-store 和 Pragma: no-cache:
{
  "accessToken": "<opaque_service_account_token>",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "expiresAt": "2026-07-20T10:00:00Z"
}
长期 Key 吊销或账号归档后,已签发的 Token 可能在网关凭证状态缓存刷新前继续被接受;若 Token 自身先过期,则更早失效。请勿假设 Token 即时失效,具体缓存刷新间隔应以部署配置为准。 该接口为非幂等操作,每次成功调用都会签发新的 Token。应用应直接使用 accessToken,不依赖其内部结构,也不将其写入日志。

使用示例

创建服务账号

curl -X POST "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts" \
  -H "Authorization: Bearer <organization_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI Automation","description":"用于持续集成任务","limitAmount":1000}'

列出服务账号

curl -X GET "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts?maxResults=20" \
  -H "Authorization: Bearer <organization_api_key>"

获取服务账号详情

curl -X GET "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901" \
  -H "Authorization: Bearer <organization_api_key>"

更新服务账号

curl -X PUT "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901" \
  -H "Authorization: Bearer <organization_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI Automation Production","description":"生产持续集成任务","limitAmount":1500}'

归档服务账号

curl -X POST "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/archive" \
  -H "Authorization: Bearer <organization_api_key>"

创建长期 Key

curl -X POST "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/keys" \
  -H "Authorization: Bearer <organization_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI Production","scope":"<space-separated-scopes>","expiresAt":"2027-07-20T00:00:00Z"}'

列出长期 Key

curl -X GET "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/keys?maxResults=20" \
  -H "Authorization: Bearer <organization_api_key>"

轮转长期 Key

curl -X POST "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/keys/019c1234-5678-7abc-8def-012345678902/rotate" \
  -H "Authorization: Bearer <organization_api_key>"

吊销长期 Key

curl -X DELETE "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/keys/019c1234-5678-7abc-8def-012345678902" \
  -H "Authorization: Bearer <organization_api_key>"

签发短期 Token

curl -X POST "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/tokens" \
  -H "Authorization: Bearer <service_account_key>" \
  -H "Content-Type: application/json" \
  -d '{"scope":"<space-separated-scopes>","expirationSeconds":3600,"customId":"deployment-2026-07-20"}'

错误码

错误响应使用 OpenAPI 统一格式:
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "name is required"
}
HTTP 状态码错误码说明
400BadRequest、ServiceAccountLimitAmountInvalid、ServiceAccountArchived、ServiceAccountKeyScopeUnsupported、ServiceAccountKeyLimitExceeded、OrganizationServiceAccountKeyLimitExceeded请求体、字段值、Key 数量上限或资源当前状态不允许该操作
401Unauthorized认证凭证缺失、无效或已失效
403Forbidden、OrganizationPlanCapabilityForbidden调用方不是目标服务账号自己的长期 Key、无权访问目标组织或组织未开通服务账号能力
404NotFound服务账号或 Key 不存在,或不属于目标组织
409ServiceAccountNameAlreadyExists、ServiceAccountKeyAlreadyExists服务账号名称冲突或 Key 唯一性冲突
500InternalError服务内部错误
503InternalError 或下游业务错误码Token 签发服务或下游依赖不可用
业务错误码会保留在 code 字段中。请同时处理 HTTP 状态码和实际错误码,不要假定所有参数错误都返回 BadRequest,或所有冲突都返回 AlreadyExists。

相关 API