Service accounts

Use this API to interact with service accounts.

The number of service accounts you can create depends on your subscription and offering:

On GitLab Premium and Ultimate, you can create an unlimited number of service accounts for all offerings.
On GitLab Free, limits vary by offering:
- For GitLab.com, you can create up to 100 service accounts for each top-level group. This includes service accounts created in subgroups or projects.
- For GitLab Self-Managed, you can create up to 100 service accounts for the entire instance. This includes service accounts created for the instance, a group, or a project.

You can also interact with service accounts through the users API. To manage SSH keys for service accounts, use the user SSH and GPG keys API.

List all group service accounts

GET /api/v4/groups/{id}/service_accounts

Lists all service accounts in a specified group. Use the page and per_page pagination parameters to filter the results.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`order_by` Query	String	Sort results by the specified field Allowed values: `id`, `username` Default: `id`
`sort` Query	String	Sort results in ascending or descending order Allowed values: `asc`, `desc` Default: `desc`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 Group not found	—

Create a group service account

POST /api/v4/groups/{id}/service_accounts

Creates a service account in a specified group.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group

Request body (application/json)

Property	Type	Description
`email`	String	Email address of the user account. If omitted when creating a new service account, generates an email address prefixed with `service_account_group_`. Custom email addresses require confirmation, unless the group has a matching verified domain or email confirmation settings are turned off
`name`	String	Name of the user. If omitted when creating a new service account, uses `Service account user`
`username`	String	Username of the user account. If omitted when creating a new service account, generates a username prefixed with `service_account_group_`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 Group not found	—

Get a single group service account

GET /api/v4/groups/{id}/service_accounts/{user_id}

Gets a specified service account in a specified group.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`user_id` Path, required	Integer	ID of the service account

Responses

Code	Description	Schema
`200`	OK	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 User not found	—

Update a group service account

PATCH /api/v4/groups/{id}/service_accounts/{user_id}

Update a specified group service account.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`user_id` Path, required	Integer	ID of the service account

Request body (application/json)

Property	Type	Description
`email`	String	Email address of the user account. If omitted when creating a new service account, generates an email address prefixed with `service_account_group_`. Custom email addresses require confirmation, unless the group has a matching verified domain or email confirmation settings are turned off
`name`	String	Name of the user. If omitted when creating a new service account, uses `Service account user`
`username`	String	Username of the user account. If omitted when creating a new service account, generates a username prefixed with `service_account_group_`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 User not found	—

Delete a group service account

DELETE /api/v4/groups/{id}/service_accounts/{user_id}

Deletes a specified group service account. Available only for group Owners and administrators.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`user_id` Path, required	Integer	ID of the service account
`hard_delete` Query	Boolean	If `true`, contributions that would usually be moved to a ghost user are deleted instead, along with groups owned solely by this service account

Responses

Code	Description	Schema
`204`	Resource deleted	—
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 Group not found	—

List all personal access tokens for a group service account

GET /api/v4/groups/{id}/service_accounts/{user_id}/personal_access_tokens

Lists all personal access tokens for a specified group service account

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`revoked` Query	Boolean	If `true`, only returns revoked tokens. If `false`, only returns tokens that are not revoked Example: `false`
`state` Query	String	Return tokens with the specified state Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Return tokens created on or before the specified time Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Return tokens created on or after the specified time Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Return tokens last used on or before the specified time Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Return tokens last used on or after the specified time Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Return tokens that expire before the specified date Example: `2022-01-01`
`expires_after` Query	String (date)	Return tokens that expire on or after the specified date Example: `2021-01-01`
`search` Query	String	Return tokens that include the specified value in their name Example: `token`
`sort` Query	String	Sort results by the specified field and direction. Possible values are `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, and `name_desc` Example: `created_desc`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`user_id` Path, required	Integer	ID of the service account

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalAccessToken
`400`	Bad Request	—
`401`	401 Unauthorized	—
`403`	Forbidden	—
`404`	404 Group Not Found	—

Create a personal access token for a group service account

POST /api/v4/groups/{id}/service_accounts/{user_id}/personal_access_tokens

Creates a personal access token for a specified group service account. Available only for group Owners and administrators. This feature was introduced in GitLab 16.1.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`user_id` Path, required	Integer	ID of the service account

Request body (application/json)

Property	Type	Description
`description`	String	Description of the access token. Limited to 255 characters Example: `A token used for k8s`
`expires_at`	String (date)	Expiration date of the access token in ISO format (YYYY-MM-DD). If undefined, the date is set to the maximum allowable lifetime limit Example: `2021-01-31`
`name` Required	String	Name of the access token Example: `My token`
`scopes` Required	Array of strings	Array of approved scopes. For a list of possible values, see access token scopes

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

Revoke a personal access token for a group service account

DELETE /api/v4/groups/{id}/service_accounts/{user_id}/personal_access_tokens/{token_id}

Revokes a specified personal access token for a group service account.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`token_id` Path, required	Integer	ID of the personal access token
`user_id` Path, required	Integer	ID of the service account

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—

Rotate a personal access token for a group service account

POST /api/v4/groups/{id}/service_accounts/{user_id}/personal_access_tokens/{token_id}/rotate

Rotates a specified personal access token for a group service account. This revokes the existing token and creates a token with the same name, description, and scopes.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`token_id` Path, required	Integer	ID of the personal access token
`user_id` Path, required	Integer	ID of the service account

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	Date when the access token expires. Introduced in GitLab 17.9. If omitted, the new token expires one week after rotation when token expiry is enforced, and does not expire otherwise Example: `2021-01-31`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

List all project service accounts

GET /api/v4/projects/{id}/service_accounts

Lists all service accounts in a specified project. Use the page and per_page pagination parameters to filter the results.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`order_by` Query	String	Attribute to sort by Allowed values: `id`, `username` Default: `id`
`sort` Query	String	Order of sorting Allowed values: `asc`, `desc` Default: `desc`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 Project not found	—

Create a project service account

POST /api/v4/projects/{id}/service_accounts

Creates a service account in a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`email`	String	Custom email address for the user
`name`	String	Name of the user
`username`	String	Username of the user

Responses

Code	Description	Schema
`201`	Created	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 Project not found	—

Get a single project service account

GET /api/v4/projects/{id}/service_accounts/{user_id}

Gets a specified service account in a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`user_id` Path, required	Integer	The ID of the service account

Responses

Code	Description	Schema
`200`	OK	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 User not found	—

Update a project service account

PATCH /api/v4/projects/{id}/service_accounts/{user_id}

Update a specified project service account.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`user_id` Path, required	Integer	The ID of the service account

Request body (application/json)

Property	Type	Description
`email`	String	Custom email address for the user
`name`	String	Name of the user
`username`	String	Username of the user

Responses

Code	Description	Schema
`200`	OK	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 User not found	—

Delete a project service account

DELETE /api/v4/projects/{id}/service_accounts/{user_id}

Deletes a specified project service account. Available only for project Owners, Maintainers, and administrators.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`user_id` Path, required	Integer	The ID of the service account
`hard_delete` Query	Boolean	Whether to remove a user’s contributions

Responses

Code	Description	Schema
`204`	No Content	—
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 Project not found	—

List all personal access tokens for a project service account

GET /api/v4/projects/{id}/service_accounts/{user_id}/personal_access_tokens

Lists all personal access tokens for a specified project service account

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`revoked` Query	Boolean	If `true`, only returns revoked tokens. If `false`, only returns tokens that are not revoked Example: `false`
`state` Query	String	Return tokens with the specified state Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Return tokens created on or before the specified time Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Return tokens created on or after the specified time Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Return tokens last used on or before the specified time Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Return tokens last used on or after the specified time Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Return tokens that expire before the specified date Example: `2022-01-01`
`expires_after` Query	String (date)	Return tokens that expire on or after the specified date Example: `2021-01-01`
`search` Query	String	Return tokens that include the specified value in their name Example: `token`
`sort` Query	String	Sort results by the specified field and direction. Possible values are `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, and `name_desc` Example: `created_desc`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`user_id` Path, required	Integer	The ID of the service account

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalAccessToken
`400`	Bad Request	—
`401`	401 Unauthorized	—
`403`	Forbidden	—
`404`	404 Project Not Found	—

Create a personal access token for a project service account

POST /api/v4/projects/{id}/service_accounts/{user_id}/personal_access_tokens

Creates a personal access token for a specified project service account. Available only for project Owners, Maintainers, and administrators.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`user_id` Path, required	Integer	The ID of the service account

Request body (application/json)

Property	Type	Description
`description`	String	Description of the access token. Limited to 255 characters Example: `A token used for k8s`
`expires_at`	String (date)	Expiration date of the access token in ISO format (YYYY-MM-DD). If undefined, the date is set to the maximum allowable lifetime limit Example: `2021-01-31`
`name` Required	String	Name of the access token Example: `My token`
`scopes` Required	Array of strings	The array of scopes of the personal access token

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

Revoke a personal access token for a project service account

DELETE /api/v4/projects/{id}/service_accounts/{user_id}/personal_access_tokens/{token_id}

Revokes a specified personal access token for a project service account.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`token_id` Path, required	Integer	The ID of the personal access token
`user_id` Path, required	Integer	The ID of the service account

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—

Rotate a personal access token for a project service account

POST /api/v4/projects/{id}/service_accounts/{user_id}/personal_access_tokens/{token_id}/rotate

Rotates a specified personal access token for a project service account. This revokes the existing token and creates a token with the same name, description, and scopes.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`token_id` Path, required	Integer	The ID of the personal access token
`user_id` Path, required	Integer	The ID of the service account

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	The expiration date of the token Example: `2021-01-31`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

List all instance service accounts

GET /api/v4/service_accounts

Lists all instance service accounts. Use the page and per_page pagination parameters to filter the results.

Parameters

Name	Type	Description
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`order_by` Query	String	Attribute to sort by Allowed values: `id`, `username` Default: `id`
`sort` Query	String	Order of sorting Allowed values: `asc`, `desc` Default: `desc`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—

Create an instance service account

POST /api/v4/service_accounts

Creates an instance service account.

Request body (application/json)

Property	Type	Description
`email`	String	Custom email address for the user
`external`	Boolean	Flag indicating the user is an external user
`name`	String	Name of the user
`username`	String	Username of the user

Responses

Code	Description	Schema
`201`	Created	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—

Update an instance service account

PATCH /api/v4/service_accounts/{user_id}

Updates a specified instance service account.

Parameters

Name	Type	Description
`user_id` Path, required	Integer	The ID of the service account user

Request body (application/json)

Property	Type	Description
`email`	String	Custom email address for the user
`external`	Boolean	Flag indicating the user is an external user
`name`	String	Name of the user
`username`	String	Username of the user

Responses

Code	Description	Schema
`200`	OK	APIEntitiesServiceAccount
`400`	400 Bad request	—
`401`	401 Unauthorized	—
`403`	403 Forbidden	—
`404`	404 Not found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesPersonalAccessToken

Property	Type	Description
`active`	Boolean	—
`created_at`	String (date-time)	—
`description`	String	Example: `Token to manage api`
`expires_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`granular`	Boolean	—
`granular_scopes`	Array of APIEntitiesPersonalAccessTokenGranularScope	—
`id`	Integer (int64)	Example: `2`
`last_used_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`last_used_ips`	Array of strings	The five most recent unique IP addresses that have authenticated with this token. When the limit is reached, the oldest IP address is removed. The list updates once per minute per token Example: `["127.0.0.1","127.0.0.2","127.0.0.3"]`
`name`	String	Example: `John Doe`
`revoked`	Boolean	—
`scopes`	Array	Example: `["api"]`
`user_id`	Integer (int64)	Example: `3`

APIEntitiesPersonalAccessTokenGranularScope

Property	Type	Description
`access`	String	Example: `personal_projects`
`group_id`	Integer (int64)	Example: `5`
`permissions`	Array	Example: `["read_job"]`
`project_id`	Integer (int64)	Example: `3`

APIEntitiesPersonalAccessTokenWithToken

Property	Type	Description
`active`	Boolean	—
`created_at`	String (date-time)	—
`description`	String	Example: `Token to manage api`
`expires_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`granular`	Boolean	—
`granular_scopes`	Array of APIEntitiesPersonalAccessTokenGranularScope	—
`id`	Integer (int64)	Example: `2`
`last_used_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`last_used_ips`	Array of strings	The five most recent unique IP addresses that have authenticated with this token. When the limit is reached, the oldest IP address is removed. The list updates once per minute per token Example: `["127.0.0.1","127.0.0.2","127.0.0.3"]`
`name`	String	Example: `John Doe`
`revoked`	Boolean	—
`scopes`	Array	Example: `["api"]`
`token`	String	—
`user_id`	Integer (int64)	Example: `3`

APIEntitiesServiceAccount

Property	Type	Description
`email`	String	Example: `service_account@example.com`
`external`	Boolean	Example: `true`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`unconfirmed_email`	String	Example: `updated_service_account@example.com`
`username`	String	Example: `admin`

List all group service accounts

Create a group service account

Get a single group service account

Update a group service account

Delete a group service account

List all personal access tokens for a group service account

Create a personal access token for a group service account

Revoke a personal access token for a group service account

Rotate a personal access token for a group service account

List all project service accounts

Create a project service account

Get a single project service account

Update a project service account

Delete a project service account

List all personal access tokens for a project service account

Create a personal access token for a project service account

Revoke a personal access token for a project service account

Rotate a personal access token for a project service account

List all instance service accounts

Create an instance service account

Update an instance service account

Schemas

APIEntitiesPersonalAccessToken

APIEntitiesPersonalAccessTokenGranularScope

APIEntitiesPersonalAccessTokenWithToken

APIEntitiesServiceAccount

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC compliance report

Thank you

Error

Request partner program details

Request received

Error