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

Service accounts API

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用此 API 与服务账号交互。

您也可以通过用户 API 与服务账号交互。

实例服务账号

Offering: GitLab Self-Managed, GitLab Dedicated

实例服务账号可用于整个 GitLab 实例，但仍然需要像人类用户一样添加到组和项目中。

前置条件：

您必须拥有实例的管理员权限。

列出所有实例服务账号

列出所有实例服务账号。

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

GET /service_accounts

支持的属性：

属性	类型	必需	描述
`order_by`	string	否	用于排序结果的属性。可能值：`id` 或 `username`。默认值：`id`。
`sort`	string	否	排序结果的方向。可能值：`desc` 或 `asc`。默认值：`desc`。

示例请求：

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

示例响应：

[
  {
    "id": 114,
    "username": "service_account_33",
    "name": "Service account user"
  },
  {
    "id": 137,
    "username": "service_account_34",
    "name": "john doe"
  }
]

创建实例服务账号

创建一个实例服务账号。

POST /service_accounts
POST /service_accounts?email=custom_email@gitlab.example.com

支持的属性：

属性	类型	必需	描述
`name`	string	否	用户名称。如果未设置，使用 `Service account user`。
`username`	string	否	用户账号的用户名。如果未定义，生成一个以 `service_account_` 开头的名称。
`email`	string	否	用户账号的邮箱。如果未定义，生成一个 no-reply 邮箱地址。自定义邮箱地址需要确认，除非邮箱确认设置已关闭。

示例请求：

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

示例响应：

{
  "id": 57,
  "username": "service_account_6018816a18e515214e0c34c2b33523fc",
  "name": "Service account user",
  "email": "service_account_6018816a18e515214e0c34c2b33523fc@noreply.gitlab.example.com"
}

如果 email 属性定义的邮箱地址已被其他用户使用，将返回 400 Bad request 错误。

更新实例服务账号

更新指定的实例服务账号。

PATCH /service_accounts/:id

参数：

属性	类型	必需	描述
`id`	integer	是	服务账号的 ID。
`name`	string	否	用户名称。
`username`	string	否	用户账号的用户名。
`email`	string	否	用户账号的邮箱。自定义邮箱地址需要确认，除非邮箱确认设置已关闭。

示例请求：

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/service_accounts/57" --data "name=Updated Service Account email=updated_email@example.com"

示例响应：

{
  "id": 57,
  "username": "service_account_6018816a18e515214e0c34c2b33523fc",
  "name": "Updated Service Account",
  "email": "service_account_<random_hash>@noreply.gitlab.example.com",
  "unconfirmed_email": "custom_email@example.com"
}

组服务账号

组服务账号由特定的顶级组拥有，可以像人类用户一样继承子组和项目的成员资格。

前置条件：

在 GitLab.com 上，您必须拥有该组的 Owner 角色。
在 GitLab Self-Managed 或 GitLab Dedicated 上，您必须：
- 是实例的管理员。
- 在顶级组中拥有 Owner 角色并被允许创建服务账号。

列出所有组服务账号

列出指定顶级组中的所有服务账号。

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

GET /groups/:id/service_accounts

参数：

属性	类型	必需	描述
`id`	integer/string	是	目标组的 ID 或 URL 编码路径。
`order_by`	string	否	按 `username` 或 `id` 对用户列表排序。默认为 `id`。
`sort`	string	否	指定按 `asc` 或 `desc` 排序。默认为 `desc`。

示例请求：

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

示例响应：

[
  {
    "id": 57,
    "username": "service_account_group_345_<random_hash>",
    "name": "Service account user",
    "email": "service_account_group_345_<random_hash>@noreply.gitlab.example.com"
  },
  {
    "id": 58,
    "username": "service_account_group_346_<random_hash>",
    "name": "Service account user",
    "email": "service_account_group_346_<random_hash>@noreply.gitlab.example.com",
    "unconfirmed_email": "custom_email@example.com"
  }
]

创建组服务账号

在指定的顶级组中创建服务账号。

此端点仅适用于顶级组。

POST /groups/:id/service_accounts

支持的属性：

属性	类型	必需	描述
`id`	integer/string	是	顶级组的 ID 或 URL 编码路径。
`name`	string	否	用户账号名称。如果未指定，使用 `Service account user`。
`username`	string	否	用户账号的用户名。如果未指定，生成一个以 `service_account_group_` 开头的名称。
`email`	string	否	用户账号的邮箱。如果未指定，生成一个以 `service_account_group_` 开头的邮箱地址。自定义邮箱地址需要确认，除非该组有匹配的已验证域名或邮箱确认设置已关闭。

示例请求：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts" --data "email=custom_email@example.com"

示例响应：

{
  "id": 57,
  "username": "service_account_group_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Service account user",
  "email": "custom_email@example.com"
}

更新组服务账号

更新指定顶级组中的服务账号。

此端点仅适用于顶级组。

PATCH /groups/:id/service_accounts/:user_id

参数：

属性	类型	必需	描述
`id`	integer/string	是	目标组的 ID 或 URL 编码路径。
`user_id`	integer	是	服务账号的 ID。
`name`	string	否	用户名称。
`username`	string	否	用户名。
`email`	string	否	用户账号的邮箱。自定义邮箱地址需要确认，除非该组有匹配的已验证域名或邮箱确认设置已关闭。

示例请求：

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts/57" --data "name=Updated Service Account email=updated_email@example.com"

示例响应：

{
  "id": 57,
  "username": "service_account_group_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Updated Service Account",
  "email": "service_account_group_345_<random_hash>@noreply.gitlab.example.com",
  "unconfirmed_email": "custom_email@example.com"
}

删除组服务账号

从指定的顶级组中删除服务账号。

此端点仅适用于顶级组。

DELETE /groups/:id/service_accounts/:user_id

参数：

属性	类型	必需	描述
`id`	integer/string	是	目标组的 ID 或 URL 编码路径。
`user_id`	integer	是	服务账号的 ID。
`hard_delete`	boolean	否	如果为 true，通常会被移动到幽灵用户的贡献将被删除，以及仅由该服务账号拥有的组。

示例请求：

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts/181"

列出组服务账号的所有个人访问令牌

列出顶级组中服务账号的所有个人访问令牌。

GET /groups/:id/service_accounts/:user_id/personal_access_tokens

支持的属性：

属性	类型	必需	描述
`id`	integer/string	是	顶级组的 ID 或 URL 编码路径。
`user_id`	integer	是	服务账号的 ID。
`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/groups/187/service_accounts/195/personal_access_tokens?sort=id_desc&search=token2b&created_before=2025-03-27"

示例响应：

[
    {
        "id": 187,
        "name": "service_accounts_token2b",
        "revoked": false,
        "created_at": "2025-03-26T14:42:51.084Z",
        "description": null,
        "scopes": [
            "api"
        ],
        "user_id": 195,
        "last_used_at": null,
        "active": true,
        "expires_at": null
    }
]

不成功的响应示例：

401: Unauthorized
404 Group Not Found

为组服务账号创建个人访问令牌

为指定顶级组中的现有服务账号创建个人访问令牌。

POST /groups/:id/service_accounts/:user_id/personal_access_tokens

参数：

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

示例请求：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens" --data "scopes[]=api,read_user,read_repository" --data "name=service_accounts_token"

示例响应：

{
  "id":6,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:47:13.900Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2024-06-12",
  "token":"<token_value>"
}

撤销组服务账号的个人访问令牌

撤销指定顶级组中现有服务账号的个人访问令牌。

此端点仅适用于顶级组。

DELETE /groups/:id/service_accounts/:user_id/personal_access_tokens/:token_id

参数：

属性	类型	必需	描述
`id`	integer/string	是	目标组的 ID 或 URL 编码路径。
`user_id`	integer	是	服务账号的 ID。
`token_id`	integer	是	令牌的 ID。

示例请求：

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens/6"

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

其他可能的响应：

400: Bad Request 如果撤销不成功。
401: Unauthorized 如果请求未授权。
403: Forbidden 如果请求不被允许。
404: Not Found 如果访问令牌不存在。

旋转组服务账号的个人访问令牌

旋转指定顶级组中现有服务账号的个人访问令牌。这会创建一个有效期为一周的新令牌，并撤销任何现有令牌。

此端点仅适用于顶级组。

POST /groups/:id/service_accounts/:user_id/personal_access_tokens/:token_id/rotate

参数：

属性	类型	必需	描述
`id`	integer/string	是	目标组的 ID 或 URL 编码路径。
`user_id`	integer	是	服务账号的 ID。
`token_id`	integer	是	令牌的 ID。
`expires_at`	date	否	访问令牌的过期日期，采用 ISO 格式（`YYYY-MM-DD`）。在 GitLab 17.9 中引入。如果令牌需要过期日期，默认为一周。如果不需要，默认为最大允许生命周期限制。

示例请求：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens/6/rotate"

示例响应：

{
  "id":7,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:54:49.962Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2023-06-20",
  "token":"<token_value>"
}