服务账户与密钥

用于 CI 和自动化的服务账户，及其密钥、策略、委派和审计。

本组中的操作及其访问规则、重试规则、参数和响应。每个请求都需携带密钥：Authorization: Bearer <密钥>（参见“身份验证”）。

操作

列出服务账户

GET HEAD /api/v1/service-accounts

访问: 服务管理权限 service-account.read · 重试: 可安全重试（读取）

列出调用方可见的服务账户，按 ID 排序，每页 50 个，每个包含名称、启用标志、revision、策略 bindings 和创建时间；将 after 设为 next 即可继续。引导密钥可以看到全部账户，受委派方只能看到其委派包含 service-account.read 的目标；没有该权限时，列表为空而不是被拒绝。

参数

名称	位置	类型	必需	规则
`after`	查询	string (uuid)	否	—

响应 200

字段	类型	必需	规则
`items`	数组（object）	是	最多 50 项
`items[].id`	string (uuid)	是	—
`items[].name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`items[].enabled`	boolean	是	—
`items[].revision`	integer	是	1–2147483647
`items[].bindings`	数组（object）	是	最多 64 项
`items[].bindings[].resource`	object	是	—
`items[].bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`items[].createdAt`	string (date-time)	是	—
`next`	string (uuid)	是	可以为 null

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/service-accounts" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

创建服务账户

POST /api/v1/service-accounts

访问: 引导密钥（安装的恢复密钥） · 重试: 请勿自动重试

为 CI 或应用程序创建一个机器身份，包含 name（3–64 个字母、数字或 _.-）及其策略 bindings：对每个仓库，指定其密钥可以使用的确切操作（例如 upload.create 或 content.read）。返回 201 和该账户；然后用 issueServiceKey 签发密钥。名称已被占用则返回 409 already_exists。

请求正文 (application/json)

字段	类型	必需	规则
`name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`bindings`	数组（object）	是	最多 64 项
`bindings[].resource`	object	是	—
`bindings[].resource.kind`	string	是	取值之一：`repository`
`bindings[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`

响应 201

字段	类型	必需	规则
`id`	string (uuid)	是	—
`name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	是	—
`revision`	integer	是	1–2147483647
`bindings`	数组（object）	是	最多 64 项
`bindings[].resource`	object	是	—
`bindings[].resource.kind`	string	是	取值之一：`repository`
`bindings[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`createdAt`	string (date-time)	是	—

响应: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/service-accounts" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","bindings":[]}'

获取服务账户

GET HEAD /api/v1/service-accounts/{id}

访问: 服务管理权限 service-account.read · 重试: 可安全重试（读取）

返回账户的名称、启用标志、revision、策略绑定和创建时间。对于受委派方，未分配给它的账户返回 404，对已分配账户缺少所需操作则返回 403。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—

响应 200

字段	类型	必需	规则
`id`	string (uuid)	是	—
`name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	是	—
`revision`	integer	是	1–2147483647
`bindings`	数组（object）	是	最多 64 项
`bindings[].resource`	object	是	—
`bindings[].resource.kind`	string	是	取值之一：`repository`
`bindings[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`createdAt`	string (date-time)	是	—

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/service-accounts/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

启用或禁用服务账户

PATCH /api/v1/service-accounts/{id}

访问: 服务管理权限 service-account.manage · 重试: 仅在携带预期修订版本时重试（compare-and-swap）

设置 enabled；expectedRevision 必须是当前修订版本，否则返回 409 revision_mismatch。此处只能更改这个标志（名称不能更改）。禁用会从下一次请求起阻止该账户的所有密钥；启用会恢复既未过期也未被撤销的密钥。受委派方只有在整个当前策略都位于其上限之内时才能这样做。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—

请求正文 (application/json)

字段	类型	必需	规则
`expectedRevision`	integer	是	1–2147483646
`enabled`	boolean	是	—

响应 200

字段	类型	必需	规则
`id`	string (uuid)	是	—
`name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	是	—
`revision`	integer	是	1–2147483647
`bindings`	数组（object）	是	最多 64 项
`bindings[].resource`	object	是	—
`bindings[].resource.kind`	string	是	取值之一：`repository`
`bindings[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`createdAt`	string (date-time)	是	—

响应: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

示例

bash

curl -X PATCH "$ARKVORY_URL/api/v1/service-accounts/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":1,"enabled":false}'

获取服务账户的策略

GET HEAD /api/v1/service-accounts/{id}/policy

访问: 服务管理权限 policy.read · 重试: 可安全重试（读取）

与 getServiceAccount 类似，为持有 policy.read 的调用方返回账户及其策略 bindings 和 revision。密钥的有效权限是此策略与密钥自身绑定在每个仓库和操作上的交集。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—

响应 200

字段	类型	必需	规则
`id`	string (uuid)	是	—
`name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	是	—
`revision`	integer	是	1–2147483647
`bindings`	数组（object）	是	最多 64 项
`bindings[].resource`	object	是	—
`bindings[].resource.kind`	string	是	取值之一：`repository`
`bindings[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`createdAt`	string (date-time)	是	—

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/service-accounts/$ID/policy" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

替换服务账户的策略

PUT /api/v1/service-accounts/{id}/policy

访问: 服务管理权限 policy.manage · 重试: 仅在携带预期修订版本时重试（compare-and-swap）

替换账户的 bindings（最多 64 个，每个是一个仓库及其确切操作）；expectedRevision 必须是当前修订版本，否则返回 409 revision_mismatch。每个密钥从下一次请求起遵循该变更：收窄立即生效，放宽绝不会超出密钥自身的绑定。受委派方要求当前策略和新策略都位于其上限之内。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—

请求正文 (application/json)

字段	类型	必需	规则
`expectedRevision`	integer	是	1–2147483646
`bindings`	数组（object）	是	最多 64 项
`bindings[].resource`	object	是	—
`bindings[].resource.kind`	string	是	取值之一：`repository`
`bindings[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`

响应 200

字段	类型	必需	规则
`id`	string (uuid)	是	—
`name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	是	—
`revision`	integer	是	1–2147483647
`bindings`	数组（object）	是	最多 64 项
`bindings[].resource`	object	是	—
`bindings[].resource.kind`	string	是	取值之一：`repository`
`bindings[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`createdAt`	string (date-time)	是	—

响应: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

示例

bash

curl -X PUT "$ARKVORY_URL/api/v1/service-accounts/$ID/policy" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":1,"bindings":[]}'

列出服务账户的密钥

GET HEAD /api/v1/service-accounts/{id}/keys

访问: 服务管理权限 credential.read · 重试: 可安全重试（读取）

列出账户的密钥元数据，按 ID 排序，每页 50 个：名称、state（pending、active、revoked）、绑定、创建时间、过期时间、激活截止时间以及它由哪个密钥轮换而来；从不包含机密值或哈希。将 after 设为 next 即可继续。过期不会改变 state，因此请将 expiresAt 与当前时间比较。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—
`after`	查询	string (uuid)	否	—

响应 200

字段	类型	必需	规则
`items`	数组（object）	是	最多 50 项
`items[].id`	string (uuid)	是	—
`items[].accountId`	string (uuid)	是	—
`items[].name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`items[].state`	string	是	取值之一：`pending`, `active`, `revoked`
`items[].bindings`	数组（object）	是	最多 64 项
`items[].bindings[].resource`	object	是	—
`items[].bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`items[].createdAt`	string (date-time)	是	—
`items[].expiresAt`	string (date-time)	是	—
`items[].activationExpiresAt`	string (date-time)	是	—
`items[].rotatedFrom`	string (uuid)	是	可以为 null
`next`	string (uuid)	是	可以为 null

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/service-accounts/$ID/keys" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

为服务账户签发密钥

POST /api/v1/service-accounts/{id}/keys

访问: 服务管理权限 credential.manage · 重试: 使用相同的 Idempotency-Key 可安全重试

签发一个待激活的密钥，包含 name、bindings（仅在账户策略也允许它们的范围内生效）和可选的 expiresAt（UTC；默认 90 天，最长 365 天，对受委派方而言绝不超过其自身密钥的有效期）。首次响应为 201，包含 key 和 secret，仅显示这一次；使用相同的 Idempotency-Key 和请求体重复请求时返回 200 且只含元数据，请求体不同则返回 409。持有者必须在 15 分钟内用该机密值调用 activateServiceKey；如果机密值丢失，请撤销该密钥，并使用新的 Idempotency-Key 签发新密钥。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—
`Idempotency-Key`	标头	string	是	最多 128 个字符

请求正文 (application/json)

字段	类型	必需	规则
`name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`bindings`	数组（object）	是	最多 64 项
`bindings[].resource`	object	是	—
`bindings[].resource.kind`	string	是	取值之一：`repository`
`bindings[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`expiresAt`	string (date-time)	否	—

响应 200

字段	类型	必需	规则
`key`	object	是	—
`key.id`	string (uuid)	是	—
`key.accountId`	string (uuid)	是	—
`key.name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`key.state`	string	是	取值之一：`pending`, `active`, `revoked`
`key.bindings`	数组（object）	是	最多 64 项
`key.bindings[].resource`	object	是	—
`key.bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`key.createdAt`	string (date-time)	是	—
`key.expiresAt`	string (date-time)	是	—
`key.activationExpiresAt`	string (date-time)	是	—
`key.rotatedFrom`	string (uuid)	是	可以为 null
`secret`	string	否	—

响应: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/service-accounts/$ID/keys" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","bindings":[]}'

读取服务账户的审计

GET HEAD /api/v1/service-accounts/{id}/audit

访问: 服务管理权限 service-audit.read · 重试: 可安全重试（读取）

按从旧到新的顺序，返回账户在序号 after（默认 0）之后的最多 100 条事件：账户、策略和密钥的变更，例如签发、轮换、激活和撤销，每条包含操作者、操作、密钥和时间。要继续读取，请将最后一个 sequence 作为 after 传入；没有 next 字段。服务器只保留最新的 100 000 条事件。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—
`after`	查询	string	否	用十进制数字表示的整数，以字符串形式发送

响应 200

字段	类型	必需	规则
`items`	数组（object）	是	最多 100 项
`items[].sequence`	string	是	—
`items[].actor`	string	是	—
`items[].action`	string	是	—
`items[].accountId`	string (uuid)	是	—
`items[].keyId`	string (uuid)	是	可以为 null
`items[].occurredAt`	string (date-time)	是	—

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/service-accounts/$ID/audit" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

获取密钥

GET HEAD /api/v1/api-keys/{id}

访问: 服务管理权限 credential.read · 重试: 可安全重试（读取）

返回一个托管密钥的元数据：其账户、名称、状态、绑定、创建时间、过期时间、激活截止时间以及它由哪个密钥轮换而来；从不包含机密值或其哈希。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—

响应 200

字段	类型	必需	规则
`id`	string (uuid)	是	—
`accountId`	string (uuid)	是	—
`name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`state`	string	是	取值之一：`pending`, `active`, `revoked`
`bindings`	数组（object）	是	最多 64 项
`bindings[].resource`	object	是	—
`bindings[].resource.kind`	string	是	取值之一：`repository`
`bindings[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`createdAt`	string (date-time)	是	—
`expiresAt`	string (date-time)	是	—
`activationExpiresAt`	string (date-time)	是	—
`rotatedFrom`	string (uuid)	是	可以为 null

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/api-keys/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

轮换密钥

POST /api/v1/api-keys/{id}/rotate

访问: 服务管理权限 credential.manage · 重试: 使用相同的 Idempotency-Key 可安全重试

为同一账户签发密钥 id 的一个待激活后继密钥，其 bindings 与原密钥相同或更窄，响应方式与 issueServiceKey 相同：201 并带有一次性 secret；使用相同 Idempotency-Key 重复请求时返回 200 且只含元数据。后继密钥被激活后，旧密钥最多再保持有效 24 小时；待新密钥可以正常工作后，请显式撤销旧密钥，但必须在它启动的作业都完成之后。操作员密钥持有的委派不会复制给其后继密钥。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—
`Idempotency-Key`	标头	string	是	最多 128 个字符

请求正文 (application/json)

字段	类型	必需	规则
`name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`bindings`	数组（object）	是	最多 64 项
`bindings[].resource`	object	是	—
`bindings[].resource.kind`	string	是	取值之一：`repository`
`bindings[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`expiresAt`	string (date-time)	否	—

响应 200

字段	类型	必需	规则
`key`	object	是	—
`key.id`	string (uuid)	是	—
`key.accountId`	string (uuid)	是	—
`key.name`	string	是	匹配 `^[a-zA-Z0-9_.-]{3,64}$`
`key.state`	string	是	取值之一：`pending`, `active`, `revoked`
`key.bindings`	数组（object）	是	最多 64 项
`key.bindings[].resource`	object	是	—
`key.bindings[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`
`key.createdAt`	string (date-time)	是	—
`key.expiresAt`	string (date-time)	是	—
`key.activationExpiresAt`	string (date-time)	是	—
`key.rotatedFrom`	string (uuid)	是	可以为 null
`secret`	string	否	—

响应: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/api-keys/$ID/rotate" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","bindings":[]}'

撤销密钥

POST /api/v1/api-keys/{id}/revoke

访问: 服务管理权限 credential.manage · 重试: 可安全重试：相同的请求效果相同

永久撤销该密钥：其下一次请求会失败，但已在运行的下载不会被切断。重复撤销以 204 成功。被撤销的操作员密钥所签发且已激活的密钥仍然有效；请单独撤销它们。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—

响应: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/api-keys/$ID/revoke" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

激活密钥

POST /api/v1/auth/activate-key

访问: 已签发的密钥，激活前后均可 · 重试: 可安全重试：相同的请求效果相同

证明持有者已收到新签发的密钥：在签发后 15 分钟内，以该密钥作为 Authorization: Bearer 调用它，该密钥即变为活跃（204）。重复调用是安全的，且不会延长有效期。激活一个轮换得到的密钥时，会把它所取代的密钥的剩余寿命缩短到最多 24 小时。

响应: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/auth/activate-key" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

列出密钥的委派

GET HEAD /api/v1/api-keys/{id}/delegations

访问: 引导密钥，或该密钥本身 · 重试: 可安全重试（读取）

返回操作员密钥 id 所持有的委派，最多 64 条（含已禁用的）：对每个目标账户，给出其 revision、是否 enabled、管理 actions（例如 credential.manage）以及它可以转授的仓库绑定上限 ceiling。受委派方在此读取自己的委派（其密钥 ID 即 getOwnPermissions 中的 credentialId）；读取其他密钥的列表则返回 403。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—

响应 200

字段	类型	必需	规则
`items`	数组（object）	是	最多 64 项
`items[].keyId`	string (uuid)	是	—
`items[].targetAccountId`	string (uuid)	是	—
`items[].enabled`	boolean	是	—
`items[].revision`	integer	是	1–2147483647
`items[].actions`	数组（string）	是	最多 7 项; 不允许重复项; 每项：取值之一：`service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`items[].ceiling`	数组（object）	是	最多 16 项
`items[].ceiling[].resource`	object	是	—
`items[].ceiling[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/api-keys/$ID/delegations" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

委派服务账户的管理权

PUT /api/v1/api-keys/{id}/delegations/{accountId}

访问: 引导密钥（安装的恢复密钥） · 重试: 仅在携带预期修订版本时重试（compare-and-swap）

让密钥 id 在 ceiling 范围内（最多 16 个它可转授的仓库绑定）以给定的 actions（service-account.read、service-account.manage、policy.read、policy.manage、credential.read、credential.manage、service-audit.read）管理服务账户 accountId；manage 不蕴含 read。创建时 expectedRevision 为 0，更改或重新启用时为该记录的当前修订版本，否则返回 409。该密钥必须处于活跃状态且由引导密钥签发；一个账户不能既持有委派又是委派的目标，因此委派不会形成链条。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—
`accountId`	路径	string (uuid)	是	—

请求正文 (application/json)

字段	类型	必需	规则
`expectedRevision`	integer	是	0–2147483646
`actions`	数组（string）	是	1–7 项; 不允许重复项; 每项：取值之一：`service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`ceiling`	数组（object）	是	最多 16 项
`ceiling[].resource`	object	是	—
`ceiling[].resource.kind`	string	是	取值之一：`repository`
`ceiling[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`ceiling[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`

响应 200

字段	类型	必需	规则
`keyId`	string (uuid)	是	—
`targetAccountId`	string (uuid)	是	—
`enabled`	boolean	是	—
`revision`	integer	是	1–2147483647
`actions`	数组（string）	是	最多 7 项; 不允许重复项; 每项：取值之一：`service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`ceiling`	数组（object）	是	最多 16 项
`ceiling[].resource`	object	是	—
`ceiling[].resource.kind`	string	是	取值之一：`repository`
`ceiling[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`ceiling[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`

响应: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

示例

bash

curl -X PUT "$ARKVORY_URL/api/v1/api-keys/$ID/delegations/$ACCOUNTID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"actions":["service-account.read"],"ceiling":[]}'

撤回委派

DELETE /api/v1/api-keys/{id}/delegations/{accountId}

访问: 引导密钥（安装的恢复密钥） · 重试: 仅在携带预期修订版本时重试（compare-and-swap）

禁用密钥 id 对 accountId 的委派；JSON 请求体携带 expectedRevision，即记录的当前修订版本。该记录作为已禁用的条目保留，没有操作权限且修订版本更高，并以 200 返回；响应丢失后，请用 listServiceDelegations 读取它而不是重复请求，因为旧的修订版本会返回 409。受委派方已经签发并激活的密钥继续有效：请单独撤销它们或禁用该账户。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—
`accountId`	路径	string (uuid)	是	—

请求正文 (application/json)

字段	类型	必需	规则
`expectedRevision`	integer	是	1–2147483646

响应 200

字段	类型	必需	规则
`keyId`	string (uuid)	是	—
`targetAccountId`	string (uuid)	是	—
`enabled`	boolean	是	—
`revision`	integer	是	1–2147483647
`actions`	数组（string）	是	最多 7 项; 不允许重复项; 每项：取值之一：`service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`ceiling`	数组（object）	是	最多 16 项
`ceiling[].resource`	object	是	—
`ceiling[].resource.kind`	string	是	取值之一：`repository`
`ceiling[].resource.id`	string	是	匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
`ceiling[].actions`	数组（string）	是	1–24 项; 不允许重复项; 每项：取值之一：`repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read`

响应: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

示例

bash

curl -X DELETE "$ARKVORY_URL/api/v1/api-keys/$ID/delegations/$ACCOUNTID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":1}'

服务账户与密钥 ​

操作 ​

列出服务账户 ​

创建服务账户 ​

获取服务账户 ​

启用或禁用服务账户 ​

获取服务账户的策略 ​

替换服务账户的策略 ​

列出服务账户的密钥 ​

为服务账户签发密钥 ​

读取服务账户的审计 ​

获取密钥 ​

轮换密钥 ​

撤销密钥 ​

激活密钥 ​

列出密钥的委派 ​

委派服务账户的管理权 ​

撤回委派 ​

服务账户与密钥

操作

列出服务账户

创建服务账户

获取服务账户

启用或禁用服务账户

获取服务账户的策略

替换服务账户的策略

列出服务账户的密钥

为服务账户签发密钥

读取服务账户的审计

获取密钥

轮换密钥

撤销密钥

激活密钥

列出密钥的委派

委派服务账户的管理权

撤回委派