{{< details >}}

  1. Tier: 基础版, 专业版, 旗舰版
  2. Offering: JihuLab.com, 私有化部署

{{< /details >}}

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

列出所有群组访问令牌

{{< history >}}

  1. state 属性在极狐GitLab 17.2 中引入。

{{< /history >}}

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

GET /groups/:id/access_tokens
GET /groups/:id/access_tokens?state=inactive
属性 类型 是否必需 描述
id integer or string yes 群组的 ID 或 URL 编码路径。
created_after datetime (ISO 8601) No 如果定义，返回在指定时间之后创建的令牌。
created_before datetime (ISO 8601) No 如果定义，返回在指定时间之前创建的令牌。
expires_after date (ISO 8601) No 如果定义，返回在指定时间之后过期的令牌。
expires_before date (ISO 8601) No 如果定义，返回在指定时间之前过期的令牌。
last_used_after datetime (ISO 8601) No 如果定义，返回在指定时间之后最后使用的令牌。
last_used_before datetime (ISO 8601) No 如果定义，返回在指定时间之前最后使用的令牌。
revoked boolean No 如果为 true，则仅返回已撤销的令牌。
search string No 如果定义，返回名称中包含指定值的令牌。
sort string No 如果定义，根据指定值对结果进行排序。可能的值：created_asc、created_desc、expires_asc、expires_desc、last_used_asc、last_used_desc、name_asc、name_desc。
state string No 如果定义，返回具有指定状态的令牌。可能的值：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
   }
]

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

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

GET /groups/:id/access_tokens/:token_id
属性 类型 是否必需 描述
id integer or string yes 群组的 ID 或 URL 编码路径。
token_id integer or string yes 群组访问令牌的 ID 或关键字 self。 
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
}

创建群组访问令牌

{{< history >}}

  1. expires_at 属性的默认值在极狐GitLab 16.0 中引入。

{{< /history >}}

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

先决条件：

  • 您必须拥有该群组的所有者角色。
POST /groups/:id/access_tokens
属性 类型 是否必需 描述
id integer or string yes 群组的 ID 或 URL 编码路径。
name String yes 令牌的名称。
description string no 群组访问令牌的描述。
scopes Array[String] yes 令牌可用的 范围 列表。
access_level Integer no 令牌的 访问级别。可能的值：10 (Guest)、15 (Planner)、20 (Reporter)、30 (Developer)、40 (Maintainer) 和 50 (Owner)。默认值：40。
expires_at date no 访问令牌的到期日期，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
}

旋转群组访问令牌

{{< history >}}

  1. 在极狐GitLab 16.0 中引入。
  2. expires_at 属性在极狐GitLab 16.6 中添加。

{{< /history >}}

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

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

先决条件：

POST /groups/:id/access_tokens/:token_id/rotate
属性 类型 是否必需 描述
id integer or string yes 群组的 ID 或 URL 编码路径。
token_id integer or string yes 群组访问令牌的 ID 或关键字 self。
expires_at date no 访问令牌的到期日期，ISO 格式 (YYYY-MM-DD)。日期必须为旋转日期起一年或更短时间。如果未定义，则令牌在一周后过期。 
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 如果令牌不是访问令牌。

自旋转

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

示例请求：

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 integer or string yes 群组的 ID 或 URL 编码路径。
token_id integer yes 群组访问令牌的 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 如果访问令牌不存在。