项目访问令牌 API

您可以通过访问项目访问令牌了解更多内容。

列出项目访问令牌列表

  • state 参数引入于极狐GitLab 17.2。

获取项目访问令牌的列表。

在极狐GitLab 17.2 及以后版本中，您可以使用 state 参数来限制项目访问令牌的响应中具有指定状态。

GET projects/:id/access_tokens
GET projects/: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/projects/<project_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",
      "last_used_at" : null,
      "revoked" : false,
      "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 projects/: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/projects/<project_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,
   "last_used_at": "2022-03-15T11:05:42.437Z"
}

创建项目访问令牌

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

创建项目访问令牌。

当创建项目访问令牌时, 您设置的最高角色（访问权限）依赖于您在这个群组中是所有者还是维护者角色。例如，最高角色可设置如下：

  • 所有者 (50)， 如果您在这个项目中拥有所有者权限。
  • 维护者 (40)，如果您在这个项目中拥有维护者权限。

在极狐GitLab 14.8 及更早版本中，项目访问令牌拥有维护者的最高角色。

POST projects/: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 (所有者)。默认是 40。
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/projects/<project_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。

先决条件：

轮换项目访问令牌。撤销先前的令牌并创建一个在一周后过期的新令牌。

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

POST /projects/: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/projects/<project_id>/access_tokens/<token_id>/rotate"

示例响应：

{
    "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 的令牌不存在。

自动复用检测

更多详情，可以参考个人访问令牌的自动复用检测。

撤销项目访问令牌

撤销项目访问令牌。

DELETE projects/:id/access_tokens/:token_id
参数 类型 是否必需 描述
id integer or string yes ID 或者 [URL 编码中项目的路径](rest/index.md#namespaced-path-encoding。
token_id integer or string yes 项目访问令牌的 ID。 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>"

响应

  • 204: No Content：撤销成功。
  • 400 Bad Request 或者 404 Not Found：撤销失败。