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 /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 属性过滤其他用户的令牌。

获取个人访问令牌详情

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

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 如果用户是管理员但令牌不存在。

自身信息

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

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

创建个人访问令牌

Offering: GitLab Self-Managed, GitLab Dedicated

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

轮换个人访问令牌

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

POST /personal_access_tokens/:id/rotate

字段	类型	必需	描述
`id`	integer or string	是	个人访问令牌的 ID 或关键字 `self`。
`expires_at`	date	否	访问令牌的过期日期，采用 ISO 格式（`YYYY-MM-DD`）。如果令牌需要过期日期，默认为 1 周。如果不要求，默认为最大允许生命周期限制。

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 如果令牌不是个人访问令牌。

自身轮换

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

使用 api 或 self_rotate 权限轮换个人访问令牌。
在请求 URL 中使用 self 关键字。

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

自动重用检测

当您轮换或撤销令牌时，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 如果请求不被允许。

自身撤销

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

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

列出所有令牌关联

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

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"
            }
        }
    ]
}

个人访问令牌 API

列出所有个人访问令牌

获取个人访问令牌详情

自身信息

创建个人访问令牌

轮换个人访问令牌

自身轮换

自动重用检测

撤销个人访问令牌

自身撤销

列出所有令牌关联

相关主题