Group service accounts

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

Interact with service accounts by using the REST API.

Prerequisites:

  • You must be an administrator of the self-managed instance, or have the Owner role for the GitLab.com group.

List service account users

History

Lists all service account users that are provisioned by group.

This function takes pagination parameters page and per_page to restrict the list of users. 

GET /groups/:id/service_accounts

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the target group.
order_by string no Orders list of users by username or id. Default is id.
sort string no Specifies sorting by asc or desc. Default is desc.

Example request: 

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

Example response: 

[

  {
    "id": 57,
    "username": "service_account_group_345_<random_hash>",
    "name": "Service account user"
  },
  {
    "id": 58,
    "username": "service_account_group_346_<random_hash>",
    "name": "Service account user"
  }
]

Create a service account user

History

Creates a service account user.

This API endpoint works on top-level groups only. It does not work on subgroups. 

POST /groups/:id/service_accounts

Supported attributes:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the target group.
name string no The name of the user. If not specified, the default Service account user name is used.
username string no The username of the user. If not specified, it’s automatically generated.

Example request: 

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

Example response: 

{
  "id": 57,
  "username": "service_account_group_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Service account user"
}

Delete a service account user

History

Deletes a service account user.

This API endpoint works on top-level groups only. It does not work on subgroups. 

DELETE /groups/:id/service_accounts/:user_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the target group.
user_id integer yes The ID of a service account user.
hard_delete boolean no If true, contributions that would usually be moved to a Ghost User are instead deleted, as well as groups owned solely by this service account user.

Example request: 

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

Create a personal access token for a service account user

History

This API endpoint works on top-level groups only. It does not work on subgroups. 

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

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the target group.
user_id integer yes The ID of a service account user.
name string yes The name of the personal access token.
scopes array yes Array of scopes of the personal access token. See personal access token scopes for possible values.
expires_at date no The personal access token expiry date. When left blank, the token follows the standard rule of expiry for personal access tokens. To specify no expiration date, omit this key.

Example request: 

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"

Example response: 

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

Rotate a personal access token for a service account user

History

This API endpoint works on top-level groups only. It does not work on subgroups. 

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

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the target group.
user_id integer yes The ID of the service account user.
token_id integer yes The ID of the token.

Example request: 

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"

Example response: 

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