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
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:
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",
"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
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:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer/string | yes | ID or URL-encoded path of a top-level group. |
name | string | no | User account name. If not specified, uses Service account user . |
username | string | no | User account username. If not specified, generates a name prepended with service_account_group_ . |
email | string | no | User 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
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:
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
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:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer/string | yes | ID or URL-encoded path of a top-level group. |
user_id | integer | yes | ID of service account user. |
name | string | yes | Name of personal access token. |
scopes | array | yes | Array of approved scopes. For a list of possible values, see Personal access token scopes. |
expires_at | date | no | Expiration 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
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:
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. |
expires_at | date | no | Expiration 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>"
}
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