个人访问令牌 API

您可以阅读更多有关个人访问令牌的内容。

列出个人访问令牌

  • created_after、created_before、last_used_after、last_used_before、revoked、search 和 state 引入于极狐GitLab 15.5。

获取经过身份验证的用户有权访问的所有个人访问令牌。默认情况下，返回一个未过滤的列表：

  • 只有当前用户创建的非管理员个人访问令牌。
  • 管理员的所有个人访问令牌。

管理员：

  • 可以使用 user_id 参数按用户过滤。
  • 可以在所有个人访问令牌上使用其他过滤器（极狐GitLab 15.5 及更高版本）。

非管理员：

  • 不能使用 user_id 参数过滤除他们自己以外的任何用户，否则他们会收到 401 Unauthorized 响应。
  • 只能在他们自己的个人访问令牌上过滤（极狐GitLab 15.5 及更高版本）。
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) No 将结果限制为在指定时间后创建的 PAT
created_before datetime (ISO 8601) No 将结果限制为在指定时间前创建的 PAT
last_used_after datetime (ISO 8601) No 将结果限制为在指定时间后最后一次使用的 PAT
last_used_before datetime (ISO 8601) No 将结果限制为在指定时间前最后一次使用的 PAT
revoked boolean No 将结果限制为具有指定撤销状态的 PAT。有效值为 true 和 false
search string No 将结果限制为名称包含搜索字符串的 PAT
state string No 将结果限制为具有特定状态的 PAT。 有效值为 active 和 inactive
user_id integer or string No 将结果限制为特定用户所拥有的 PAT

请求示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens"

响应示例：

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

请求示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens?user_id=3"

响应示例：

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

请求示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens?revoked=true"

响应示例：

[
    {
        "id": 41,
        "name": "Revoked Test Token",
        "revoked": true,
        "created_at": "2022-01-01T14:31:47.729Z",
        "scopes": [
            "api"
        ],
        "user_id": 8,
        "last_used_at": "2022-05-18T17:58:37.550Z",
        "active": false,
        "expires_at": null
    }
]

您可以通过合并的属性进行过滤：

GET /personal_access_tokens?revoked=true&created_before=2022-01-01

获取单个个人访问令牌

使用以下任意一个方法获取个人访问令牌：

  • 使用个人访问令牌的 ID
  • 将其传递给 header 中的 API

使用个人访问令牌 ID

  • 引入于极狐GitLab 15.1。

通过 ID 获取单个个人访问令牌。用户可以获得自己的令牌。管理员可以获得任何令牌。

GET /personal_access_tokens/:id
参数 类型 是否必需 描述
id integer/string yes 个人访问令牌 ID 
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/<id>"

响应

404 HTTP 状态码引入于极狐GitLab 15.3。

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

使用请求 header

  • 引入于极狐GitLab 15.5。

通过在 header 中传递令牌来获取单个个人访问令牌和令牌信息。

GET /personal_access_tokens/self

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

响应示例：

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

轮换个人访问令牌

您可以：

  • 使用个人访问令牌 ID。
  • 在极狐GitLab 16.0 及以后版本中，将个人访问令牌传递给 API 请求头。

使用个人访问令牌 ID

  • 引入于极狐GitLab 16.0。

在极狐GitLab 16.6 及以后版本，您可以使用 expires_at 参数设置不同的到期日期。此非默认到期日期最多可以比旋转日期晚一年。

POST /personal_access_tokens/:id/rotate
参数 类型 是否必需 描述
id integer/string yes 个人访问令牌 ID
expires_at date no 访问令牌的过期日期的格式是（YYYY-MM-DD）。引入于极狐GitLab 16.6。
note 非管理员可以轮换他们自己的令牌。管理员可以轮换任何用户的令牌。
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "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：如果出现以下任一情况：
    • 用户无权访问具有指定 ID 的令牌。
    • 具有指定 ID 的令牌不存在。
  • 404: Not Found：如果用户是管理员但具有指定 ID 的令牌不存在。

使用请求标头

  • 引入于极狐GitLab 16.10。

必需：

  • api 范围。

您可以使用 expires_at 参数来设置不同的过期日期。此非默认过期日期最多可以比旋转日期晚一年。

POST /personal_access_tokens/self/rotate

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/self/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：如果出现以下任一情况：
    • 令牌不存在。
    • 令牌已过期。
    • 令牌已被撤销。
  • 404: Not Found：如果用户是管理员但具有指定 ID 的令牌不存在。

自动复用检测

  • 引入于极狐GitLab 16.3

对于每一个旋转的令牌，之前的和现在被撤销的令牌都会被引用。这种引用链定义了一个令牌家族。在一个令牌家族中，只有最新的令牌是活动的，该家族中的所有其他令牌都被撤销了。

当来自某个令牌系列的已吊销令牌，被用于针对令牌轮换端点的身份验证尝试时，该尝试会失败，并且该令牌系列中的活动令牌也会被吊销。

这种机制有助于在个人访问令牌遭泄露时防范安全风险。

自动复用检测在令牌轮换 API 请求中默认启用。

撤回个人访问令牌

可以使用以下内容之一撤回个人访问令牌：

  • 使用个人访问令牌的 ID
  • 将其传递到 Header 中的 API

使用个人访问令牌 ID

使用 ID 撤回个人访问令牌。

DELETE /personal_access_tokens/:id
参数 类型 是否必需 描述
id integer/string yes 个人访问令牌 ID
note 非管理员只能撤回他们自己的令牌。管理员可以撤回任何用户的令牌。
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/<personal_access_token_id>"

响应

  • 撤回成功：204: No Content

  • 撤回失败：400: Bad Request

  • 204: No Content 如果撤销成功。
  • 400: Bad Request 如果撤销不成功。
  • 401: Unauthorized 如果访问令牌无效。
  • 403: Forbidden 如果访问令牌没有必须的权限。

使用请求 Header

  • 引入于极狐GitLab 15.0。限定为带有 api 范围的令牌。
  • 引入于极狐GitLab 15.4，任何令牌都可以使用该端点。

撤销使用请求 header 传入的个人访问令牌。要求：

  • 15.0 到 15.3 中为 api 范围
  • 15.4 及更高版本中为任何范围
DELETE /personal_access_tokens/self

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

响应

  • 204: No Content 如果撤销成功。
  • 400: Bad Request 如果撤销不成功。
  • 401: Unauthorized 如果访问令牌无效。

列出令牌关联

  • 引入于极狐GitLab 17.4。

返回当前认证用户能够访问的所有群组、子群组和项目的未过滤列表。

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 No 限制当前用户的最小角色 (access_level)。
page integer No 获取的页面。默认为 1。
per_page integer No 返回的每页的记录数量。默认为 20。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "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。

为当前认证用户创建受限范围的个人访问令牌

为当前的认证用户创建个人访问令牌的更多详情，可以查看用户令牌 API。

访问令牌故障排查

关于访问令牌议题故障排查，可以查看令牌故障排查指南。