Help us learn about your current experience with the documentation. Take the survey.

用户令牌 API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

使用此 API 与个人访问令牌和模拟令牌进行交互。更多信息，请参阅 个人访问令牌 和 模拟令牌。

为用户创建个人访问令牌

为指定用户创建个人访问令牌。

令牌值包含在响应中，但之后无法检索。

先决条件：

  • 您必须拥有实例的管理员权限。
POST /users/:user_id/personal_access_tokens

支持的属性：

属性 类型 必需 描述
user_id integer 是 用户账户 ID
name string 是 个人访问令牌名称
description string 否 个人访问令牌描述
expires_at date 否 访问令牌的过期日期，采用 ISO 格式（YYYY-MM-DD）。如果未定义，日期将设置为 最大允许生命周期限制。
scopes array 是 已批准范围的数组。可能的值列表，请参阅 个人访问令牌范围。

示例请求：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "name=mytoken" --data "expires_at=2017-04-04" \
  --data "scopes[]=api" \
  --url "https://gitlab.example.com/api/v4/users/42/personal_access_tokens"

示例响应：

{
    "id": 3,
    "name": "mytoken",
    "revoked": false,
    "created_at": "2020-10-14T11:58:53.526Z",
    "description": "测试令牌描述",
    "scopes": [
        "api"
    ],
    "user_id": 42,
    "active": true,
    "expires_at": "2020-12-31",
    "token": "<your_new_access_token>"
}

创建个人访问令牌

为您的账户创建个人访问令牌。出于安全考虑，该令牌：

  • 仅限于 k8s_proxy 范围。 此范围授予使用 Kubernetes 代理执行 Kubernetes API 调用的权限。
  • 默认在创建当天的午夜过期。

令牌值包含在响应中，但之后无法检索。

先决条件：

  • 您必须已通过身份验证。
POST /user/personal_access_tokens

支持的属性：

属性 类型 必需 描述
name string 是 个人访问令牌名称
description string 否 个人访问令牌描述
scopes array 是 已批准范围的数组。仅接受 k8s_proxy。
expires_at array 否 访问令牌的过期日期，采用 ISO 格式（YYYY-MM-DD）。如果未定义，日期将设置为 最大允许生命周期限制。

示例请求：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "name=mytoken" --data "scopes[]=k8s_proxy" \
  --url "https://gitlab.example.com/api/v4/user/personal_access_tokens"

示例响应：

{
    "id": 3,
    "name": "mytoken",
    "revoked": false,
    "created_at": "2020-10-14T11:58:53.526Z",
    "description": "测试令牌描述",
    "scopes": [
        "k8s_proxy"
    ],
    "user_id": 42,
    "active": true,
    "expires_at": "2020-10-15",
    "token": "<your_new_access_token>"
}

列出用户的所有模拟令牌

列出指定用户的所有模拟令牌。

使用 page 和 per_page 分页参数 来过滤结果。

先决条件：

  • 您必须拥有实例的管理员权限。
GET /users/:user_id/impersonation_tokens

支持的属性：

属性 类型 必需 描述
user_id integer 是 用户账户 ID
state string 否 根据状态过滤令牌。可能的值：all、active 或 inactive。

示例请求：

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

示例响应：

[
   {
      "active" : true,
      "user_id" : 2,
      "scopes" : [
         "api"
      ],
      "revoked" : false,
      "name" : "mytoken",
      "description": "测试令牌描述",
      "id" : 2,
      "created_at" : "2017-03-17T17:18:09.283Z",
      "impersonation" : true,
      "expires_at" : "2017-04-04",
      "last_used_at": "2017-03-24T09:44:21.722Z"
   },
   {
      "active" : false,
      "user_id" : 2,
      "scopes" : [
         "read_user"
      ],
      "revoked" : true,
      "name" : "mytoken2",
      "description": "测试令牌描述",
      "created_at" : "2017-03-17T17:19:28.697Z",
      "id" : 3,
      "impersonation" : true,
      "expires_at" : "2017-04-14",
      "last_used_at": "2017-03-24T09:44:21.722Z"
   }
]

获取用户的模拟令牌

获取指定用户的模拟令牌。

先决条件：

  • 您必须拥有实例的管理员权限。
GET /users/:user_id/impersonation_tokens/:impersonation_token_id

支持的属性：

属性 类型 必需 描述
user_id integer 是 用户账户 ID
impersonation_token_id integer 是 模拟令牌 ID

示例请求：

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2"

示例响应：

{
   "active" : true,
   "user_id" : 2,
   "scopes" : [
      "api"
   ],
   "revoked" : false,
   "name" : "mytoken",
   "description": "测试令牌描述",
   "id" : 2,
   "created_at" : "2017-03-17T17:18:09.283Z",
   "impersonation" : true,
   "expires_at" : "2017-04-04"
}

创建模拟令牌

为指定用户创建模拟令牌。这些令牌用于代表用户操作，可以执行 API 调用以及 Git 读写操作。这些令牌在用户的个人设置页面上对关联用户不可见。

令牌值包含在响应中，但之后无法检索。

先决条件：

  • 您必须拥有实例的管理员权限。
POST /users/:user_id/impersonation_tokens

支持的属性：

属性 类型 必需 描述
user_id integer 是 用户账户 ID
name string 是 模拟令牌名称
description string 否 模拟令牌描述
expires_at date 是 模拟令牌的过期日期，采用 ISO 格式（YYYY-MM-DD）。如果未定义，日期将设置为 最大允许生命周期限制。
scopes array 是 已批准范围的数组。可能的值列表，请参阅 个人访问令牌范围。

示例请求：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "name=mytoken" --data "expires_at=2017-04-04" \
  --data "scopes[]=api" \
  --url "https://gitlab.example.com/api/v4/users/42/impersonation_tokens"

示例响应：

{
   "id" : 2,
   "revoked" : false,
   "user_id" : 2,
   "scopes" : [
      "api"
   ],
   "token" : "<impersonation_token>",
   "active" : true,
   "impersonation" : true,
   "name" : "mytoken",
   "description": "测试令牌描述",
   "created_at" : "2017-03-17T17:18:09.283Z",
   "expires_at" : "2017-04-04"
}

撤销模拟令牌

撤销指定用户的模拟令牌。

先决条件：

  • 您必须拥有实例的管理员权限。
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id

支持的属性：

属性 类型 必需 描述
user_id integer 是 用户账户 ID
impersonation_token_id integer 是 模拟令牌 ID

示例请求：

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1"