Group service accounts API

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

Use this API to interact with service accounts for your groups. For more information, see Service accounts.

Prerequisites:

  • You must have administrator access to the instance, or have the Owner role for the GitLab.com group.

List all service account users

History

Lists all service account users in a specified top-level group.

Use the page and per_page pagination parameters to filter the results.

GET /groups/:id/service_accounts

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the target group.
order_bystringnoOrders list of users by username or id. Default is id.
sortstringnoSpecifies 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",
    "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"
  }
]

Create a service account user

History

Creates a service account user in a given top-level group.

This endpoint only works on top-level groups.

POST /groups/:id/service_accounts

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesID or URL-encoded path of a top-level group.
namestringnoUser account name. If not specified, uses Service account user.
usernamestringnoUser account username. If not specified, generates a name prepended with service_account_group_.
emailstringnoUser account email. If not specified, generates an email prepended with service_account_group_. Custom email addresses require confirmation before the account is active, unless the group has a matching verified domain.

Example request:

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"

Example response:

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

Delete a service account user

History

Deletes a service account user from a given top-level group.

This endpoint only works on top-level groups.

DELETE /groups/:id/service_accounts/:user_id

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the target group.
user_idintegeryesThe ID of a service account user.
hard_deletebooleannoIf 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

Creates a personal access token for an existing service account user in a given top-level group.

This endpoint only works on top-level groups.

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

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesID or URL-encoded path of a top-level group.
user_idintegeryesID of service account user.
namestringyesName of personal access token.
scopesarrayyesArray of approved scopes. For a list of possible values, see Personal access token scopes.
expires_atdatenoExpiration date of the access token in ISO format (YYYY-MM-DD). If not specified, the date is set to the maximum allowable lifetime limit.

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

Rotates a personal access token for an existing service account user in a given top-level group. This creates a new token valid for one week and revokes any existing tokens.

This endpoint only works on top-level groups.

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

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the target group.
user_idintegeryesThe ID of the service account user.
token_idintegeryesThe ID of the token.
expires_atdatenoExpiration date of the access token in ISO format (YYYY-MM-DD). Introduced in GitLab 17.9. If undefined, the token expires after one week.

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