{{< details >}}
- Tier: 基础版,专业版,旗舰版
- Offering: JihuLab.com,私有化部署
{{< /details >}}
使用此 API 与项目访问令牌交互。有关更多信息,请参阅项目访问令牌。
列出所有项目访问令牌
{{< history >}}
-
state
属性在极狐GitLab 17.2 中引入。
{{< /history >}}
列出指定项目的所有项目访问令牌。
GET projects/:id/access_tokens
GET projects/:id/access_tokens?state=inactive
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer 或 string | 是 | 项目的 ID 或URL 编码路径。 |
created_after |
datetime (ISO 8601) | 否 | 如果已定义,返回在指定时间之后创建的令牌。 |
created_before |
datetime (ISO 8601) | 否 | 如果已定义,返回在指定时间之前创建的令牌。 |
expires_after |
date (ISO 8601) | 否 | 如果已定义,返回在指定时间之后过期的令牌。 |
expires_before |
date (ISO 8601) | 否 | 如果已定义,返回在指定时间之前过期的令牌。 |
last_used_after |
datetime (ISO 8601) | 否 | 如果已定义,返回在指定时间之后最后使用的令牌。 |
last_used_before |
datetime (ISO 8601) | 否 | 如果已定义,返回在指定时间之前最后使用的令牌。 |
revoked |
boolean | 否 | 如果为 true ,则仅返回已撤销的令牌。 |
search |
string | 否 | 如果已定义,返回名称中包含指定值的令牌。 |
sort |
string | 否 | 如果已定义,根据指定值排序结果。可能的值:created_asc ,created_desc ,expires_asc ,expires_desc ,last_used_asc ,last_used_desc ,name_asc ,name_desc 。 |
state |
string | 否 | 如果已定义,返回具有指定状态的令牌。可能的值:active 和 inactive 。 |
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "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",
"description": "Test Token description",
"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",
"description": "Test Token description",
"revoked" : true,
"last_used_at" : "2021-02-13T10:34:57.178Z",
"access_level" : 40
}
]
获取项目访问令牌的详细信息
获取项目访问令牌的详细信息。您可以引用特定的项目访问令牌,或者使用关键字 self
返回身份验证项目访问令牌的详细信息。
GET projects/:id/access_tokens/:token_id
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer 或 string | 是 | 项目的 ID 或URL 编码路径。 |
token_id |
integer 或 string | 是 | 项目访问令牌的 ID 或关键字 self 。 |
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "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",
"description": "Test Token description",
"revoked" : false,
"access_level": 40,
"last_used_at": "2022-03-15T11:05:42.437Z"
}
创建项目访问令牌
{{< history >}}
- 在极狐GitLab 16.0 中引入了
expires_at
属性的默认值。
{{< /history >}}
为指定项目创建项目访问令牌。您无法创建访问级别高于您账户的令牌。例如,具有维护者角色的用户无法创建具有所有者角色的项目访问令牌。
您必须使用个人访问令牌进行身份验证。无法使用项目访问令牌进行身份验证。对此功能有一个开放功能请求。
POST projects/:id/access_tokens
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer 或 string | 是 | 项目的 ID 或URL 编码路径。 |
name |
string | 是 | 令牌的名称。 |
description |
string | 否 | 项目访问令牌的描述。 |
scopes |
Array[String] |
是 | 令牌可用的范围列表。 |
access_level |
integer | 否 | 令牌的访问级别。可能的值:10 (访客),15 (计划员),20 (报告者),30 (开发者),40 (维护者),和 50 (所有者)。默认值:40 。 |
expires_at |
date | 是 | 令牌的过期日期,以 ISO 格式 (YYYY-MM-DD ) 表示。如果未定义,则日期设置为最大允许期限。 |
curl --request POST \
--header "PRIVATE-TOKEN: <your_personal_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/projects/<project_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 >}}
- 在极狐GitLab 16.0 中引入。
- 在极狐GitLab 16.6 中添加了
expires_at
属性。
{{< /history >}}
旋转项目访问令牌。这会立即撤销以前的令牌并创建新令牌。通常,此端点通过使用个人访问令牌进行身份验证来旋转特定项目访问令牌。您还可以使用项目访问令牌自旋。有关更多信息,请参阅自旋。
如果尝试使用此端点旋转以前已撤销的令牌,则同一令牌系列中的任何活动令牌都会被撤销。有关更多信息,请参阅自动重用检测。
先决条件:
- 具有
api
范围的个人访问令牌或具有api
或self_rotate
范围的项目访问令牌。请参阅自旋。
POST /projects/:id/access_tokens/:token_id/rotate
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer 或 string | 是 | 项目的 ID 或URL 编码路径。 |
token_id |
integer 或 string | 是 | 项目访问令牌的 ID 或关键字 self 。 |
expires_at |
date | 否 | 访问令牌的过期日期,以 ISO 格式 (YYYY-MM-DD ) 表示。日期必须在旋转日期的一年或更短时间内。如果未定义,则令牌在一周后过期。 |
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "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",
"description": "Test project 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_project_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/self/rotate"
撤销项目访问令牌
撤销指定的项目访问令牌。
DELETE projects/:id/access_tokens/:token_id
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer 或 string | 是 | 项目的 ID 或URL 编码路径。 |
token_id |
integer | 是 | 项目访问令牌的 ID。 |
curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>"
如果成功,则返回 204 No content
。
其他可能的响应:
-
400: Bad Request
如果没有成功撤销。 -
404: Not Found
如果访问令牌不存在。