账户与登录

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

操作

POST /api/v1/auth/login

访问: 任何人，无需密钥 · 重试: 请勿自动重试

用账户的 name 和 password 换取有效期为 12 小时的 Bearer 会话 token，同时返回其 expiresAt 和账户；以 Authorization: Bearer 发送。未知的名称、错误的密码和已禁用的账户都返回同样的 401 invalid_credentials。尝试次数按客户端地址和账户限流（429 rate_limited 并带有 Retry-After），一个账户最多保留 32 个会话：新会话会结束最旧的那个。

请求正文 (application/json)

字段	类型	必需	规则
`name`	string	是	—
`password`	string (password)	是	—

响应 200

字段	类型	必需	规则
`token`	string	是	—
`expiresAt`	string (date-time)	是	—
`account`	object	是	—
`account.id`	string (uuid)	是	—
`account.name`	string	是	—
`account.administrator`	boolean	是	—
`account.enabled`	boolean	是	—

响应: 200, 400, 401, 403, 405, 413, 415, 429, 503

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","password":"<password>"}'

注册账户

POST /api/v1/auth/register

访问: 任何人，无需密钥 · 重试: 请勿自动重试

使用 name（3–64 个字母、数字或 _.-）和 password（12–128 个字符）创建普通账户（绝不是管理员）并使其登录，返回 201 和与 login 相同的 12 小时会话。仅当服务器允许自助注册时可用（参见 getAuthOptions），否则返回 403 registration_disabled；名称已被占用则返回 409 already_exists。尝试次数按客户端地址限流（429 并带有 Retry-After），自助注册在达到 900 个账户时停止。

请求正文 (application/json)

字段	类型	必需	规则
`name`	string	是	—
`password`	string (password)	是	—

响应 201

字段	类型	必需	规则
`token`	string	是	—
`expiresAt`	string (date-time)	是	—
`account`	object	是	—
`account.id`	string (uuid)	是	—
`account.name`	string	是	—
`account.administrator`	boolean	是	—
`account.enabled`	boolean	是	—

响应: 201, 400, 403, 405, 413, 415, 429, 503

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","password":"<password>"}'

获取登录选项

GET HEAD /api/v1/auth/options

访问: 任何人，无需密钥 · 重试: 可安全重试（读取）

在登录之前告诉控制台应显示哪些表单：当 registerAccount 在此服务器上开放时，selfRegistration 为 true。

响应 200

字段	类型	必需	规则
`selfRegistration`	boolean	是	—

响应: 200, 400, 403, 503

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/auth/options"

列出您的个人访问令牌

GET HEAD /api/v1/auth/tokens

访问: 已登录的账户会话（不是密钥） · 重试: 可安全重试（读取）

列出已登录账户的个人访问令牌，活跃的排在前面，包含名称、前缀、作用域、创建时间、过期时间、上次使用时间以及是否已撤销；机密值不会再次显示。

响应 200

字段	类型	必需	规则
`items`	数组（object）	是	最多 100 项
`items[].id`	string (uuid)	是	—
`items[].name`	string	是	—
`items[].prefix`	string	是	—
`items[].scope`	string	是	取值之一：`read`, `read-write`
`items[].createdAt`	string (date-time)	是	—
`items[].expiresAt`	string (date-time)	否	可以为 null
`items[].lastUsedAt`	string (date-time)	否	可以为 null
`items[].revoked`	boolean	是	—

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

示例

bash

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

创建个人访问令牌

POST /api/v1/auth/tokens

访问: 已登录的账户会话（不是密钥） · 重试: 请勿自动重试

为脚本和工具创建一个以已登录账户身份行事的令牌；机密值只出现在本次响应中。name 为 1–64 个字符，expiresAt 默认为 90 天，必须在将来且在 365 天以内，scope 为 read-write（默认）或 read，后者永远不能改变任何内容。令牌永远不带管理员权限，不能创建令牌，一个账户最多有 50 个有效令牌（507 token_limit）。

请求正文 (application/json)

字段	类型	必需	规则
`name`	string	是	—
`expiresAt`	string (date-time)	否	—
`scope`	string	否	取值之一：`read`, `read-write`

响应 201

字段	类型	必需	规则
`id`	string (uuid)	是	—
`name`	string	是	—
`prefix`	string	是	—
`scope`	string	是	取值之一：`read`, `read-write`
`createdAt`	string (date-time)	是	—
`expiresAt`	string (date-time)	否	可以为 null
`lastUsedAt`	string (date-time)	否	可以为 null
`revoked`	boolean	是	—
`token`	string	是	—

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

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/auth/tokens" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>"}'

撤销您的个人访问令牌

DELETE /api/v1/auth/tokens/{id}

访问: 已登录的账户会话（不是密钥） · 重试: 可安全重试：相同的请求效果相同

撤销已登录账户的一个个人访问令牌；此后使用它的请求都会失败。撤销已被撤销的令牌同样会成功。

参数

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

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

示例

bash

curl -X DELETE "$ARKVORY_URL/api/v1/auth/tokens/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

退出登录

POST /api/v1/auth/logout

访问: 任何有效的密钥或会话 · 重试: 可安全重试：相同的请求效果相同

结束在 Authorization 中发送的账户会话；其令牌立即失效。若使用任何其他凭据（个人令牌或服务密钥），则返回 204 且不撤销任何内容。

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

示例

bash

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

修改您的密码

POST /api/v1/auth/password

访问: 已登录的账户会话（不是密钥） · 重试: 请勿自动重试

校验 currentPassword 后设置 newPassword（12–128 个字符）；当前密码错误则返回 401 current_password_invalid，并计入登录退避。成功后，该账户的所有会话和所有个人访问令牌都会被撤销，包括当前会话，因此需要重新登录。

请求正文 (application/json)

字段	类型	必需	规则
`currentPassword`	string (password)	是	—
`newPassword`	string (password)	是	—

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

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/auth/password" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"<currentPassword>","newPassword":"<newPassword>"}'

获取当前身份

GET HEAD /api/v1/auth/me

访问: 任何有效的密钥或会话 · 重试: 可安全重试（读取）

返回凭据属于谁：其 id、是否为管理员、凭据类型（session、personal-token、service-key 或 file-key）、个人令牌的作用域，以及它拥有 read 或 write 访问权限的仓库。可用它显示已登录的用户并选择仓库；托管服务密钥的确切权限请使用 getOwnPermissions。

响应 200

字段	类型	必需	规则
`id`	string	是	—
`administrator`	boolean	是	—
`credential`	string	否	取值之一：`session`, `personal-token`, `service-key`, `file-key`
`tokenScope`	string	否	取值之一：`read`, `read-write`
`grants`	数组（object）	是	—
`grants[].repository`	string	是	—
`grants[].permissions`	数组（string）	是	每项：取值之一：`read`, `write`

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

示例

bash

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

列出账户

GET HEAD /api/v1/users

访问: 管理员 · 重试: 可安全重试（读取）

按名称排序，列出所有用户账户，包含 ID、名称、管理员标志以及是否已启用。服务器最多容纳 1000 个账户。

响应 200

字段	类型	必需	规则
`items`	数组（object）	否	—
`items[].id`	string (uuid)	是	—
`items[].name`	string	是	—
`items[].administrator`	boolean	是	—
`items[].enabled`	boolean	是	—

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

示例

bash

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

创建账户

POST /api/v1/users

访问: 管理员 · 重试: 请勿自动重试

使用 name（3–64 个字母、数字或 _.-）、password（12–128 个字符）和 administrator（默认 false）创建账户，并返回 201 和该账户。名称已被占用则返回 409 already_exists；服务器最多容纳 1000 个账户（507 account_limit）。

请求正文 (application/json)

字段	类型	必需	规则
`name`	string	是	—
`password`	string (password)	是	—
`administrator`	boolean	否	—

响应 201

字段	类型	必需	规则
`id`	string (uuid)	是	—
`name`	string	是	—
`administrator`	boolean	是	—
`enabled`	boolean	是	—

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

示例

bash

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

启用、禁用或重置账户

PATCH /api/v1/users/{id}

访问: 管理员 · 重试: 请勿自动重试

更改账户的 enabled 和/或设置新的 password；此处不能更改管理员标志。禁用会结束该账户的所有会话，在其保持禁用期间，它的个人令牌也会停止生效；重置密码会结束所有会话并撤销所有个人令牌。

参数

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

请求正文 (application/json)

字段	类型	必需	规则
`enabled`	boolean	否	—
`password`	string (password)	否	—

响应 200

字段	类型	必需	规则
`id`	string (uuid)	是	—
`name`	string	是	—
`administrator`	boolean	是	—
`enabled`	boolean	是	—

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

示例

bash

curl -X PATCH "$ARKVORY_URL/api/v1/users/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

列出账户的个人访问令牌

GET HEAD /api/v1/users/{id}/tokens

访问: 管理员 · 重试: 可安全重试（读取）

列出任意账户的个人访问令牌，活跃的排在前面，包含名称、前缀、作用域、创建时间、过期时间、上次使用时间和撤销情况；从不包含机密值。可在禁用或重置账户之前用它审查自动化任务。

参数

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

响应 200

字段	类型	必需	规则
`items`	数组（object）	是	最多 100 项
`items[].id`	string (uuid)	是	—
`items[].name`	string	是	—
`items[].prefix`	string	是	—
`items[].scope`	string	是	取值之一：`read`, `read-write`
`items[].createdAt`	string (date-time)	是	—
`items[].expiresAt`	string (date-time)	否	可以为 null
`items[].lastUsedAt`	string (date-time)	否	可以为 null
`items[].revoked`	boolean	是	—

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

示例

bash

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

撤销账户的个人访问令牌

DELETE /api/v1/users/{id}/tokens/{tokenId}

访问: 管理员 · 重试: 可安全重试：相同的请求效果相同

撤销账户 id 的一个个人访问令牌；此后使用它的请求都会失败，该事件会记录到安全审计中。撤销已被撤销的令牌同样会成功。

参数

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

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

示例

bash

curl -X DELETE "$ARKVORY_URL/api/v1/users/$ID/tokens/$TOKENID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

列出访问组

GET HEAD /api/v1/access-groups

访问: 管理员 · 重试: 可安全重试（读取）

列出所有访问组，包含其成员账户 ID 和仓库授权（read 或 write）。服务器最多容纳 100 个组，成员关系和授权各最多 10 000 条。

响应 200

字段	类型	必需	规则
`items`	数组（object）	否	—
`items[].id`	string (uuid)	是	—
`items[].name`	string	是	—
`items[].members`	数组（string (uuid)）	是	—
`items[].grants`	数组（object）	是	—
`items[].grants[].repository`	string	是	—
`items[].grants[].access`	string	是	取值之一：`read`, `write`

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

示例

bash

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

创建访问组

POST /api/v1/access-groups

访问: 管理员 · 重试: 请勿自动重试

使用 name（2–64 个字母、数字或 _.-）创建一个空组并返回 201 和该组；名称已被占用则返回 409 already_exists。用 addGroupMember 添加成员，用 setGroupGrant 添加仓库。

请求正文 (application/json)

字段	类型	必需	规则
`name`	string	是	—

响应 201

字段	类型	必需	规则
`id`	string (uuid)	是	—
`name`	string	是	—
`members`	数组（string (uuid)）	是	—
`grants`	数组（object）	是	—
`grants[].repository`	string	是	—
`grants[].access`	string	是	取值之一：`read`, `write`

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

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/access-groups" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>"}'

将账户加入组

PUT /api/v1/access-groups/{id}/members/{userId}

访问: 管理员 · 重试: 可安全重试：相同的请求效果相同

使账户 userId 成为该组的成员；它在下一次请求时即获得该组的仓库访问权限。添加已有成员不会产生任何变化；成员关系总共最多 10 000 条（507 membership_limit）。

参数

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

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

示例

bash

curl -X PUT "$ARKVORY_URL/api/v1/access-groups/$ID/members/$USERID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

将账户移出组

DELETE /api/v1/access-groups/{id}/members/{userId}

访问: 管理员 · 重试: 可安全重试：相同的请求效果相同

将账户 userId 从该组中移除；它通过该组获得的访问权限在下一次请求时终止。移除不是成员的账户同样会成功。

参数

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

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

示例

bash

curl -X DELETE "$ARKVORY_URL/api/v1/access-groups/$ID/members/$USERID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

授予组对仓库的访问权限

PUT /api/v1/access-groups/{id}/grants/{repository}

访问: 管理员 · 重试: 可安全重试：相同的请求效果相同

授予该组的成员对 repository 的 access，取值为 read 或 write，并替换该组在其中先前的授权；从其下一次请求开始生效。仓库不需要单独创建：授权会使其对成员可见。授权总共最多 10 000 条（507 grant_limit）。

参数

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

请求正文 (application/json)

字段	类型	必需	规则
`access`	string	是	取值之一：`read`, `write`

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

示例

bash

curl -X PUT "$ARKVORY_URL/api/v1/access-groups/$ID/grants/$REPOSITORY" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"access":"read"}'

移除组对仓库的访问权限

DELETE /api/v1/access-groups/{id}/grants/{repository}

访问: 管理员 · 重试: 可安全重试：相同的请求效果相同

移除该组对 repository 的授权；其成员只保留通过其他组获得的访问权限。移除不存在的授权同样会成功。

参数

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

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

示例

bash

curl -X DELETE "$ARKVORY_URL/api/v1/access-groups/$ID/grants/$REPOSITORY" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

读取安全审计

GET HEAD /api/v1/security/audit

访问: 管理员 · 重试: 可安全重试（读取）

按从新到旧的顺序，返回登录、注册、账户、组、授权、密码和个人令牌变更的仅追加日志，每条包含操作者、凭据类型、目标、结果和客户端地址；被限流的尝试不会记入日志。每页包含 limit 条（1–100，默认 50）；将 after 设为 next 即可继续。

参数

名称	位置	类型	必需	规则
`after`	查询	string	否	用十进制数字表示的整数，以字符串形式发送
`limit`	查询	integer	否	1–100

响应 200

字段	类型	必需	规则
`items`	数组（object）	是	最多 100 项
`items[].id`	string	是	用十进制数字表示的整数，以字符串形式发送
`items[].occurredAt`	string (date-time)	是	—
`items[].actor`	string	是	可以为 null
`items[].credential`	string	是	取值之一：`session`, `personal-token`, `service-key`, `file-key`; 可以为 null
`items[].clientIp`	string	是	可以为 null
`items[].action`	string	是	—
`items[].target`	string	是	可以为 null
`items[].outcome`	string	是	取值之一：`success`, `failure`, `denied`
`items[].code`	string	是	可以为 null
`items[].details`	object	是	—
`next`	string	是	可以为 null

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

示例

bash

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

获取您的有效权限

GET HEAD /api/v1/auth/permissions

访问: 任何有效的密钥或会话 · 重试: 可安全重试（读取）

返回调用方的 profile（托管服务密钥为 managed，其他为 legacy）、其密钥 ID、有效绑定（每个仓库及其中允许的确切操作），以及它是否为引导服务管理员。可用它来适配客户端；服务器仍会检查每个请求，因此权限的变化会立即生效。

响应 200

字段	类型	必需	规则
`id`	string	是	—
`profile`	string	是	取值之一：`legacy`, `managed`
`bindings`	数组（object）	是	最多 10000 项
`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`
`serviceAdministration`	boolean	是	—
`credentialId`	string (uuid)	否	可以为 null

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

示例

bash

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

账户与登录 ​

操作 ​

登录 ​

注册账户 ​

获取登录选项 ​

列出您的个人访问令牌 ​

创建个人访问令牌 ​

撤销您的个人访问令牌 ​

退出登录 ​

修改您的密码 ​

获取当前身份 ​

列出账户 ​

创建账户 ​

启用、禁用或重置账户 ​

列出账户的个人访问令牌 ​

撤销账户的个人访问令牌 ​

列出访问组 ​

创建访问组 ​

将账户加入组 ​

将账户移出组 ​

授予组对仓库的访问权限 ​

移除组对仓库的访问权限 ​

读取安全审计 ​

获取您的有效权限 ​

账户与登录

操作

登录

注册账户

获取登录选项

列出您的个人访问令牌

创建个人访问令牌

撤销您的个人访问令牌

退出登录

修改您的密码

获取当前身份

列出账户

创建账户

启用、禁用或重置账户

列出账户的个人访问令牌

撤销账户的个人访问令牌

列出访问组

创建访问组

将账户加入组

将账户移出组

授予组对仓库的访问权限

移除组对仓库的访问权限

读取安全审计

获取您的有效权限