{{< details >}}

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

{{< /details >}}

使用此 API 与个人访问令牌进行交互。有关更多信息，请参见 个人访问令牌。

列出所有个人访问令牌

{{< history >}}

  • created_after、created_before、last_used_after、last_used_before、revoked、search 和 state 筛选器在极狐GitLab 15.5 中引入。

{{< /history >}}

列出身份验证用户可访问的所有个人访问令牌。对于管理员，返回实例中所有个人访问令牌的列表。对于非管理员，返回当前用户的个人访问令牌列表。

GET /personal_access_tokens
GET /personal_access_tokens?created_after=2022-01-01T00:00:00
GET /personal_access_tokens?created_before=2022-01-01T00:00:00
GET /personal_access_tokens?last_used_after=2022-01-01T00:00:00
GET /personal_access_tokens?last_used_before=2022-01-01T00:00:00
GET /personal_access_tokens?revoked=true
GET /personal_access_tokens?search=name
GET /personal_access_tokens?state=inactive
GET /personal_access_tokens?user_id=1

支持的属性：

属性 类型 必需 描述
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。
user_id integer or string 否 如果定义，返回由指定用户拥有的令牌。非管理员只能筛选自己的令牌。

示例请求：

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/personal_access_tokens?user_id=3&created_before=2022-01-01"

示例响应：

[
    {
        "id": 4,
        "name": "Test Token",
        "revoked": false,
        "created_at": "2020-07-23T14:31:47.729Z",
        "description": "Test Token description",
        "scopes": [
            "api"
        ],
        "user_id": 3,
        "last_used_at": "2021-10-06T17:58:37.550Z",
        "active": true,
        "expires_at": null
    }
]

如果成功，返回令牌列表。

其他可能的响应：

  • 401: Unauthorized 如果非管理员使用 user_id 属性筛选其他用户。

获取个人访问令牌的详细信息

{{< history >}}

  • 在极狐GitLab 15.1 中引入。
  • 404 HTTP 状态码在极狐GitLab 15.3 中引入。

{{< /history >}}

获取指定个人访问令牌的详细信息。管理员可以获取任何令牌的详细信息。非管理员只能获取自己令牌的详细信息。

GET /personal_access_tokens/:id
属性 类型 必需 描述
id integer or string 是 个人访问令牌的 ID 或关键字 self。 
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/personal_access_tokens/<id>"

如果成功，返回令牌的详细信息。

其他可能的响应：

  • 401: Unauthorized 如果：
    • 令牌不存在。
    • 你无权访问指定令牌。
  • 404: Not Found 如果用户是管理员但令牌不存在。

自我告知

{{< history >}}

  • 在极狐GitLab 15.5 中引入。

{{< /history >}}

除了获取特定个人访问令牌的详细信息，还可以返回用于验证请求的个人访问令牌的详细信息。要返回这些详细信息，您必须在请求 URL 中使用 self 关键字。

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/personal_access_tokens/self"

创建个人访问令牌

{{< details >}}

  • Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated

{{< /details >}}

您可以使用用户令牌 API 创建个人访问令牌。有关更多信息，请参阅以下端点：

轮换个人访问令牌

{{< history >}}

  • 在极狐GitLab 16.0 中引入。
  • expires_at 属性在极狐GitLab 16.6 中添加。

{{< /history >}}

轮换指定的个人访问令牌。这将撤销先前的令牌，并创建一个新的令牌，该令牌将在一周后过期。管理员可以撤销任何用户的令牌。非管理员只能撤销自己的令牌。

POST /personal_access_tokens/:id/rotate
属性 类型 必需 描述
id integer or 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/personal_access_tokens/<personal_access_token_id>/rotate"

示例响应：

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test Token description",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "active": true,
    "expires_at": "2023-08-15",
    "token": "s3cr3t"
}

如果成功，返回 200: OK。

其他可能的响应：

  • 400: Bad Request 如果未成功轮换。
  • 401: Unauthorized 如果以下任何条件为真：
    • 令牌不存在。
    • 令牌已过期。
    • 令牌已撤销。
    • 您无权访问指定令牌。
  • 403: Forbidden 如果令牌不允许自我轮换。
  • 404: Not Found 如果用户是管理员但令牌不存在。
  • 405: Method Not Allowed 如果令牌不是个人访问令牌。

自我轮换

{{< history >}}

  • 在极狐GitLab 16.10 中引入。

{{< /history >}}

除了轮换特定个人访问令牌，您还可以轮换用于验证请求的同一个人访问令牌。要自我轮换个人访问令牌，您必须：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/personal_access_tokens/self/rotate"

自动重用检测

{{< history >}}

  • 在极狐GitLab 16.3 中引入。

{{< /history >}}

当您轮换或撤销令牌时，极狐GitLab 会自动跟踪旧令牌和新令牌之间的关系。每次生成新令牌时，会与之前的令牌建立连接。这些连接的令牌形成一个令牌系列。

如果您尝试使用 API 轮换已撤销的访问令牌，则同一令牌系列中的任何活动令牌都会被撤销。

此功能有助于保护极狐GitLab，防止旧令牌泄露或被盗。通过跟踪令牌关系并在旧令牌使用时自动撤销访问，攻击者无法利用已泄露的令牌。

撤销个人访问令牌

撤销指定的个人访问令牌。管理员可以撤销任何用户的令牌。非管理员只能撤销自己的令牌。

DELETE /personal_access_tokens/:id
属性 类型 必需 描述
id integer or string 是 个人访问令牌的 ID 或关键字 self。 
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/personal_access_tokens/<personal_access_token_id>"

如果成功，返回 204: No Content。

其他可能的响应：

  • 400: Bad Request 如果未成功撤销。
  • 401: Unauthorized 如果请求未授权。
  • 403: Forbidden 如果请求不允许。

自我撤销

{{< history >}}

  • 在极狐GitLab 15.0 中引入，仅限于具有 api 范围的令牌。
  • 在极狐GitLab 15.4 中引入，任何令牌都可以使用此端点。

{{< /history >}}

除了撤销特定个人访问令牌，您还可以撤销用于验证请求的同一个人访问令牌。要自我撤销个人访问令牌，您必须在请求 URL 中使用 self 关键字。

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/personal_access_tokens/self"

列出所有令牌关联

{{< history >}}

  • 在极狐GitLab 17.4 中引入。

{{< /history >}}

列出用于验证请求的个人访问令牌可访问的所有群组和项目。通常，这包括用户所属的任何群组或项目。

GET /personal_access_tokens/self/associations
GET /personal_access_tokens/self/associations?page=2
GET /personal_access_tokens/self/associations?min_access_level=40

支持的属性：

属性 类型 必需 描述
min_access_level integer 否 根据当前用户的最低 角色 (access_level) 限制。
page integer 否 要检索的页面。默认为 1。
per_page integer 否 每页返回的记录数量。默认为 20。

示例请求：

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/personal_access_tokens/self/associations"

示例响应：

{
    "groups": [
        {
        "id": 1,
        "web_url": "http://gitlab.example.com/groups/test",
        "name": "Test",
        "parent_id": null,
        "organization_id": 1,
        "access_levels": 20,
        "visibility": "public"
        },
        {
        "id": 3,
        "web_url": "http://gitlab.example.com/groups/test/test_private",
        "name": "Test Private",
        "parent_id": 1,
        "organization_id": 1,
        "access_levels": 50,
        "visibility": "test_private"
        }
    ],
    "projects": [
        {
            "id": 1337,
            "description": "Leet.",
            "name": "Test Project",
            "name_with_namespace": "Test / Test Project",
            "path": "test-project",
            "path_with_namespace": "Test/test-project",
            "created_at": "2024-07-02T13:37:00.123Z",
            "access_levels": {
                "project_access_level": null,
                "group_access_level": 20
            },
            "visibility": "private",
            "web_url": "http://gitlab.example.com/test/test_project",
            "namespace": {
                "id": 1,
                "name": "Test",
                "path": "Test",
                "kind": "group",
                "full_path": "Test",
                "parent_id": null,
                "avatar_url": null,
                "web_url": "http://gitlab.example.com/groups/test"
            }
        }
    ]
}

相关主题