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
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
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
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
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
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>"
}
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support