群组访问令牌 API

使用此 API 与群组访问令牌进行交互。有关更多信息，请参阅 群组访问令牌。

列出所有群组访问令牌#

列出群组的所有群组访问令牌。

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

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

json
1[
2   {
3      "user_id" : 141,
4      "scopes" : [
5         "api"
6      ],
7      "name" : "token",
8      "expires_at" : "2021-01-31",
9      "id" : 42,
10      "active" : true,
11      "created_at" : "2021-01-20T22:11:48.151Z",
12      "description": "Test Token description",
13      "revoked" : false,
14      "last_used_at": null,
15      "access_level": 40
16   },
17   {
18      "user_id" : 141,
19      "scopes" : [
20         "read_api"
21      ],
22      "name" : "token-2",
23      "expires_at" : "2021-01-31",
24      "id" : 43,
25      "active" : false,
26      "created_at" : "2021-01-21T12:12:38.123Z",
27      "description": "Test Token description",
28      "revoked" : true,
29      "last_used_at": "2021-02-13T10:34:57.178Z",
30      "access_level": 40
31   }
32]

获取群组访问令牌的详细信息#

获取群组访问令牌的详细信息。您可以引用特定的群组访问令牌，或者使用关键字 self 返回身份验证群组访问令牌的详细信息。

plaintext
GET /groups/:id/access_tokens/:token_id

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

json
1{
2   "user_id" : 141,
3   "scopes" : [
4      "api"
5   ],
6   "name" : "token",
7   "expires_at" : "2021-01-31",
8   "id" : 42,
9   "active" : true,
10   "created_at" : "2021-01-20T22:11:48.151Z",
11   "description": "Test Token description",
12   "revoked" : false,
13   "access_level": 40
14}

创建群组访问令牌#

为指定的群组创建群组访问令牌。

先决条件：

• 您必须拥有该群组的所有者角色。

plaintext
POST /groups/:id/access_tokens

shell
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 }' \
  --url "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens"

json
1{
2   "scopes" : [
3      "api",
4      "read_repository"
5   ],
6   "active" : true,
7   "name" : "test",
8   "revoked" : false,
9   "created_at" : "2021-01-21T19:35:37.921Z",
10   "description": "Test Token description",
11   "user_id" : 166,
12   "id" : 58,
13   "expires_at" : "2021-01-31",
14   "token" : "D4y...Wzr",
15   "access_level": 30
16}

旋转群组访问令牌#

旋转群组访问令牌。这会立即撤销以前的令牌并创建新令牌。通常，此端点通过使用个人访问令牌来旋转特定的群组访问令牌。您还可以使用群组访问令牌自行旋转。有关更多信息，请参阅 自旋转。

如果您尝试使用此端点旋转以前已撤销的令牌，则同一令牌系列中的任何活动令牌都会被撤销。有关更多信息，请参阅 自动重用检测。

先决条件：

• 拥有 api 范围 的个人访问令牌，或者拥有 api 或 self_rotate 范围 的群组访问令牌。请参阅 自旋转。

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

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

示例响应：

json
1{
2    "id": 42,
3    "name": "Rotated Token",
4    "revoked": false,
5    "created_at": "2023-08-01T15:00:00.000Z",
6    "description": "Test group access token",
7    "scopes": ["api"],
8    "user_id": 1337,
9    "last_used_at": null,
10    "active": true,
11    "expires_at": "2023-08-15",
12    "access_level": 30,
13    "token": "s3cr3t"
14}

如果成功，返回 200: OK。

其他可能的响应：

• 400: Bad Request 如果未成功旋转。
• 401: Unauthorized 如果以下任一条件为真：
  • 令牌不存在。
  • 令牌已过期。
  • 令牌被撤销。
  • 您无权访问指定的令牌。
  • 您正在使用群组访问令牌旋转另一个群组访问令牌。请参阅 自旋转。
• 403: Forbidden 如果令牌不允许自旋转。
• 404: Not Found 如果用户是管理员但令牌不存在。
• 405: Method Not Allowed 如果令牌不是访问令牌。

自旋转#

与旋转特定的群组访问令牌不同，您可以旋转用于验证请求的同一群组访问令牌。要自行旋转群组访问令牌，您必须：

• 使用具有 api 或 self_rotate 范围 的群组访问令牌进行旋转。
• 在请求 URL 中使用 self 关键字。

示例请求：

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_group_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens/self/rotate"

撤销群组访问令牌#

撤销指定的群组访问令牌。

plaintext
DELETE /groups/:id/access_tokens/:token_id

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

如果成功，返回 204 No content。

其他可能的响应：

• 400: Bad Request 如果未成功撤销。
• 404: Not Found 如果访问令牌不存在。