Help us learn about your current experience with the documentation. Take the survey.

群组访问令牌 API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

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

列出所有群组访问令牌

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

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

属性	类型	必需	描述
`id`	整数或字符串	是	群组的 ID 或 URL 编码路径。
`created_after`	日期时间 (ISO 8601)	否	如果定义，则返回在指定时间之后创建的令牌。
`created_before`	日期时间 (ISO 8601)	否	如果定义，则返回在指定时间之前创建的令牌。
`expires_after`	日期 (ISO 8601)	否	如果定义，则返回在指定时间之后过期的令牌。
`expires_before`	日期 (ISO 8601)	否	如果定义，则返回在指定时间之前过期的令牌。
`last_used_after`	日期时间 (ISO 8601)	否	如果定义，则返回在指定时间之后最后使用的令牌。
`last_used_before`	日期时间 (ISO 8601)	否	如果定义，则返回在指定时间之前最后使用的令牌。
`revoked`	布尔值	否	如果为 `true`，则只返回已撤销的令牌。
`search`	字符串	否	如果定义，则返回名称中包含指定值的令牌。
`sort`	字符串	否	如果定义，则按指定值对结果进行排序。可能的值：`created_asc`、`created_desc`、`expires_asc`、`expires_desc`、`last_used_asc`、`last_used_desc`、`name_asc`、`name_desc`。
`state`	字符串	否	如果定义，则返回具有指定状态的令牌。可能的值：`active` 和 `inactive`。

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
      "description": "Test Token description",
      "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",
      "description": "Test Token description",
      "revoked" : true,
      "last_used_at": "2021-02-13T10:34:57.178Z",
      "access_level": 40
   }
]

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

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

GET /groups/:id/access_tokens/:token_id

属性	类型	必需	描述
`id`	整数或字符串	是	群组的 ID 或 URL 编码路径。
`token_id`	整数或字符串	是	ID

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
   "description": "Test Token description",
   "revoked" : false,
   "access_level": 40
}

创建群组访问令牌

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

前置条件：

您必须拥有该群组的 Owner 角色。

POST /groups/:id/access_tokens

属性	类型	必需	描述
`id`	整数或字符串	是	群组的 ID 或 URL 编码路径。
`name`	字符串	是	令牌的名称。
`description`	字符串	否	群组访问令牌的描述。
`scopes`	`Array[String]`	是	令牌可用的范围列表。
`access_level`	整数	否	令牌的角色。可能的值：`10` (Guest)、`15` (Planner)、`20` (Reporter)、`30` (Developer)、`40` (Maintainer) 和 `50` (Owner)。默认值：`40`。
`expires_at`	日期	否	访问令牌的过期日期，格式为 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 }' \
  --url "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",
   "description": "Test Token description",
   "user_id" : 166,
   "id" : 58,
   "expires_at" : "2021-01-31",
   "token" : "D4y...Wzr",
   "access_level": 30
}

轮换群组访问令牌

轮换群组访问令牌。此操作会立即撤销之前的令牌并创建一个新令牌。通常，此端点通过个人访问令牌进行身份验证来轮换特定的群组访问令牌。您也可以使用群组访问令牌来轮换自身。更多信息，请参阅自我轮换。

如果您尝试使用此端点轮换先前已撤销的令牌，则来自同一令牌系列的任何活动令牌都将被撤销。更多信息，请参阅自动重用检测。

前置条件：

具有 api 范围的个人访问令牌，或具有 api 或 self_rotate 范围的群组访问令牌。请参阅自我轮换。

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

属性	类型	必需	描述
`id`	整数或字符串	是	群组的 ID 或 URL 编码路径。
`token_id`	整数或字符串	是	群组访问令牌的 ID 或关键字 `self`。
`expires_at`	日期	否	访问令牌的过期日期，格式为 ISO (`YYYY-MM-DD`)。如果令牌需要过期日期，则默认为 1 周。如果不需要，则默认为最大允许生命周期限制。

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

示例响应：

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test group access token",
    "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，如果满足以下任一条件：
- 令牌不存在。
- 令牌已过期。
- 令牌已被撤销。
- 您无权访问指定的令牌。
- 您正在使用群组访问令牌来轮换另一个群组访问令牌。请改为参阅自我轮换。
403: Forbidden，如果令牌不允许轮换自身。
404: Not Found，如果用户是管理员但令牌不存在。
405: Method Not Allowed，如果令牌不是访问令牌。

自我轮换

您可以轮换用于对请求进行身份验证的同一个群组访问令牌，而不是轮换特定的群组访问令牌。要自我轮换群组访问令牌，您必须：

轮换具有 api 或 self_rotate 范围的群组访问令牌。
在请求 URL 中使用 self 关键字。

示例请求：

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

撤销群组访问令牌

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

DELETE /groups/:id/access_tokens/:token_id

属性	类型	必需	描述
`id`	整数或字符串	是	群组的 ID 或 URL 编码路径。
`token_id`	整数	是	群组访问令牌的 ID。

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，如果访问令牌不存在。