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.

Copy to clipboard 
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:

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

Example response:

Copy to clipboard 
[

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

Copy to clipboard 
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:

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

Example response:

Copy to clipboard 
{
  "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.

Copy to clipboard 
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:

Copy to clipboard 
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.

Copy to clipboard 
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:

Copy to clipboard 
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:

Copy to clipboard 
{
  "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.

Copy to clipboard 
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:

Copy to clipboard 
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:

Copy to clipboard 
{
  "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>"
}