群组访问令牌 API

您可以阅读更多有关群组访问令牌的内容。

列出群组访问令牌

状态 属性自极狐GitLab 17.2 引入。

在极狐GitLab 17.2 及以后版本中，您可以使用 state 属性来为具有指定状态的群组访问令牌进行响应限制。

GET /groups/:id/access_tokens
GET /groups/:id/access_tokens?state=inactive

参数	类型	是否必需	描述
`id`	integer or string	yes	群组 ID 或 URL 编码的路径
`state`	string	No	限制指定状态的令牌结果。有效值为 `active` 和 `inactive`。默认会返回两个状态。

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens"

[
   {
      "user_id" : 141,
      "scopes" : [
         "api"
      ],
      "name" : "token",
      "expires_at" : "2021-01-31",
      "id" : 42,
      "active" : true,
      "created_at" : "2021-01-20T22:11:48.151Z",
      "revoked" : false,
      "last_used_at": null,
      "access_level": 40
   },
   {
      "user_id" : 141,
      "scopes" : [
         "read_api"
      ],
      "name" : "token-2",
      "expires_at" : "2021-01-31",
      "id" : 43,
      "active" : false,
      "created_at" : "2021-01-21T12:12:38.123Z",
      "revoked" : true,
      "last_used_at": "2021-02-13T10:34:57.178Z",
      "access_level": 40
   }
]

获取群组访问令牌

通过 ID 获取群组访问令牌。

GET groups/:id/access_tokens/:token_id

参数	类型	是否必需	描述
`id`	integer or string	yes	群组 ID 或 URL 编码的路径
`token_id`	integer or string	yes	群组访问令牌的 ID

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens/<token_id>"

{
   "user_id" : 141,
   "scopes" : [
      "api"
   ],
   "name" : "token",
   "expires_at" : "2021-01-31",
   "id" : 42,
   "active" : true,
   "created_at" : "2021-01-20T22:11:48.151Z",
   "revoked" : false,
   "access_level": 40
}

创建群组访问令牌

expires_at 参数默认引入于极狐GitLab 16.0。

创建群组访问令牌。您必须拥有群组所有者的角色才能创建群组访问令牌。

POST groups/:id/access_tokens

参数	类型	是否必需	描述
`id`	integer or string	yes	群组 ID 或 URL 编码的路径
`name`	String	yes	群组访问令牌的名称
`scopes`	`Array[String]`	yes	范围列表
`access_level`	Integer	no	访问级别。有效值为 `10`（访客）、`20`（报告者）、`30`（开发者）、`40`（维护者）、`50`（所有者）
`expires_at`	Date	yes	ISO 格式的访问令牌的到期日期 (`YYYY-MM-DD`)。该日期不能晚于访问令牌的最大允许生存期

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type:application/json" \
--data '{ "name":"test_token", "scopes":["api", "read_repository"], "expires_at":"2021-01-31", "access_level": 30 }' \
"https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens"

{
   "scopes" : [
      "api",
      "read_repository"
   ],
   "active" : true,
   "name" : "test",
   "revoked" : false,
   "created_at" : "2021-01-21T19:35:37.921Z",
   "user_id" : 166,
   "id" : 58,
   "expires_at" : "2021-01-31",
   "token" : "D4y...Wzr",
   "access_level": 30
}

轮换群组访问令牌

引入于极狐GitLab 16.0。

先决条件：

您必须有一个具有 api 范围的个人访问令牌。

轮换群组访问令牌。撤销之前的令牌并创建一个一周后过期的新令牌。

在极狐GitLab 16.6 及以后版本中，您可以使用 expires_at 参数来设置不同的到期日期。此非默认到期日期最多可以是自轮换日期起一年。

POST /groups/:id/access_tokens/:token_id/rotate

参数	类型	是否必需	描述
`id`	integer or string	yes	群组 ID 或 URL 编码的路径
`token_id`	integer or string	yes	项目访问令牌 ID
`expires_at`	date	no	满足 ISO 格式（`YYYY-MM-DD`）的个人令牌访问过期时间。自极狐GitLab 16.6 引入。

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens/<token_id>/rotate"

示例响应：

Example response:

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "active": true,
    "expires_at": "2023-08-15",
    "access_level": 30,
    "token": "s3cr3t"
}

响应

200: OK：如果已成功撤销现有令牌并创建新令牌。
400: Bad Request：如果没有成功轮换。
401: Unauthorized：如果有以下任一情况：
- 用户无权访问具有指定 ID 的令牌。
- 具有指定 ID 的令牌不存在。
404: Not Found：如果用户是管理员但具有指定 ID 的令牌不存在。

撤回群组访问令牌

引入于极狐GitLab 14.7。

撤回群组访问令牌。

DELETE groups/:id/access_tokens/:token_id

参数	类型	是否必需	描述
`id`	integer or string	yes	群组 ID 或 URL 编码的路径
`token_id`	integer or string	yes	群组访问令牌的 ID

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens/<token_id>"

响应

撤回成功：204: No Content
撤回失败：400 Bad Request 或 404 Not Found